create-ailk 0.30.0 → 0.32.0

package/dist/lib/render-comparison.js

@@ -0,0 +1,573 @@
+/**
+ * The cutover comparison (#10648, spec
+ * docs/specs/10648-the-cutover-kit-frozen-inventory-spec.md D9).
+ *
+ * Per frozen page URL, at two viewports, in Chromium, on both origins: the
+ * render (a direct 200 that settles on the requested path, `render-verdict.ts`'s
+ * rule), the text of `main`, every JSON-LD script string for string, and a
+ * full-page screenshot compared pixel by pixel. Then a sweep: every frozen URL
+ * must answer 200 with no redirect. A DOM diff alone is never the evidence
+ * (roadmap § 9, rules/outcome-evidence.md): the pixels gate the verdict, and
+ * `comparison.md` links every before/after pair for the eye read.
+ *
+ * create-ailk has one runtime dependency, so nothing here imports Playwright:
+ * the PNG decode and diff are pure functions over buffers (`node:zlib` only),
+ * a page is reached only through the `ComparisonPage` slice it is handed, and
+ * `loadChromium` resolves the site's own Playwright at run time. Jest drives
+ * all of it without a browser.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { inflateSync } from "node:zlib";
+/** The two viewports every page is compared at. */
+export const VIEWPORTS = [
+    { name: "desktop", width: 1440, height: 900 },
+    { name: "mobile", width: 390, height: 844 },
+];
+/** How long one navigation may take before the render fails. */
+const NAVIGATION_TIMEOUT_MS = 60_000;
+/** How long one sweep request may take. */
+const SWEEP_TIMEOUT_MS = 15_000;
+/** Requests in flight at once, for a sweep or a crawl. */
+export const IN_FLIGHT = 4;
+/** The page's words: `main`'s rendered text, else `body`'s. */
+export const TEXT_EXPRESSION = '(() => { const root = document.querySelector("main") ?? document.body; return root ? root.innerText : ""; })()';
+/** Every JSON-LD script's text, in document order. */
+export const JSONLD_EXPRESSION = 'Array.from(document.querySelectorAll(\'script[type="application/ld+json"]\'), (s) => s.textContent ?? "")';
+const itemKey = (i) => `${i.kind}/${i.slug}`;
+/** `compareText`'s whitespace rule. */
+const collapse = (s) => s.replace(/\s+/g, " ").trim();
+/**
+ * Plain JS run in the after page, so no transform reaches it. Under the kind
+ * pull's position rule (#10734 D3) it removes exactly the reported items, or
+ * removes nothing and answers why: FAQs are the tail of the last `faq`
+ * section's items, matched by question; terms are the tail of their letter
+ * group in the last `glossary-index` section, matched by slug, and a letter
+ * group they leave empty goes with its nav link. A reason never carries an
+ * item's words.
+ */
+export const EXCLUDE_SOURCE = `function (document, exclude) {
+  var norm = function (s) { return String(s).replace(/\\s+/g, " ").trim(); };
+  var firstLine = function (el) {
+    var lines = String(el.innerText || "").split("\\n");
+    for (var i = 0; i < lines.length; i++) if (norm(lines[i]) !== "") return norm(lines[i]);
+    return "";
+  };
+  var last = function (selector) {
+    var all = document.querySelectorAll(selector);
+    return all.length === 0 ? null : all[all.length - 1];
+  };
+  var byTestId = function (root, id) {
+    return Array.from(root.querySelectorAll("[data-testid]")).filter(function (el) { return el.getAttribute("data-testid") === id; });
+  };
+  var faqs = exclude.filter(function (t) { return t.kind === "faq"; });
+  var terms = exclude.filter(function (t) { return t.kind === "term"; });
+  var items = [];
+  if (faqs.length > 0) {
+    var faq = last('[data-section="faq"]');
+    if (faq === null) return { refused: "no faq section" };
+    var all = Array.from(faq.querySelectorAll('[data-testid="faq-item-expanded"], [data-testid="faq-item-accordion"], [data-testid="faq-item-grid"]'));
+    var left = faqs.slice();
+    for (var i = Math.max(0, all.length - faqs.length); i < all.length; i++) {
+      var line = firstLine(all[i]);
+      var at = left.findIndex(function (t) { return norm(t.name) === line; });
+      if (at < 0) return { refused: "item " + (i + 1) + " of " + all.length + " in the last faq section is not a reported top-up" };
+      left.splice(at, 1);
+      items.push(all[i]);
+    }
+    if (left.length > 0) return { refused: "the last faq section has " + all.length + " item(s), fewer than its " + faqs.length + " top-up(s)" };
+  }
+  var glossary = null;
+  var termItems = [];
+  if (terms.length > 0) {
+    glossary = last('[data-section="glossary-index"]');
+    if (glossary === null) return { refused: "no glossary-index section" };
+    for (var j = 0; j < terms.length; j++) {
+      var links = byTestId(glossary, "glossary-index-term-" + terms[j].slug);
+      var li = links.length === 1 ? links[0].closest("li") : null;
+      if (li === null) return { refused: "term " + terms[j].slug + " is not shown once in the last glossary-index section" };
+      termItems.push(li);
+    }
+    for (var k = 0; k < terms.length; k++) {
+      var siblings = Array.from(termItems[k].parentElement.children);
+      var later = siblings.slice(siblings.indexOf(termItems[k]) + 1);
+      if (later.some(function (el) { return termItems.indexOf(el) < 0; })) {
+        return { refused: "term " + terms[k].slug + " is not at the tail of its letter group" };
+      }
+    }
+  }
+  items.forEach(function (el) { el.remove(); });
+  var lists = [];
+  termItems.forEach(function (el) {
+    if (lists.indexOf(el.parentElement) < 0) lists.push(el.parentElement);
+    el.remove();
+  });
+  lists.forEach(function (ul) {
+    if (ul.children.length > 0) return;
+    var group = ul.closest("section[data-letter]");
+    if (group === null) return;
+    var link = byTestId(glossary, "glossary-index-letter-" + group.getAttribute("data-letter"))[0];
+    group.remove();
+    if (link === undefined) return;
+    var nav = link.closest("nav");
+    link.remove();
+    if (nav !== null && nav.children.length === 0) nav.remove();
+  });
+  return { removed: exclude.map(function (t) { return t.kind + "/" + t.slug; }) };
+}`;
+/** The expression the after page evaluates: `EXCLUDE_SOURCE` called on a JSON literal. */
+export function exclusionExpression(exclude) {
+    return `(${EXCLUDE_SOURCE})(document, ${JSON.stringify(exclude)})`;
+}
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/**
+ * The after side's JSON-LD without the top-ups' nodes: per kind, the one array
+ * holding a matching node (a `Question` by `name`, a `DefinedTerm` by
+ * `termCode`) must end in exactly those nodes and keep one other. The script
+ * that changed is re-serialized with `serializeJsonLd`'s rule
+ * (`packages/schema/src/json-ld.ts`, restated: no runtime import); every other
+ * keeps its string. Anything else is `refused`, with the scripts untouched.
+ */
+export function excludeJsonLd(scripts, exclude) {
+    const parsed = scripts.map((script) => {
+        try {
+            return { value: JSON.parse(script) };
+        }
+        catch {
+            return undefined;
+        }
+    });
+    const changed = new Set();
+    for (const kind of ["faq", "term"]) {
+        const items = exclude.filter((i) => i.kind === kind);
+        if (items.length === 0)
+            continue;
+        const matches = (node, item) => isRecord(node) &&
+            (kind === "faq"
+                ? node["@type"] === "Question" && typeof node["name"] === "string" && collapse(node["name"]) === collapse(item.name)
+                : node["@type"] === "DefinedTerm" && node["termCode"] === item.slug);
+        const found = [];
+        const walk = (value, script) => {
+            if (Array.isArray(value)) {
+                if (value.some((node) => items.some((item) => matches(node, item))))
+                    found.push({ script, array: value });
+                for (const v of value)
+                    walk(v, script);
+            }
+            else if (isRecord(value)) {
+                for (const v of Object.values(value))
+                    walk(v, script);
+            }
+        };
+        parsed.forEach((p, script) => p !== undefined && walk(p.value, script));
+        if (found.length !== 1)
+            return { refused: `${found.length} JSON-LD arrays hold a ${kind} top-up, expected 1` };
+        const { script, array } = found[0];
+        const left = [...items];
+        const tail = array.length > items.length ? array.slice(-items.length) : [];
+        for (const node of tail) {
+            const at = left.findIndex((item) => matches(node, item));
+            if (at < 0)
+                break;
+            left.splice(at, 1);
+        }
+        if (tail.length === 0 || left.length > 0) {
+            return { refused: `the last ${items.length} node(s) of the ${kind} array are not its top-ups` };
+        }
+        array.splice(-items.length);
+        changed.add(script);
+    }
+    return {
+        scripts: scripts.map((script, i) => changed.has(i) ? JSON.stringify(parsed[i].value).replace(/</g, "\\u003c") : script),
+    };
+}
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+function paeth(a, b, c) {
+    const p = a + b - c;
+    const pa = Math.abs(p - a);
+    const pb = Math.abs(p - b);
+    const pc = Math.abs(p - c);
+    return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+}
+/**
+ * An 8-bit RGB or RGBA, non-interlaced PNG as RGBA, every scanline filter
+ * undone. Anything else — another depth or colour type, interlacing, a
+ * truncated or corrupt stream — is `unsupported-png`.
+ */
+export function decodePng(png) {
+    const unsupported = { ok: false, reason: "unsupported-png" };
+    try {
+        if (png.length < 8 || !png.subarray(0, 8).equals(PNG_SIGNATURE))
+            return unsupported;
+        let width = 0;
+        let height = 0;
+        let channels = 0;
+        const idat = [];
+        for (let at = 8; at + 8 <= png.length;) {
+            const length = png.readUInt32BE(at);
+            const type = png.toString("ascii", at + 4, at + 8);
+            const data = png.subarray(at + 8, at + 8 + length);
+            if (type === "IHDR") {
+                width = data.readUInt32BE(0);
+                height = data.readUInt32BE(4);
+                const [depth, colour, compression, filter, interlace] = data.subarray(8, 13);
+                if (depth !== 8 || compression !== 0 || filter !== 0 || interlace !== 0)
+                    return unsupported;
+                if (colour === 2)
+                    channels = 3;
+                else if (colour === 6)
+                    channels = 4;
+                else
+                    return unsupported;
+            }
+            else if (type === "IDAT") {
+                idat.push(data);
+            }
+            else if (type === "IEND") {
+                break;
+            }
+            at += 12 + length;
+        }
+        if (channels === 0 || width === 0 || height === 0)
+            return unsupported;
+        const raw = inflateSync(Buffer.concat(idat));
+        const stride = width * channels;
+        if (raw.length !== height * (stride + 1))
+            return unsupported;
+        const rgba = new Uint8Array(width * height * 4);
+        let prev = new Uint8Array(stride);
+        for (let y = 0; y < height; y++) {
+            const filter = raw[y * (stride + 1)];
+            const row = Uint8Array.from(raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1)));
+            for (let i = 0; i < stride; i++) {
+                const a = i >= channels ? row[i - channels] : 0;
+                const b = prev[i];
+                const c = i >= channels ? prev[i - channels] : 0;
+                const predicted = filter === 0 ? 0
+                    : filter === 1 ? a
+                        : filter === 2 ? b
+                            : filter === 3 ? (a + b) >> 1
+                                : filter === 4 ? paeth(a, b, c)
+                                    : -1;
+                if (predicted < 0)
+                    return unsupported;
+                row[i] = (row[i] + predicted) & 0xff;
+            }
+            for (let x = 0; x < width; x++) {
+                const to = (y * width + x) * 4;
+                const from = x * channels;
+                rgba[to] = row[from];
+                rgba[to + 1] = row[from + 1];
+                rgba[to + 2] = row[from + 2];
+                rgba[to + 3] = channels === 4 ? row[from + 3] : 255;
+            }
+            prev = row;
+        }
+        return { ok: true, image: { width, height, data: rgba } };
+    }
+    catch {
+        return unsupported;
+    }
+}
+/** How many pixels differ in any channel, or `size-differs`. */
+export function diffPixels(a, b) {
+    if (a.width !== b.width || a.height !== b.height)
+        return "size-differs";
+    let differing = 0;
+    for (let i = 0; i < a.data.length; i += 4) {
+        if (a.data[i] !== b.data[i] ||
+            a.data[i + 1] !== b.data[i + 1] ||
+            a.data[i + 2] !== b.data[i + 2] ||
+            a.data[i + 3] !== b.data[i + 3]) {
+            differing += 1;
+        }
+    }
+    return differing;
+}
+function textLines(text) {
+    return text
+        .split("\n")
+        .map((line) => line.replace(/\s+/g, " ").trim())
+        .filter((line) => line !== "");
+}
+/** Whitespace runs collapsed, then line for line; `differs` names the first differing line (1-based). */
+export function compareText(before, after) {
+    const a = textLines(before);
+    const b = textLines(after);
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        if (a[i] !== b[i]) {
+            return { verdict: "differs", line: i + 1, before: a[i] ?? "", after: b[i] ?? "" };
+        }
+    }
+    return { verdict: "same" };
+}
+/** `same` only when the two arrays are equal string for string — never after a parse. */
+export function compareJsonLd(before, after) {
+    for (let i = 0; i < Math.max(before.length, after.length); i++) {
+        if (before[i] !== after[i]) {
+            return { verdict: "differs", index: i, before: before[i] ?? null, after: after[i] ?? null };
+        }
+    }
+    return { verdict: "same" };
+}
+function pixelVerdict(before, after, tolerance) {
+    const a = decodePng(before);
+    const b = decodePng(after);
+    if (!a.ok || !b.ok)
+        return { verdict: "unsupported-png" };
+    const differing = diffPixels(a.image, b.image);
+    if (differing === "size-differs")
+        return { verdict: "size-differs" };
+    const total = a.image.width * a.image.height;
+    const verdict = differing === 0 ? "same" : differing / total <= tolerance ? "within-tolerance" : "differs";
+    return { verdict, differing, total };
+}
+function passes(v) {
+    return v.verdict === "same" || v.verdict === "within-tolerance";
+}
+async function renderSide(side, path, viewport, screenshot, exclude) {
+    const failed = (render) => ({ render, text: "", jsonLd: [] });
+    await side.page.setViewportSize({ width: viewport.width, height: viewport.height });
+    let status;
+    try {
+        const response = await side.page.goto(side.origin + path, {
+            waitUntil: "load",
+            timeout: NAVIGATION_TIMEOUT_MS,
+        });
+        status = response?.status();
+    }
+    catch (err) {
+        return failed(`navigation failed: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`);
+    }
+    if (status !== 200)
+        return failed(status === undefined ? "no response" : `status ${status}, expected 200`);
+    const settled = new URL(side.page.url()).pathname;
+    if (settled !== path)
+        return failed(`requested "${path}" but the page settled on "${settled}"`);
+    let full;
+    let dom;
+    if (exclude !== undefined) {
+        if (screenshot)
+            full = await side.page.screenshot({ fullPage: true, animations: "disabled" });
+        const answer = await side.page.evaluate(exclusionExpression(exclude));
+        dom =
+            isRecord(answer) && typeof answer["refused"] === "string"
+                ? { refused: `dom: ${answer["refused"]}` }
+                : isRecord(answer) && Array.isArray(answer["removed"])
+                    ? { removed: exclude.map(itemKey) }
+                    : { refused: "dom: no answer from the page" };
+    }
+    const text = await side.page.evaluate(TEXT_EXPRESSION);
+    const read = await side.page.evaluate(JSONLD_EXPRESSION);
+    let jsonLd = Array.isArray(read) ? read.map(String) : [];
+    let exclusion = dom;
+    if (exclude !== undefined && dom !== undefined && "removed" in dom) {
+        const excluded = excludeJsonLd(jsonLd, exclude);
+        if ("refused" in excluded)
+            exclusion = { refused: `json-ld: ${excluded.refused}` };
+        else
+            jsonLd = excluded.scripts;
+    }
+    return {
+        render: "ok",
+        text: typeof text === "string" ? text : "",
+        jsonLd,
+        ...(screenshot && {
+            png: await side.page.screenshot({ fullPage: true, animations: "disabled" }),
+        }),
+        ...(full !== undefined && { full }),
+        ...(exclusion !== undefined && { exclusion }),
+    };
+}
+/** One frozen URL at every viewport, before against after. */
+export async function comparePage(o) {
+    const viewports = [];
+    const exclude = o.exclude !== undefined && o.exclude.length > 0 ? o.exclude : undefined;
+    for (const viewport of VIEWPORTS) {
+        const before = await renderSide(o.before, o.path, viewport, o.screenshots);
+        const after = await renderSide(o.after, o.path, viewport, o.screenshots, exclude);
+        const rendered = before.render === "ok" && after.render === "ok";
+        const result = {
+            viewport: viewport.name,
+            render: { before: before.render, after: after.render },
+            text: rendered ? compareText(before.text, after.text) : { verdict: "not-compared" },
+            jsonLd: rendered ? compareJsonLd(before.jsonLd, after.jsonLd) : { verdict: "not-compared" },
+            ...(after.exclusion !== undefined && { exclusion: after.exclusion }),
+        };
+        if (o.screenshots) {
+            if (before.png !== undefined && after.png !== undefined) {
+                const shots = {
+                    before: `${o.n}-${viewport.name}-before.png`,
+                    after: `${o.n}-${viewport.name}-after.png`,
+                };
+                o.writeShot(shots.before, before.png);
+                o.writeShot(shots.after, after.png);
+                if (after.full !== undefined) {
+                    shots.afterFull = `${o.n}-${viewport.name}-after-full.png`;
+                    o.writeShot(shots.afterFull, after.full);
+                }
+                result.pixels = pixelVerdict(before.png, after.png, o.tolerance);
+                result.shots = shots;
+            }
+            else {
+                result.pixels = { verdict: "not-compared" };
+            }
+        }
+        viewports.push(result);
+    }
+    const pass = viewports.every((v) => v.render.before === "ok" &&
+        v.render.after === "ok" &&
+        passes(v.text) &&
+        passes(v.jsonLd) &&
+        (v.pixels === undefined || passes(v.pixels)) &&
+        (v.exclusion === undefined || "removed" in v.exclusion));
+    const excluded = exclude !== undefined && viewports.every((v) => v.exclusion !== undefined && "removed" in v.exclusion)
+        ? exclude.map(itemKey)
+        : undefined;
+    return { path: o.path, n: o.n, pass, viewports, ...(excluded !== undefined && { excluded }) };
+}
+// ── The sweep (D9) ──────────────────────────────────────────────────────────
+/** `fn` over `items`, at most `limit` at once; results in input order. */
+export async function mapLimit(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const i = next++;
+            results[i] = await fn(items[i]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return results;
+}
+/** Every path on `origin` must answer 200 directly; a redirect is not a 200. */
+export async function sweep(o) {
+    const results = await mapLimit(o.paths, IN_FLIGHT, async (path) => {
+        try {
+            const response = await o.fetch(o.origin + path, {
+                redirect: "manual",
+                ...(o.headers !== undefined && { headers: o.headers }),
+                signal: AbortSignal.timeout(SWEEP_TIMEOUT_MS),
+            });
+            return { path, status: response.status };
+        }
+        catch {
+            return { path, status: 0 };
+        }
+    });
+    return { pass: results.every((r) => r.status === 200), results };
+}
+function cell(v) {
+    return v === undefined ? "—" : v.verdict;
+}
+/** The eye-read table: one row per URL and viewport, linking its screenshot pair. */
+export function comparisonMarkdown(report) {
+    const lines = [
+        `# Comparison: ${report.before} → ${report.after}`,
+        "",
+        "| # | Path | Viewport | Render | Text | JSON-LD | Pixels | Screenshots |",
+        "| - | ---- | -------- | ------ | ---- | ------- | ------ | ----------- |",
+    ];
+    for (const page of report.pages) {
+        for (const v of page.viewports) {
+            const render = v.render.before === "ok" && v.render.after === "ok"
+                ? "ok"
+                : `before: ${v.render.before}; after: ${v.render.after}`;
+            const shots = v.shots === undefined
+                ? "—"
+                : `[before](shots/${v.shots.before}) · [after](shots/${v.shots.after})`;
+            lines.push(`| ${page.n} | \`${page.path}\` | ${v.viewport} | ${render.replace(/\|/g, "\\|")} | ${cell(v.text)} | ${cell(v.jsonLd)} | ${cell(v.pixels)} | ${shots} |`);
+        }
+    }
+    const excluding = report.pages.filter((p) => p.viewports.some((v) => v.exclusion !== undefined));
+    if (excluding.length > 0) {
+        lines.push("", "## Excluded kind-pull top-ups (#10734)", "");
+        for (const page of excluding) {
+            for (const key of page.excluded ?? [])
+                lines.push(`- \`${page.path}\`: ${key}`);
+            for (const v of page.viewports) {
+                if (v.shots?.afterFull !== undefined) {
+                    lines.push(`- \`${page.path}\` ${v.viewport} before exclusion: [after](shots/${v.shots.afterFull})`);
+                }
+                if (v.exclusion !== undefined && "refused" in v.exclusion) {
+                    lines.push(`- \`${page.path}\` (${v.viewport}): not excluded — ${v.exclusion.refused}`);
+                }
+            }
+        }
+    }
+    const failed = report.sweep.results.filter((r) => r.status !== 200);
+    lines.push("", `## Sweep: ${report.sweep.results.length} URL(s) on ${report.after}, ${failed.length} not 200`, "", ...failed.map((r) => `- \`${r.path}\` → ${r.status}`));
+    return `${lines.join("\n")}\n`;
+}
+/** `comparison.json` and `comparison.md` in `dir`; the screenshots are already in `dir/shots`. */
+export function writeComparisonEvidence(dir, report) {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "comparison.json"), `${JSON.stringify(report, null, 2)}\n`);
+    writeFileSync(join(dir, "comparison.md"), comparisonMarkdown(report));
+}
+export const PLAYWRIGHT_INSTALL_HINT = "pnpm add -D @playwright/test && pnpm exec playwright install chromium";
+/** `chromium` from `playwright` or `@playwright/test`, resolved from each dir in turn. */
+export function loadChromium(dirs) {
+    for (const dir of dirs) {
+        for (const name of ["playwright", "@playwright/test"]) {
+            try {
+                const mod = createRequire(join(dir, "package.json"))(name);
+                if (mod.chromium !== undefined)
+                    return mod.chromium;
+            }
+            catch {
+                // Not installed here: the next candidate.
+            }
+        }
+    }
+    return undefined;
+}
+/** Every page compared, the sweep run, the evidence written; `pass` gates the step. */
+export async function runComparison(o) {
+    const shotsDir = join(o.dir, "shots");
+    if (o.screenshots)
+        mkdirSync(shotsDir, { recursive: true });
+    const browser = await o.chromium.launch();
+    const pages = [];
+    try {
+        const before = await (await browser.newContext()).newPage();
+        const after = await (await browser.newContext()).newPage();
+        const headers = o.afterHeaders;
+        if (headers !== undefined) {
+            // Only requests to the `after` origin carry the headers (a preview's
+            // protection bypass): never a third-party subresource, never another origin.
+            const origin = new URL(o.after).origin;
+            await after.route("**/*", (route) => new URL(route.request().url()).origin === origin
+                ? route.continue({ headers: { ...route.request().headers(), ...headers } })
+                : route.continue());
+        }
+        for (const [i, path] of o.pages.entries()) {
+            const exclude = o.exclude !== undefined && Object.hasOwn(o.exclude, path) ? o.exclude[path] : undefined;
+            const result = await comparePage({
+                path,
+                n: i + 1,
+                before: { origin: o.before, page: before },
+                after: { origin: o.after, page: after },
+                tolerance: o.tolerance,
+                screenshots: o.screenshots,
+                writeShot: (name, png) => writeFileSync(join(shotsDir, name), png),
+                ...(exclude !== undefined && { exclude }),
+            });
+            o.onLine?.(`${result.pass ? "same" : "DIFFERS"} ${path}`);
+            pages.push(result);
+        }
+    }
+    finally {
+        await browser.close();
+    }
+    const swept = await sweep({
+        origin: o.after,
+        paths: o.sweepPaths,
+        fetch: o.fetch,
+        ...(o.afterHeaders !== undefined && { headers: o.afterHeaders }),
+    });
+    const report = { before: o.before, after: o.after, pages, sweep: swept };
+    writeComparisonEvidence(o.dir, report);
+    return { ...report, pass: swept.pass && pages.every((p) => p.pass) };
+}

