app/kb/procedures/render.mjs

Functions

Imports

It imports app/kb/procedures/key-resources.mjs, app/kb/procedures/lineage.mjs, app/kb/procedures/marks.mjs, app/kb/procedures/parse.mjs, app/kb/procedures/proof.mjs, app/kb/procedures/taxonomy.mjs, app/kb/procedures/validate.mjs, app/kb/registry/align.mjs, app/kb/registry/catalog.mjs, app/lib/phage-tools.mjs, app/lib/search/records.mjs. Imported by app/components/procedure-materials.tsx, app/components/procedure-primers.tsx, app/components/procedure-steps.tsx, app/components/procedure.tsx, app/db/procedure-versions.ts, app/db/procedures.ts, app/kb/procedures/compile.mjs, app/kb/procedures/lineage.server.ts, app/kb/procedures/proof.server.ts, app/kb/procedures/route.ts, app/kb/procedures/save.server.ts, app/kb/registry/host.server.ts.

Source

1// Turns a parsed, validated procedure into the record D1 stores and the page draws: every markdown
2// fragment rendered to HTML through the site's own pipeline (so links pass the same URL allowlist as a
3// post), every gap left out, and the quantities a reader can scale left as numbered slots in the HTML.
4// The markdown twin and the search inputs are derived here too, from the same parse, so a machine and a
5// person read the same facts.
6//
7// `renderBody` is passed in, not imported: the pipeline is 4 MB, so the Worker loads it lazily
8// (load-pipeline.server.ts) and a Node script imports it directly.
9
10import GithubSlugger from "github-slugger";
11
12import { TOOLS } from "../../lib/phage-tools.mjs";
13import { productsForRows } from "../registry/align.mjs";
14import { itemPath } from "../registry/catalog.mjs";
15import { plainText } from "../../lib/search/records.mjs";
16import { keyResources, keyResourcesMarkdown } from "./key-resources.mjs";
17import { proofFromFile } from "./proof.mjs";
18import { formatQuantity, readConditions, segmentText } from "./marks.mjs";
19import { statusLabel } from "./taxonomy.mjs";
20import { allSteps, PLATFORMS, procedurePath, readCalcs } from "./parse.mjs";
21import { HOWTO_TYPES } from "./validate.mjs";
22import { storedLineage } from "./lineage.mjs";
23
24/** The slot a scalable quantity leaves in a step's HTML, filled at request time (fillQuantities). */
25const SLOT = (/** @type {number} */ i) => `QZQ${i}QZQ`;
26const SLOT_PATTERN = /QZQ(\d+)QZQ/g;
27
28const GAP = /^MISSING:/;
29
30/** A heading as the pipeline writes it: rehype-slug's id, then the autolink inside. */
31const HEADING = /<h([1-6]) id="([^"]+)">([\s\S]*?)<\/h\1>/g;
32
33/**
34 * The ids of the sections the components draw from the front matter (ProcedureView), so a prose
35 * heading with the same words takes the -1 suffix rather than the fixed section's id.
36 *
37 * @param {unknown} profile
38 */
39export function fixedSectionIds(profile) {
40  const materials = profile === "recipe" ? "ingredients" : profile === "computational" ? "software-and-data" : "reagents";
41  const fixed = [materials, "equipment", "primers", "troubleshooting", "expected-results", "limitations", "references", "proof-of-use", "version-history", "cite-this-procedure", "key-resources"];
42  // A how-to's own sections (S2, S1), after the shared ones so no protocol's prose heading changes its id.
43  return profile === "computational" ? [...fixed, "overview", "questions", "objectives", "key-points", "explanation"] : fixed;
44}
45
46/**
47 * The value, or null when it is a recorded gap or absent.
48 *
49 * @template T
50 * @param {T} value
51 * @returns {T | null}
52 */
53function known(value) {
54  if (value === undefined || value === null || value === "") return null;
55  if (typeof value === "string" && GAP.test(value)) return null;
56  return value;
57}
58
59/** @param {unknown} v */
60const list = (v) => (Array.isArray(v) ? v : v === undefined || v === null ? [] : [v]);
61
62/**
63 * @typedef {(input: { file: string, body: string, resolveImage: (src: string) => Promise<any> }) =>
64 *   Promise<{ html: string, toc: Array<{ depth: number, id: string, text: string }>, blockedUrls: Array<{ url: string }> }>} RenderBody
65 */
66
67/**
68 * A primer as a protocol carries it: the lab registry's own facts about it, read when the protocol is compiled and stored
69 * in the record, so the page, the sheet, the twin and a frozen version all print the same sequence, and the protocol's
70 * file holds none (docs/REGISTRY.md). Its Tm and length are computed from the sequence where they are shown.
71 *
72 * @typedef {{ id: string, name: string, status: "published" | "draft", set: string | null, direction: string | null, sequence: string | null, reference: string | null, publishedIn?: string | null }} StoredPrimer
73 */
74
75/**
76 * A host strain as a protocol carries it: the lab registry's stated facts about it, read when the protocol is compiled and
77 * stored in the record, so the page, the twin and a frozen version name one strain and the protocol's file types none.
78 *
79 * A reagent as a protocol carries it: the lab registry's name for it, read when the protocol is compiled, so a material that
80 * names a reagent shows the registry's name and links its page and a frozen version keeps the name it was published with.
81 *
82 * An equipment item as a protocol carries it: the registry's stated facts (who makes it, and a centrifuge's rotor, or that the rotor
83 * is a recorded gap), read when the protocol is compiled, so the protocol's Equipment table and twin say as it was published.
84 *
85 * @typedef {{ id: string, name: string, status: "published" | "draft", manufacturer: string | null, rotor: string | null, rotorGap: boolean }} StoredEquipment
86 *
87 * @typedef {{ id: string, name: string, status: "published" | "draft", preparedInLab: boolean, supplier: string | null, catalogNumber: string | null, productUrl: string | null, recipe: string | null }} StoredReagent
88 *
89 * @typedef {{ id: string, name: string, status: "published" | "draft", organism: string | null, strain: string | null, collection: string | null, collectionNumber: string | null }} StoredStrain
90 */
91
92/**
93 * Where a reagent comes from, in the words a protocol's table and twin use: a bought reagent's supplier and catalog number, linked to
94 * its product page where there is one; a reagent prepared in the lab, linked to its recipe where one exists.
95 *
96 * @param {StoredReagent} reagent
97 * @returns {{ text: string, href: string | null }}
98 */
99export function reagentSource(reagent) {
100  if (reagent.preparedInLab) {
101    return { text: reagent.recipe ? "Prepared in the lab (recipe)" : "Prepared in the lab", href: reagent.recipe ? `/recipes/${reagent.recipe}` : null };
102  }
103  const text = [reagent.supplier, reagent.catalogNumber].filter(Boolean).join(", ");
104  return { text: text || "Not recorded", href: reagent.productUrl };
105}
106
107/**
108 * @param {{
109 *   slug: string,
110 *   parsed: import("./parse.mjs").ParsedProcedure,
111 *   gaps: Array<{ field: string, reason: string }>,
112 *   renderBody: RenderBody,
113 *   resolveImage?: (src: string) => Promise<{ width: number, height: number }>,
114 *   primerRows?: StoredPrimer[],
115 *   strainRows?: Array<StoredStrain & { path: string }>,
116 *   organismNames?: Record<string, string>,
117 *   reagentRows?: StoredReagent[],
118 *   equipmentRows?: StoredEquipment[],
119 * }} input
120 */
121export async function renderProcedure({ slug, parsed, gaps, renderBody, resolveImage, primerRows, strainRows, organismNames, reagentRows, equipmentRows }) {
122  const file = procedurePath(slug);
123  const d = parsed.data;
124  const refuseImage = async (/** @type {string} */ src) => {
125    throw new Error(`${file}: an image in prose ("${src}") is not supported; recipes carry photos on a step's own line`);
126  };
127
128  /**
129   * @param {unknown} markdown
130   * @param {{ inline?: boolean }} [opts]
131   */
132  const md = async (markdown, opts = {}) => {
133    if (typeof markdown !== "string" || !markdown.trim() || GAP.test(markdown)) return null;
134    const out = await renderBody({ file, body: markdown, resolveImage: refuseImage });
135    if (out.blockedUrls.length > 0) {
136      throw new Error(`${file}: the URL allowlist refused ${out.blockedUrls.map((b) => b.url).join(", ")}`);
137    }
138    const html = out.html.trim();
139    if (!opts.inline) return html;
140    const single = /^<p>([\s\S]*)<\/p>$/.exec(html);
141    return single && !single[1]?.includes("<p>") ? (single[1] ?? "") : html;
142  };
143
144  /** @param {{ src: string, alt: string }} photo */
145  const photo = async (photo) => {
146    if (!resolveImage) return { src: photo.src, alt: photo.alt, width: null, height: null };
147    const size = await resolveImage(photo.src);
148    return { src: photo.src, alt: photo.alt, width: size.width, height: size.height };
149  };
150
151  /** @param {unknown} value */
152  const inlineList = async (value) =>
153    /** @type {string[]} */ ((await Promise.all(list(known(value)).map((/** @type {string} */ x) => md(x, { inline: true })))).filter(Boolean));
154
155  const materialsByName = new Map(list(d.materials).map((/** @type {any} */ m) => [String(m.name).toLowerCase(), m]));
156
157  /** @param {import("./parse.mjs").Step} step */
158  const renderStep = async (step) => {
159    /** @type {Array<{ name: string, amount: string, unit: string, fixed: boolean, min: number | null, max: number | null }>} */
160    const quantities = [];
161    /** @type {Array<{ name: string, display: string, amount: string | null }>} */
162    const materials = [];
163    /** @type {string[]} */
164    const equipment = [];
165    /** @type {Array<{ label: string, text: string, min: number | null, max: number | null, unit: string }>} */
166    const timers = [];
167    let words = "";
168    for (const seg of step.segments) {
169      if (seg.type === "material") {
170        materials.push({
171          name: seg.name,
172          display: seg.display,
173          amount: seg.quantity ? formatQuantity(seg.quantity) : null,
174        });
175        if (seg.quantity) {
176          quantities.push({
177            // Which ingredient the amount is of, so a recipe can show it in other units (recipe-views.mjs).
178            name: seg.name,
179            amount: seg.quantity.amount,
180            unit: seg.quantity.unit,
181            fixed: seg.quantity.fixed,
182            min: seg.quantity.min,
183            max: seg.quantity.max,
184          });
185          words += `${SLOT(quantities.length - 1)} of ${seg.display}`;
186          continue;
187        }
188      } else if (seg.type === "equipment") {
189        equipment.push(seg.name);
190      } else if (seg.type === "timer" && seg.quantity) {
191        timers.push({
192          label: seg.label,
193          text: formatQuantity(seg.quantity),
194          min: seg.quantity.min,
195          max: seg.quantity.max,
196          unit: seg.quantity.unit,
197        });
198      }
199      words += segmentText(seg);
200    }
201    const text = step.segments.map((s) => segmentText(s)).join("");
202    const { temperatures, spins } = readConditions(text);
203    const flagHtml = async (/** @type {string[]} */ items) =>
204      /** @type {string[]} */ ((await Promise.all(items.map((t) => md(t)))).filter(Boolean));
205    return {
206      number: step.number,
207      html: await md(words, { inline: true }),
208      text: plainText(text),
209      quantities,
210      materials,
211      equipment,
212      timers,
213      temperatures,
214      spins,
215      spin: step.flags.spin.filter((s) => !GAP.test(s)),
216      critical: await flagHtml(step.flags.critical),
217      pause: await flagHtml(step.flags.pause),
218      why: await flagHtml(step.flags.why),
219      expect: await flagHtml(step.flags.expect),
220      troubleshooting: step.flags.troubleshooting,
221      calculators: readCalcs(step.flags.calc),
222      // A tutorial's challenges, each with the solution the parse paired with it (S5).
223      challenges: await Promise.all(
224        step.flags.challenge.map(async (c, i) => ({ html: await md(c), solutionHtml: await md(step.flags.solution[i] ?? "") })),
225      ),
226      commands: step.commands,
227      photos: await Promise.all(step.photos.map(photo)),
228    };
229  };
230
231  // One slugger for the whole page, as rehype-slug has for a whole post: each prose block is rendered
232  // on its own, so a heading repeated across blocks would otherwise keep one id twice. The sections the
233  // components draw themselves take their ids first.
234  const slugger = new GithubSlugger();
235  for (const id of fixedSectionIds(d.profile)) slugger.slug(id);
236  /** @type {Array<{ depth: number, id: string, text: string }>} */
237  const toc = [];
238  /** @type {Array<{ id: string, title: string, blocks: Array<{ type: "prose", html: string } | { type: "steps", steps: Array<Awaited<ReturnType<typeof renderStep>>> }> }>} */
239  const sections = [];
240  for (const section of parsed.sections) {
241    const sectionId = section.custom ? section.id : slugger.slug(section.title);
242    toc.push({ depth: 2, id: sectionId, text: section.title });
243    /** @type {(typeof sections)[number]["blocks"]} */
244    const blocks = [];
245    for (const block of section.blocks) {
246      if (block.type === "prose") {
247        const out = await renderBody({ file, body: block.markdown, resolveImage: refuseImage });
248        if (out.blockedUrls.length > 0) {
249          throw new Error(`${file}: the URL allowlist refused ${out.blockedUrls.map((b) => b.url).join(", ")}`);
250        }
251        const html = out.html.replace(HEADING, (_all, level, id, inner) => {
252          const text = String(inner).replace(/<[^>]+>/g, "").replace(/#$/, "").trim();
253          const unique = slugger.slug(text);
254          if (Number(level) === 3) toc.push({ depth: 3, id: unique, text });
255          return `<h${level} id="${unique}">${String(inner).replace(`href="#${id}"`, `href="#${unique}"`)}</h${level}>`;
256        });
257        blocks.push({ type: "prose", html });
258      } else {
259        blocks.push({ type: "steps", steps: await Promise.all(block.steps.map(renderStep)) });
260      }
261    }
262    sections.push({ id: sectionId, title: section.title, blocks });
263  }
264
265  const reagentsById = new Map((reagentRows ?? []).map((r) => [r.id, r]));
266  const materials = await Promise.all(
267    list(d.materials).map(async (/** @type {any} */ m) => ({
268      name: m.name,
269      // A reagent of the registry is shown by the registry's name, linked, so the protocol types no product name for it.
270      display: m.display ?? reagentsById.get(m.reagent)?.name ?? m.name,
271      // What the registry says of it, as it was when the protocol was compiled: the table shows where it comes from.
272      reagent: reagentsById.get(m.reagent) ?? null,
273      group: m.group ?? null,
274      kind: m.kind ?? null,
275      version: known(m.version),
276      stock: list(m.stock).filter((s) => known(s) !== null).map(String),
277      final: known(m.final),
278      amount: known(m.amount),
279      per: known(m.per),
280      solution: m.solution ?? null,
281      noteHtml: await md(m.note, { inline: true }),
282      // A recipe's grams in one cup of it, where the recipe states it: the only way its volume is shown as weight (DECIDE 7).
283      gramsPerCup: typeof m.grams_per_cup === "number" && m.grams_per_cup > 0 ? m.grams_per_cup : null,
284      /** @type {{ amount: string, unit: string, fixed: boolean, min: number | null, max: number | null } | null} */
285      quantity: null,
286    })),
287  );
288
289  // A material with no amount of its own takes the sum of what its marks use, when they share a unit and
290  // none is fixed, so a recipe's shopping list scales with its servings.
291  /** @param {string} name */
292  const markedTotal = (name) => {
293    const qs = allSteps(parsed).flatMap((s) =>
294      s.segments.flatMap((seg) => (seg.type === "material" && seg.name.toLowerCase() === name.toLowerCase() && seg.quantity ? [seg.quantity] : [])),
295    );
296    const unit = qs[0]?.unit;
297    if (qs.length === 0 || qs.some((q) => q.min === null || q.max !== q.min || q.unit !== unit)) return null;
298    const sum = qs.reduce((n, q) => n + (q.min ?? 0), 0);
299    return { amount: String(sum), unit: unit ?? "", fixed: qs.every((q) => q.fixed), min: sum, max: sum };
300  };
301  for (const m of materials) {
302    if (m.amount === null) m.quantity = markedTotal(m.name);
303  }
304
305  // A recipe may leave its ingredients undeclared: the marks are the list, in order of first use.
306  if (d.profile === "recipe") {
307    for (const step of allSteps(parsed)) {
308      for (const seg of step.segments) {
309        if (seg.type !== "material" || materialsByName.has(seg.name.toLowerCase())) continue;
310        materialsByName.set(seg.name.toLowerCase(), { name: seg.name });
311        materials.push({
312          name: seg.name,
313          display: seg.name,
314          reagent: null,
315          group: null,
316          kind: null,
317          version: null,
318          stock: [],
319          final: null,
320          amount: null,
321          per: null,
322          solution: null,
323          noteHtml: null,
324          gramsPerCup: null,
325          quantity: markedTotal(seg.name),
326        });
327      }
328    }
329  }
330
331  const troubleshooting = await Promise.all(
332    list(d.troubleshooting).map(async (/** @type {any} */ row) => ({
333      id: row.id,
334      step: String(row.step),
335      problem: await md(row.problem, { inline: true }),
336      reason: await md(row.reason, { inline: true }),
337      solution: await md(row.solution, { inline: true }),
338    })),
339  );
340
341  const image = known(d.image);
342  const record = {
343    slug,
344    profile: /** @type {"protocol" | "recipe" | "computational"} */ (d.profile),
345    path: String(d.path),
346    title: String(d.title),
347    seoTitle: String(d.seo_title),
348    description: String(d.description),
349    draft: d.draft === true,
350    version: known(d.version) === null ? null : String(d.version),
351    // Newest first; the first entry is the version the page is at (validate.mjs). Empty until one is written.
352    history: await Promise.all(
353      list(known(d.history)).map(async (/** @type {any} */ h) => ({
354        version: String(h.version),
355        date: String(h.date),
356        summaryHtml: await md(h.summary, { inline: true }),
357        doi: h.doi ? String(h.doi) : null,
358      })),
359    ),
360    updated: known(d.updated),
361    // What the protocol library filters and lists by (taxonomy.mjs); ids, so the page draws the words.
362    methods: /** @type {string[]} */ (list(known(d.method))),
363    organisms: /** @type {string[]} */ (list(known(d.organism))),
364    // The words for each organism id, read from the lab registry when the protocol was compiled (docs/REGISTRY.md).
365    organismNames: organismNames ?? {},
366    targets: /** @type {string[]} */ (list(known(d.target))),
367    courses: /** @type {string[]} */ (list(known(d.course))),
368    // The library's "Start here" position, or null: stored, never inferred.
369    startHere: known(d.start_here) === null ? null : Number(d.start_here),
370    // Proof of use: slugs of the papers that used the method and the phages it produced, or null. Stored, never inferred.
371    proofOfUse: proofFromFile(known(d.proof_of_use)),
372    firstUsed: known(d.first_used),
373    lastRun: known(d.last_run),
374    status: known(d.status) === null ? null : statusLabel(String(d.status)),
375    // The procedure this one was copied from with the editor's Duplicate (validate.mjs checks the shape), or null.
376    forkedFrom:
377      d.forked_from && typeof d.forked_from === "object"
378        ? { slug: String(d.forked_from.slug), version: d.forked_from.version ? String(d.forked_from.version) : null }
379        : null,
380    time: {
381      total: known(d.time?.total),
382      handsOn: known(d.time?.hands_on),
383    },
384    introHtml: await md(parsed.intro),
385    basedOn: list(known(d.based_on)).map((/** @type {any} */ s) => ({
386      citation: String(s.citation),
387      for: String(s.for),
388      doi: s.doi ? String(s.doi) : null,
389      url: s.url ? String(s.url) : null,
390    })),
391    references: /** @type {string[]} */ (
392      (await Promise.all(list(known(d.references)).map((/** @type {string} */ r) => md(r, { inline: true })))).filter(Boolean)
393    ),
394    materials,
395    equipment: await Promise.all(
396      list(d.equipment).map(async (/** @type {any} */ e) => {
397        const item = typeof e === "object" && e !== null ? ((equipmentRows ?? []).find((r) => r.id === e.equipment) ?? null) : null;
398        return typeof e === "string" ? { name: e, noteHtml: null, item } : { name: String(e.name), noteHtml: await md(e.note, { inline: true }), item };
399      }),
400    ),
401    troubleshooting,
402    expectedResultsHtml: await md(d.expected_results),
403    limitationsHtml: await md(d.limitations),
404    sections,
405    toc,
406    // Protocol.
407    scale: known(d.scale) ? { count: Number(d.scale.count), unit: String(d.scale.unit) } : null,
408    biosafety: known(d.biosafety) && d.biosafety !== "not applicable" ? d.biosafety : null,
409    // Dustin's to set per protocol. A gap reads as null, so no page, twin or structured data ever carries "MISSING".
410    biosafetyLevel: /** @type {string | null} */ (known(d.biosafety_level)),
411    // The strains are the registry's: the names are computed from them, never typed in the protocol.
412    hostStrains: (strainRows ?? []).map((s) => ({ id: s.id, name: s.name, path: s.path, organism: s.organism, strain: s.strain, collection: s.collection, collectionNumber: s.collectionNumber })),
413    hostStrain: (strainRows ?? []).length > 0 ? (strainRows ?? []).map((s) => s.name).join("; ") : null,
414    solutions: list(d.solutions).map((/** @type {any} */ s) => ({
415      id: s.id,
416      name: s.name,
417      components: list(s.components).map((/** @type {any} */ c) => ({
418        name: String(c.name),
419        final: known(c.final),
420        amount: known(c.amount),
421      })),
422      storage: known(s.storage),
423      shelfLife: known(s.shelf_life),
424    })),
425    // The registry's rows for the primers the file names, in the file's order (compile.mjs resolves them).
426    primers: (primerRows ?? []).map((p) => ({ id: p.id, name: p.name, set: p.set, direction: p.direction, sequence: p.sequence, reference: p.reference, publishedIn: p.publishedIn ?? null })),
427    cycling: Array.isArray(d.cycling) ? d.cycling : [],
428    // Recipe.
429    servings: known(d.servings) === null ? null : Number(d.servings),
430    cuisine: known(d.cuisine),
431    category: known(d.category),
432    diet: list(known(d.diet)).map(String),
433    prepTime: known(d.prep_time),
434    cookTime: known(d.cook_time),
435    image: image ? await photo(image) : null,
436    substitutions: await Promise.all(
437      list(d.substitutions).map(async (/** @type {any} */ s) => ({
438        for: String(s.for),
439        use: String(s.use),
440        noteHtml: await md(s.note, { inline: true }),
441      })),
442    ),
443    // Computational.
444    // Tutorial or how-to (S1), and a tutorial's questions, objectives and key points (S2), as the file states them.
445    howtoType: /** @type {keyof typeof HOWTO_TYPES | null} */ (d.profile === "computational" && Object.hasOwn(HOWTO_TYPES, d.type) ? d.type : null),
446    questions: await inlineList(d.questions),
447    objectives: await inlineList(d.objectives),
448    keyPoints: await inlineList(d.key_points),
449    explanation: list(known(d.explanation)).map((/** @type {any} */ e) => ({ title: String(e.title), url: String(e.url) })),
450    environmentHtml: await md(d.environment),
451    prerequisites: /** @type {string[]} */ (
452      (await Promise.all(list(known(d.prerequisites)).map((/** @type {string} */ p) => md(p, { inline: true })))).filter(Boolean)
453    ),
454    gaps,
455  };
456  return record;
457}
458
459/** @typedef {Awaited<ReturnType<typeof renderProcedure>>} ProcedureRecord */
460
461/**
462 * The scale factor a request asks for, or 1. A protocol scales its material totals by the count of its
463 * unit; a recipe scales its step amounts by servings.
464 *
465 * @param {ProcedureRecord} record
466 * @param {number | null} asked the count (protocol) or servings (recipe) in the URL
467 */
468export function scaleFactor(record, asked) {
469  if (!asked || !(asked > 0) || asked > 1000) return 1;
470  if (record.profile === "recipe" && record.servings) return asked / record.servings;
471  if (record.profile === "protocol" && record.scale) return asked / record.scale.count;
472  return 1;
473}
474
475/**
476 * The step's HTML with its quantity slots filled. A protocol's step amounts are per unit and never
477 * scale; a recipe's scale unless the file fixed them.
478 *
479 * @param {{ html: string | null, quantities: Array<{ name?: string, amount: string, unit: string, fixed: boolean, min: number | null, max: number | null }> }} step
480 * @param {number} factor
481 * @param {(q: { name?: string, amount: string, unit: string, fixed: boolean, min: number | null, max: number | null }) => string} [show] how a recipe shows an amount in the reader's units (recipe-views.mjs)
482 */
483export function fillQuantities(step, factor, show) {
484  return (step.html ?? "").replace(SLOT_PATTERN, (_all, i) => {
485    const q = step.quantities[Number(i)];
486    if (!q) return "";
487    return show ? show(q) : formatQuantity({ ...q, raw: "" }, factor);
488  });
489}
490
491/**
492 * The markdown twin: the same facts as the page, generated from the same file.
493 *
494 * @param {ProcedureRecord} record
495 * @param {import("./parse.mjs").ParsedProcedure} parsed
496 */
497export function procedureMarkdown(record, parsed) {
498  const d = parsed.data;
499  const out = [`# ${record.title}`, "", record.description, ""];
500  const facts = [
501    ["Type", record.howtoType ? HOWTO_TYPES[record.howtoType] : null],
502    ["Version", record.version],
503    ["Updated", record.updated],
504    ["First used", record.firstUsed],
505    ["Last run", record.lastRun],
506    ["Status", record.status],
507    ["Scale", record.scale ? `${record.scale.count} ${record.scale.unit}${record.scale.count === 1 ? "" : "s"}` : null],
508    ["Servings", record.servings],
509    ["Prep time", record.prepTime],
510    ["Cook time", record.cookTime],
511    ["Total time", record.time.total],
512    ["Hands-on time", record.time.handsOn],
513    // The parent's file name and version; the twin's route reads it out as the parent's title and address (lineage.mjs).
514    ["Based on", record.forkedFrom ? storedLineage(record.forkedFrom) : null],
515    ["Host strain", record.hostStrains.length > 0 ? record.hostStrains.map((s) => `[${s.name}](${s.path})`).join("; ") : null],
516    ["Biosafety level", record.biosafetyLevel],
517    [
518      "Biosafety",
519      record.biosafety
520        ? [record.biosafety.organism, record.biosafety.strain, record.biosafety.atcc ? `ATCC ${record.biosafety.atcc}` : null]
521            .filter(Boolean)
522            .join(", ")
523        : null,
524    ],
525  ].filter(([, v]) => v !== null && v !== undefined && v !== "");
526  for (const [k, v] of facts) out.push(`- ${k}: ${v}`);
527  if (facts.length) out.push("");
528  // A tutorial opens with what it answers and teaches (S2), as the page does.
529  const bullets = (/** @type {string} */ title, /** @type {unknown} */ value) => {
530    const items = list(known(value));
531    if (items.length) out.push(`## ${title}`, "", ...items.map((x) => `- ${x}`), "");
532  };
533  bullets("Questions", d.questions);
534  bullets("Objectives", d.objectives);
535  if (parsed.intro) out.push(parsed.intro, "");
536
537  if (record.basedOn.length) {
538    out.push("## Based on", "");
539    for (const s of record.basedOn) {
540      const link = s.doi ? ` (doi:${s.doi})` : s.url ? ` (${s.url})` : "";
541      out.push(`- ${s.citation}${link}: ${s.for}`);
542    }
543    out.push("");
544  }
545
546  const heading = record.profile === "recipe" ? "Ingredients" : record.profile === "computational" ? "Software and data" : "Reagents";
547  out.push(`## ${heading}`, "");
548  // The registry reagents the materials name, as the record baked them (the file holds only their ids).
549  const reagentOf = new Map(record.materials.map((m) => [m.name, m.reagent]));
550  for (const m of list(d.materials).length ? list(d.materials) : record.materials) {
551    const parts = [
552      known(m.amount) ? `${m.amount}${known(m.per) ? ` per ${m.per}` : ""}` : null,
553      list(m.stock).filter((s) => known(s) !== null).length ? `stock ${list(m.stock).filter((s) => known(s) !== null).join(" or ")}` : null,
554      known(m.final) ? `final ${m.final}` : null,
555      known(m.version) ? `version ${m.version}` : null,
556    ].filter(Boolean);
557    const note = known(m.note) ? ` ${m.note}` : "";
558    const reagent = reagentOf.get(m.name) ?? null;
559    const shown = m.display ?? reagent?.name ?? m.name;
560    if (reagent) {
561      const source = reagentSource(reagent);
562      parts.push(source.href ? `source [${source.text}](${source.href})` : `source ${source.text}`);
563    }
564    // A published reagent links its page, as the page's table does.
565    const named = reagent?.status === "published" ? `[${shown}](${itemPath("reagent", reagent.id)})` : shown;
566    out.push(`- ${named}${m.group ? ` (${m.group})` : ""}${parts.length ? `: ${parts.join("; ")}.` : ""}${note}`);
567  }
568  out.push("");
569  for (const s of record.solutions) {
570    out.push(`### ${s.name}`, "");
571    for (const c of s.components) out.push(`- ${c.name}${c.final ? `, ${c.final} final` : ""}${c.amount ? `, ${c.amount}` : ""}`);
572    if (s.storage) out.push(`- Storage: ${s.storage}`);
573    if (s.shelfLife) out.push(`- Shelf life: ${s.shelfLife}`);
574    out.push("");
575  }
576  if (record.equipment.length) {
577    out.push("## Equipment", "");
578    // The registry facts of each item, as the record baked them (the file holds only the ids).
579    const itemOf = new Map(record.equipment.map((e) => [e.name, e.item]));
580    for (const e of list(d.equipment)) {
581      const name = typeof e === "string" ? e : String(e.name);
582      const item = itemOf.get(name) ?? null;
583      const facts = item ? ` (${[`manufacturer ${item.manufacturer ?? "not recorded"}`, item.rotor ? `rotor ${item.rotor}` : item.rotorGap ? "rotor not recorded" : null].filter(Boolean).join("; ")})` : "";
584      const named = item?.status === "published" ? `[${name}](${itemPath("equipment", item.id)})` : name;
585      out.push(`- ${named}${facts}${typeof e === "string" || !e.note ? "" : `: ${e.note}`}`);
586    }
587    out.push("");
588  }
589  if (record.primers.length) {
590    const products = productsForRows(record.primers);
591    out.push("## Primers", "", "| Primer | Direction | Sequence (5′ to 3′) | Product (computed) |", "| --- | --- | --- | --- |");
592    for (const p of record.primers) {
593      const pair = products.get(p.id);
594      const sizes = pair ? [...new Set(pair.products.map((x) => x.length))].map((n) => `${n} bp`).join(" or ") : "";
595      out.push("| [" + p.name + "](/research/lab/primers/" + p.id + ") | " + (p.direction ?? "") + " | " + (p.sequence ? "`" + p.sequence + "`" : "") + " | " + sizes + " |");
596    }
597    out.push("");
598    const references = [...new Set([...products.values()].map((pair) => pair.reference.id))];
599    if (references.length > 0) out.push(`Product sizes are computed from where the primers bind ${references.join(", ")}, in that accession's coordinates.`, "");
600  }
601  out.push(...keyResourcesMarkdown(keyResources(record)));
602  if (known(d.environment)) out.push("## Environment", "", String(d.environment), "");
603  if (record.prerequisites.length) out.push("## Prerequisites", "", ...list(d.prerequisites).map((p) => `- ${p}`), "");
604
605  for (const section of parsed.sections) {
606    out.push(`## ${section.title}`, "");
607    for (const block of section.blocks) {
608      if (block.type === "prose") {
609        out.push(block.markdown, "");
610        continue;
611      }
612      for (const step of block.steps) {
613        out.push(`${step.number}. ${step.segments.map((s) => segmentText(s)).join("")}`);
614        const flag = (/** @type {string} */ name, /** @type {string[]} */ items) => {
615          for (const item of items) if (!GAP.test(item)) out.push(`   > ${name}: ${item.replace(/\n/g, "\n   > ")}`);
616        };
617        flag("Critical", step.flags.critical);
618        flag("Pause point", step.flags.pause);
619        flag("Spin", step.flags.spin);
620        flag("Why", step.flags.why);
621        flag("Expected", step.flags.expect);
622        for (const id of step.flags.troubleshooting) out.push(`   > Troubleshooting: see "${id}" below.`);
623        for (const c of readCalcs(step.flags.calc)) out.push(`   > Calculator: [${TOOLS[c.id]?.title}](${TOOLS[c.id]?.path})${Object.keys(c.values).length ? ` with ${Object.entries(c.values).map(([k, v]) => `${k} ${v}`).join(", ")}` : ""}`);
624        // Every platform's block, each under its name (S4): the page's tabs are a view of these.
625        for (const cmd of step.commands) {
626          if (cmd.platform) out.push("", `   ${PLATFORMS[/** @type {keyof typeof PLATFORMS} */ (cmd.platform)] ?? cmd.platform}:`);
627          out.push("", `   \`\`\`${cmd.lang}`, ...cmd.code.split("\n").map((l) => `   ${l}`), "   ```");
628          if (cmd.output !== null) {
629            out.push("", "   Expected output:", "", "   ```", ...cmd.output.split("\n").map((l) => `   ${l}`), "   ```");
630          }
631        }
632        for (const p of step.photos) out.push(`   ![${p.alt}](${p.src})`);
633        // A challenge and its solution, both: the page folds the solution away, and a machine reads it anyway.
634        step.flags.challenge.forEach((c, i) => {
635          out.push("", `   > Challenge: ${c.replace(/\n/g, "\n   > ")}`);
636          const solution = step.flags.solution[i];
637          if (solution) out.push("", `   > Solution: ${solution.replace(/\n/g, "\n   > ")}`);
638        });
639      }
640      out.push("");
641    }
642  }
643
644  bullets("Key points", d.key_points);
645  if (record.explanation.length) out.push("## Explanation", "", ...record.explanation.map((e) => `- [${e.title}](${e.url})`), "");
646
647  if (list(d.troubleshooting).length) {
648    out.push("## Troubleshooting", "", "| Step | Problem | Possible reason | Solution |", "| --- | --- | --- | --- |");
649    for (const r of list(d.troubleshooting)) {
650      const cell = (/** @type {unknown} */ v) => String(v).replace(/\|/g, "\\|").replace(/\n/g, " ");
651      out.push(`| ${cell(r.step)} | ${cell(r.problem)} | ${cell(r.reason)} | ${cell(r.solution)} |`);
652    }
653    out.push("");
654  }
655  if (known(d.expected_results)) out.push("## Expected results", "", String(d.expected_results), "");
656  if (known(d.limitations)) out.push("## Limitations", "", String(d.limitations), "");
657  if (list(d.substitutions).length) {
658    out.push("## Substitutions", "");
659    for (const s of list(d.substitutions)) out.push(`- For ${s.for}, use ${s.use}${s.note ? `: ${s.note}` : ""}`);
660    out.push("");
661  }
662  if (record.history.length) {
663    out.push("## Version history", "");
664    for (const h of list(d.history)) out.push(`- Version ${h.version}, ${h.date}: ${h.summary}${h.doi ? ` (doi:${h.doi})` : ""}`);
665    out.push("");
666  }
667  const refs = list(known(d.references));
668  if (refs.length) out.push("## References", "", ...refs.map((r) => `- ${r}`), "");
669  return `${out.join("\n").replace(/\n{3,}/g, "\n\n").trim()}\n`;
670}
671
672/**
673 * The search uid of the page at `path`: the one the page had when it was a content page, so a search
674 * link survives the move. Also what removing a procedure's search records is keyed by.
675 *
676 * @param {string} path
677 */
678export function procedureSearchUid(path) {
679  return `page:${path.slice(1).replaceAll("/", ":")}`;
680}
681
682/**
683 * What the search index takes for this procedure, in the shape recordsForPages reads, with the uid
684 * `procedureSearchUid` names.
685 *
686 * @param {ProcedureRecord} record
687 * @param {import("./parse.mjs").ParsedProcedure} parsed
688 */
689export function procedureSearchInput(record, parsed) {
690  const markdown = procedureMarkdown(record, parsed);
691  const sections = parsed.sections.map((section) => {
692    const body = section.blocks
693      .map((block) =>
694        block.type === "prose"
695          ? block.markdown
696          : block.steps
697              .map((s) => [s.segments.map((x) => segmentText(x)).join(""), ...s.flags.why, ...s.flags.critical].join(" "))
698              .join(" "),
699      )
700      .join(" ");
701    return { anchor: section.id, title: section.title, body: plainText(body) };
702  });
703  return {
704    url: record.path,
705    uid: procedureSearchUid(record.path),
706    title: record.title,
707    description: record.description,
708    intro: plainText(parsed.intro),
709    sections,
710    markdown,
711  };
712}