package/dist/mdx-braces.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Bare `{…}` braces on mdx-body pages (#10773, spec
+ * docs/specs/10773-update-never-refreshes-0-19-spec.md D3, D4).
+ *
+ * MDX reads every `{` in body text as the start of a JavaScript expression.
+ * Under the renderer's `next-mdx-remote` defaults (`blockJS`), an expression
+ * that does not parse fails the page, and one that parses is deleted — so on
+ * an mdx-body page every `{` in text other than a `{/* … *\/}` comment is a
+ * defect. This module is the one lexical rule for that brace:
+ *
+ * - `findBareBraces` names every bare brace in a body, by offset, line and
+ *   column, in one left-to-right pass;
+ * - `escapeBareBraces` inserts one `\` before each, and keeps the result only
+ *   when the site's own MDX parser reads it with no expression left but
+ *   comments — the lexer proposes, the parser disposes.
+ *
+ * Used by `create-ailk update` and, through a byte-identical copy in the
+ * scaffold's `tools/`, by `pnpm mdx-body:check`. Pure: no filesystem and no
+ * imports. It must never contain a double open brace, which the scaffold copy
+ * substitutes as a marker.
+ */
+export interface BareBrace {
+    /** Offset of the `{` in the body. */
+    offset: number;
+    /** 1-based line within the body. */
+    line: number;
+    /** 1-based column within the line. */
+    column: number;
+    /** `comment-like` when the next non-whitespace character is `/`. */
+    kind: "placeholder" | "comment-like";
+}
+/** A minimal mdast node: what `escapeBareBraces` reads from the parser's tree. */
+export interface MdastNode {
+    type: string;
+    value?: unknown;
+    position?: {
+        start?: {
+            line?: number;
+            offset?: number;
+        };
+        end?: {
+            offset?: number;
+        };
+    };
+    children?: MdastNode[];
+}
+/** The site's MDX parser: throws the parser's message (carrying `line` and `reason`) on failure. */
+export type MdxParse = (body: string) => MdastNode;
+export type EscapeResult = {
+    kind: "clean";
+} | {
+    kind: "escaped";
+    text: string;
+    count: number;
+} | {
+    kind: "refused";
+    reason: string;
+};
+/**
+ * Every bare `{` in an MDX body. Skips, in this order of precedence: fenced
+ * code, ESM blocks, backslash escapes, inline code, JSX tags (attribute
+ * expressions included) and `{/* … *\/}` comments. Linear in the body.
+ */
+export declare function findBareBraces(body: string): BareBrace[];
+/** The first expression node left in the tree that is not a comment. */
+export declare function firstExpression(node: MdastNode): MdastNode | undefined;
+/**
+ * Escape every bare brace in `body`, all or nothing: `clean` when there is
+ * none (`parse` is not called), `refused` when a brace is a mangled comment,
+ * the escaped text does not parse, or an expression the escape did not reach
+ * remains; otherwise `escaped`.
+ */
+export declare function escapeBareBraces(body: string, parse: MdxParse): EscapeResult;