@michaelmagan/dnumb 0.1.0

package/dist/diff/render.cjs

@@ -0,0 +1,540 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderDiff = renderDiff;
+/**
+ * Render a diff as the text an agent reads.
+ *
+ * The grammar is the step-2 spike's, ported unchanged. Six independent cold
+ * readers, one diff each and no other context, scored 6/6 correct accounts with
+ * zero fabrications on this exact output — including the control fixture where
+ * nothing changed (`docs/notes/02-v1-cold-read.md`). That result is the gate the
+ * stateful thesis rested on, so the format is deliberately not redesigned here.
+ *
+ * Ids are *after*-state ids, because the next thing the agent does is query the
+ * state it is now in. Removed elements carry a before-id and are marked `-`, so
+ * the two are never confused.
+ */
+const not_measured_js_1 = require("../snapshot/not-measured.cjs");
+/** Sub-pixel layout noise. Matches the tolerance `changes.ts` measures with. */
+const BOX_TOLERANCE = 0.5;
+const DEFAULT_MAX_LINES = 15;
+const n = (value) => (Number.isInteger(value) ? String(value) : value.toFixed(1));
+const vArrow = (d) => (d > 0 ? `↓${n(d)}` : `↑${n(-d)}`);
+const hArrow = (d) => (d > 0 ? `→${n(d)}` : `←${n(-d)}`);
+const signed = (d) => `${d > 0 ? '+' : ''}${n(d)}`;
+const cssName = (prop) => prop.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+/** `aria-expanded` is what the line prints; `ariaExpanded` is what the record calls it. */
+const camelName = (prop) => prop.replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase());
+// ---- labels ---------------------------------------------------------------
+const LABEL_TEXT_LIMIT = 32;
+const SUBTREE_TEXT_LIMIT = 80;
+/**
+ * Subtree text is a *matching* feature; using it as a label turns `body` into a
+ * paragraph. Fall back to it only for small elements, where it is the only
+ * thing that says which one this is — `+ e6 li "Desk lamp 1"` beats `+ e6 li`.
+ */
+const SUBTREE_LABEL_MAX_DESCENDANTS = 2;
+/**
+ * Records indexed by id, one index per capture.
+ *
+ * Both collectors number elements `e0`, `e1`, … from zero, so `e6` in the before
+ * capture and `e6` in the after capture are different elements. One shared map
+ * would resolve a removed element's children against the wrong capture and
+ * label it with text from a page it was never on.
+ */
+function indexRecords(changes, side) {
+    const byId = new Map();
+    for (const change of changes) {
+        const record = side === 'before' ? change.before : change.after;
+        if (record)
+            byId.set(record.id, record);
+    }
+    return byId;
+}
+/**
+ * The subtree-text label, or `null` when it must not be used.
+ *
+ * `renderDiff` is handed changes rather than the `Prepared` side maps that hold
+ * `subtreeText` and `descendantCount`, so both are recomputed from the records
+ * in hand. `null` covers two cases that have to behave the same way: the
+ * element is too big for this to be a name, or part of its subtree is not among
+ * those records. A partial subtree printed as a label would attribute to one
+ * element the words of an unknown fraction of it, which is the fabrication this
+ * whole format exists to avoid. The descendant cap also bounds the walk, so a
+ * malformed record cycle cannot spin here.
+ */
+function subtreeLabel(el, byId) {
+    let descendants = 0;
+    let text = el.text;
+    const visit = (node) => {
+        for (const childId of node.childIds) {
+            const child = byId.get(childId);
+            if (!child)
+                return false;
+            descendants++;
+            if (descendants > SUBTREE_LABEL_MAX_DESCENDANTS)
+                return false;
+            text = `${text} ${child.text}`.trim();
+            if (!visit(child))
+                return false;
+        }
+        return true;
+    };
+    return visit(el) ? text.slice(0, SUBTREE_TEXT_LIMIT) : null;
+}
+/**
+ * `tag#testid` or `tag.role`, matching `digest/render.ts`'s own `label()` and
+ * `query.ts`'s `ANNOTATED_QUERY` grammar exactly (B9). This function used to
+ * print `@testId` / `#domId` instead — a sigil pair this package's own `q
+ * find` cannot parse: `#` there means test id and `.` means role, so a token
+ * this renderer produced (`table@testId`, `ul#domId`) either matched nothing
+ * (`domId` is not part of the compound annotation at all — `q find` only
+ * ever matches it as a whole separate field) or matched the wrong field
+ * outright (`#` parsed as *test id*, not the dom id this line meant). An
+ * agent that copies a diff line straight into `q find` — the documented
+ * round-trip — got zero matches, with a hint asserting the query's own
+ * `field "testId"` came up empty when the line never named a test id to
+ * begin with. Dropping `domId` from the compound token (rather than
+ * inventing a third sigil) keeps this renderer producing exactly the shape
+ * the rest of the package already agrees on; `domId` alone still identifies
+ * the element via `id`/text/`q describe`, and `q find` already matches it as
+ * a bare field.
+ */
+function label(el, byId) {
+    let head = `${el.id} ${el.tag}`;
+    if (el.testId)
+        head += `#${el.testId}`;
+    else if (el.role)
+        head += `.${el.role}`;
+    const name = el.name || el.text || subtreeLabel(el, byId);
+    if (!name)
+        return head;
+    const shown = name.length > LABEL_TEXT_LIMIT ? `${name.slice(0, LABEL_TEXT_LIMIT - 1)}…` : name;
+    return `${head} "${shown}"`;
+}
+const at = (el) => `@${n(el.rect.x)},${n(el.rect.y)} ${n(el.rect.width)}x${n(el.rect.height)}`;
+/**
+ * `Change.descendants` (set in `changes.ts`'s subsumption pass) counts
+ * folded *elements*, deliberately a different unit from the header's `N
+ * folded` count of *change records* below — see the comment on `folded` in
+ * `renderDiff` for why that is not a bug.
+ */
+const inside = (change) => change.descendants ? ` +${change.descendants} inside` : '';
+// ---- line forms -----------------------------------------------------------
+/** Vertical before horizontal, movement before resize. One reading order, always. */
+function vector(d) {
+    if (!d)
+        return '';
+    return [
+        Math.abs(d.dy) > BOX_TOLERANCE ? vArrow(d.dy) : null,
+        Math.abs(d.dx) > BOX_TOLERANCE ? hArrow(d.dx) : null,
+        Math.abs(d.dh) > BOX_TOLERANCE ? `↕${signed(d.dh)}` : null,
+        Math.abs(d.dw) > BOX_TOLERANCE ? `↔${signed(d.dw)}` : null,
+    ]
+        .filter((part) => part !== null)
+        .join(' ');
+}
+function boxLine(d, before, after, byId) {
+    const parts = [];
+    if (Math.abs(d.dx) > BOX_TOLERANCE || Math.abs(d.dy) > BOX_TOLERANCE) {
+        parts.push(`@${n(before.rect.x)},${n(before.rect.y)} → @${n(after.rect.x)},${n(after.rect.y)}`);
+    }
+    if (Math.abs(d.dw) > BOX_TOLERANCE || Math.abs(d.dh) > BOX_TOLERANCE) {
+        parts.push(`${n(before.rect.width)}x${n(before.rect.height)} → ` +
+            `${n(after.rect.width)}x${n(after.rect.height)}`);
+    }
+    return `~ ${label(after, byId)} ${parts.join(' ')} (${vector(d)})`;
+}
+/**
+ * Clipping is reported as the measurement, the fact that explains it, and the
+ * fact that would excuse it — the clipper's own `overflow` value and whether it
+ * can be scrolled. A clipped box inside `overflow:auto` is a scroll region; the
+ * same box inside `overflow:hidden` is content nobody can reach. Both are said
+ * and neither is adjudicated: the cold reader drew "unusable" from
+ * `not scrollable` beside `182x5 visible` on its own. Dropping `scrollable`
+ * from the line inverts what the rest of it means.
+ */
+function clipLine(after, byId) {
+    const clip = after.clip;
+    if (!clip)
+        return `✓ ${label(after, byId)} no longer clipped`;
+    const hidden = clip.hidden;
+    const directions = [
+        hidden.top ? `${n(hidden.top)}px above` : null,
+        hidden.bottom ? `${n(hidden.bottom)}px below` : null,
+        hidden.left ? `${n(hidden.left)}px left of` : null,
+        hidden.right ? `${n(hidden.right)}px right of` : null,
+    ]
+        .filter((part) => part !== null)
+        .join(', ');
+    const visible = clip.visible.width < BOX_TOLERANCE || clip.visible.height < BOX_TOLERANCE
+        ? '0 visible'
+        : `${n(clip.visible.width)}x${n(clip.visible.height)} visible`;
+    const scroll = clip.scrollable ? ', scrollable' : ', not scrollable';
+    return (`! ${label(after, byId)} clipped by ${clip.by} ${clip.byTag} ` +
+        `[overflow:${clip.overflow}${scroll}] — ${directions} it, ${visible}`);
+}
+/**
+ * A `removed` or `added` line that the matcher could not resolve to a genuine
+ * presence change — the capture whose window could have excluded this
+ * element's hypothetical counterpart was truncated (for `removed`, that is
+ * the *after* capture; for `added`, the *before* capture — the other side's
+ * truncation is irrelevant, see `changes.ts`'s `markBoundaryAmbiguous`), and
+ * the document-order shift measured near this element would place that
+ * counterpart outside the window. Marked `?`, never `-` or `+`: printing
+ * either would assert an answer this diff does not have.
+ */
+function boundaryLine(change, byBefore, byAfter) {
+    if (change.capSize === undefined)
+        return null;
+    if (change.kind === 'removed') {
+        if (!change.before)
+            return null;
+        // `capSize` is the *after* capture's element count (`changes.ts`'s
+        // `markBoundaryAmbiguous`): that window is what could have cut this
+        // element's surviving counterpart off, so it is the capture named here.
+        // Naming "before" instead is F2 — it prints the other capture's count
+        // under the wrong capture's label, and can contradict the header line
+        // above it whenever the two windows differ in size.
+        return (`? ${label(change.before, byBefore)} ${at(change.before)} — after capped at ` +
+            `${change.capSize} elements; may be removed, or pushed past the cap by insertions ` +
+            `earlier in the document`);
+    }
+    if (change.kind === 'added') {
+        if (!change.after)
+            return null;
+        // Mirror of the above: `capSize` is the *before* capture's element count
+        // — its window is what could have missed an element that already existed.
+        return (`? ${label(change.after, byAfter)} ${at(change.after)} — before capped at ` +
+            `${change.capSize} elements; may be new, or pulled into the window by removals earlier ` +
+            `in the document`);
+    }
+    return null;
+}
+/**
+ * A `style` change names a record property, and `ElementRecord` is not indexable
+ * by an arbitrary string, so the read goes through one narrow cast. An absent
+ * property renders `∅` rather than the string `undefined`, which a reader would
+ * take for a value the page actually had.
+ */
+function propValue(el, prop) {
+    const value = el[prop];
+    if (value === undefined || value === null)
+        return '∅';
+    if (typeof value === 'object') {
+        if ('top' in value && 'right' in value && 'bottom' in value && 'left' in value) {
+            const { top, right, bottom, left } = value;
+            return top === right && right === bottom && bottom === left
+                ? String(top)
+                : `${String(top)} ${String(right)} ${String(bottom)} ${String(left)}`;
+        }
+        if ('row' in value && 'column' in value) {
+            const { row, column } = value;
+            return row === column ? String(row) : `${String(row)} ${String(column)}`;
+        }
+    }
+    return String(value);
+}
+/**
+ * The line for one primary change, or `null` when the change does not carry the
+ * records its line quotes.
+ *
+ * Returning `null` rather than printing a half-line keeps the header's counts
+ * honest: they are taken from the changes that actually produced a line, so the
+ * summary never promises a line the body does not hold.
+ */
+function lineFor(change, byBefore, byAfter) {
+    if (change.boundaryAmbiguous)
+        return boundaryLine(change, byBefore, byAfter);
+    const { before, after } = change;
+    switch (change.kind) {
+        case 'added':
+            return after ? `+ ${label(after, byAfter)} ${at(after)}${inside(change)}` : null;
+        case 'removed':
+            return before ? `- ${label(before, byBefore)} ${at(before)}${inside(change)}` : null;
+        case 'appeared':
+            return after
+                ? `+ ${label(after, byAfter)} ${at(after)} (was ${change.reason ?? 'not visible'})${inside(change)}`
+                : null;
+        case 'disappeared':
+            return before
+                ? `- ${label(before, byBefore)} ${at(before)} (now ${change.reason ?? 'not visible'})${inside(change)}`
+                : null;
+        case 'text':
+            return before && after
+                ? `~ ${label(after, byAfter)} text "${before.text}" → "${after.text}"`
+                : null;
+        case 'attr': {
+            if (!before || !after || !change.prop)
+                return null;
+            const field = camelName(change.prop);
+            return (`~ ${label(after, byAfter)} ${change.prop} ` +
+                `${propValue(before, field)} → ${propValue(after, field)}`);
+        }
+        case 'clip':
+            return after ? clipLine(after, byAfter) : null;
+        case 'overflow': {
+            if (!after)
+                return null;
+            if (!change.now)
+                return `✓ ${label(after, byAfter)} overflow-x resolved`;
+            const past = n(after.scrollWidth - after.clientWidth);
+            return `! ${label(after, byAfter)} overflow-x +${past}px now [${after.overflowX}]`;
+        }
+        case 'box':
+            return before && after && change.delta ? boxLine(change.delta, before, after, byAfter) : null;
+        case 'style':
+            return before && after && change.prop
+                ? `~ ${label(after, byAfter)} ${cssName(change.prop)} ` +
+                    `${propValue(before, change.prop)} → ${propValue(after, change.prop)}`
+                : null;
+    }
+}
+// ---- ordering -------------------------------------------------------------
+/**
+ * Structure, then visibility, then content, then the facts, then geometry, then
+ * paint. An agent reading top-down meets the act before its consequences.
+ */
+const RANK = {
+    added: 0,
+    removed: 0,
+    appeared: 1,
+    disappeared: 1,
+    text: 2,
+    attr: 2,
+    clip: 3,
+    overflow: 3,
+    box: 4,
+    style: 5,
+};
+/**
+ * Document order, read off the id.
+ *
+ * `Prepared.docIndex` holds this, but `renderDiff` is handed changes and not the
+ * captures they came from. Both collectors number elements `e0`, `e1`, … in the
+ * order they walk the tree, so the suffix *is* the document index. An id in any
+ * other shape sorts first rather than throwing the whole ordering out.
+ */
+function documentOrder(change) {
+    const id = change.after?.id ?? change.before?.id ?? '';
+    const digits = /^e(\d+)$/.exec(id)?.[1];
+    return digits === undefined ? 0 : Number(digits);
+}
+// ---- the derived tail ------------------------------------------------------
+/**
+ * How many of a group's ids are named before the line switches to a count.
+ *
+ * The rest stay reachable through the cause: they are exactly the elements that
+ * moved by this vector because of `rootVia`, and the trailing `[N]` says how
+ * many there are. Naming all of them turns one insert into a 2,000-character
+ * line without adding any reach.
+ */
+const DERIVED_NAMED = 3;
+/**
+ * A folded line's whole content is "these ids, this vector, because of that
+ * element". A derived change missing any of the three has no such line, so it
+ * stays primary and gets its own — the diff never drops a change on a shape
+ * problem, because a change that vanishes is indistinguishable from a page that
+ * did not change.
+ */
+const foldable = (change) => change.cause === 'derived' &&
+    change.afterId !== undefined &&
+    change.rootVia !== undefined &&
+    change.rootHow !== undefined;
+const deltaKey = (d) => d ? `${n(d.dx)}|${n(d.dy)}|${n(d.dw)}|${n(d.dh)}` : '';
+/**
+ * One line per root cause and vector.
+ *
+ * Grouping on `rootVia` rather than `via` is what keeps one insertion to one
+ * line: a pushed row and the four words inside it share a root, and grouping on
+ * the immediate cause made them five groups that all meant "because e6 was
+ * inserted".
+ */
+function foldDerived(derived) {
+    const groups = new Map();
+    for (const change of derived) {
+        const key = change.kind === 'style'
+            ? `inherited|${change.rootVia}|${change.prop ?? ''}`
+            : `${change.rootVia}|${change.rootHow}|${deltaKey(change.delta)}`;
+        const group = groups.get(key);
+        if (group)
+            group.push(change);
+        else
+            groups.set(key, [change]);
+    }
+    const lines = [];
+    for (const group of groups.values()) {
+        const first = group[0];
+        if (!first)
+            continue;
+        const ids = group
+            .slice(0, DERIVED_NAMED)
+            .map((change) => change.afterId)
+            .join(' ');
+        const more = group.length > DERIVED_NAMED ? ` +${group.length - DERIVED_NAMED} more` : '';
+        if (first.kind === 'style') {
+            lines.push(`~ ${ids}${more} ${cssName(first.prop ?? '')} inherited from ${first.rootVia} [${group.length}]`);
+            continue;
+        }
+        const moved = vector(first.delta);
+        lines.push(`~ ${ids}${more} ${first.rootHow}${moved ? ` ${moved}` : ''} by ${first.rootVia} [${group.length}]`);
+    }
+    return lines;
+}
+/**
+ * One side's clause of the caveat, or `null` when that side is not truncated.
+ *
+ * A hand-built `DiffMeta` can say a side is truncated without knowing its
+ * count — `diffCaptures` never leaves this gap, but a caller that builds its
+ * own `DiffMeta` might. The old fallback printed the literal character `?`
+ * for a missing count, which is this diff's own glyph for an unresolved
+ * add/remove (F3): a reader would take `before capped at ? elements` for an
+ * ambiguity marker rather than a caveat about the whole capture. Naming the
+ * gap in words instead can never be confused with that.
+ */
+function truncationClause(side, truncated, count) {
+    if (!truncated)
+        return null;
+    return count === undefined
+        ? `${side} capped (count not recorded)`
+        : `${side} capped at ${count} elements`;
+}
+/**
+ * Both `look` and `diff` share the fact a capture can be a window rather than
+ * the whole page (`src/snapshot/limits.ts`). `renderDigest` says so on its own
+ * header line; this is that line's counterpart here. A reader comparing two
+ * 5,000-element windows of a 12,000-element page has to be told even when
+ * nothing near the cap looks ambiguous — the absence of a `?` line does not
+ * mean the two captures cover everything, only that nothing detectably fell
+ * off the edge.
+ */
+function truncationCaveat(meta) {
+    const parts = [
+        truncationClause('before', meta.truncatedBefore, meta.beforeCount),
+        truncationClause('after', meta.truncatedAfter, meta.afterCount),
+    ].filter((part) => part !== null);
+    if (parts.length === 0)
+        return null;
+    return (`TRUNCATED: ${parts.join(', ')} — this diff compares a window of the page, not the whole ` +
+        'thing; content past a cap is not in that capture at all');
+}
+/**
+ * One side's clause of the not-measured caveat, or `null` when that side
+ * measured nothing worth disclosing. `formatNotMeasured` already returns
+ * `null` for "nothing to disclose" (`src/snapshot/not-measured.ts`'s own doc
+ * comment) — this only adds the side label, the same shape
+ * `truncationClause` uses above.
+ */
+function notMeasuredClause(side, notMeasured) {
+    if (!notMeasured)
+        return null;
+    const formatted = (0, not_measured_js_1.formatNotMeasured)(notMeasured);
+    return formatted ? `${side}: ${formatted}` : null;
+}
+/**
+ * B7. `notMeasured` is measured by the capture layer, threaded all the way
+ * into `DiffMeta` (`diffCaptures` forwards `notMeasuredBefore`/
+ * `notMeasuredAfter` from each side's `Snapshot.notMeasured` unconditionally
+ * — see `index.ts`), and then rendered nowhere: `dnumb diff` never disclosed
+ * shadow DOM or iframe content in its text output, so an agent reading a
+ * diff had no way to learn that part of the page was invisible to the
+ * capture that produced it, even though the digest's own header
+ * (`digest/render.ts`) and every `q` verb already say so for a single
+ * capture. This is that same disclosure for a diff: a real change inside a
+ * closed shadow root or a cross-origin iframe on either side is not a
+ * silence this diff can vouch for, and the two sides need not agree — a
+ * `before` walk capture and an `after` CDP capture can disagree on what they
+ * could even see, independent of whatever the page actually did.
+ */
+function notMeasuredCaveat(meta) {
+    const parts = [
+        notMeasuredClause('before', meta.notMeasuredBefore),
+        notMeasuredClause('after', meta.notMeasuredAfter),
+    ].filter((part) => part !== null);
+    if (parts.length === 0)
+        return null;
+    return (`NOT MEASURED: ${parts.join('; ')} — shadow DOM and iframe content neither capture path ` +
+        'could see is not reflected in this diff, on either side');
+}
+// ---- the diff --------------------------------------------------------------
+function renderDiff(changes, meta, options = {}) {
+    const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+    const byBefore = indexRecords(changes, 'before');
+    const byAfter = indexRecords(changes, 'after');
+    const live = changes.filter((change) => change.subsumed === undefined);
+    const derived = live.filter(foldable);
+    const primary = live.filter((change) => !foldable(change));
+    // A change marked `derived` with nothing to point at still has to be printed
+    // -- a class toggling `open` is real, and dropping it would make a page that
+    // changed look like one that did not -- but it is context for the lines above
+    // it, not an act of its own. Sinking it below the primaries keeps the
+    // `cause` the subsumption pass assigned meaningful in the output, instead of
+    // it being a field nothing reads.
+    const rank = (change) => change.cause === 'derived' ? RANK.style + 1 : RANK[change.kind];
+    primary.sort((a, b) => rank(a) - rank(b) || documentOrder(a) - documentOrder(b));
+    const body = [];
+    const printed = [];
+    for (const change of primary) {
+        const line = lineFor(change, byBefore, byAfter);
+        if (line === null)
+            continue;
+        body.push(line);
+        printed.push(change);
+    }
+    body.push(...foldDerived(derived));
+    // A boundary-ambiguous change is counted separately, never as a confirmed
+    // add or remove — folding it into either count would restate in the header
+    // summary the exact fabrication its own line refuses to make.
+    const isAmbiguous = (change) => change.boundaryAmbiguous === true;
+    const count = (kinds) => printed.filter((change) => kinds.includes(change.kind) && !isAmbiguous(change)).length;
+    const added = count(['added', 'appeared']);
+    const removed = count(['removed', 'disappeared']);
+    const ambiguous = printed.filter(isAmbiguous).length;
+    // Every other number on this line — `added`, `removed`, `changed`,
+    // `derived` — counts `Change` records, not elements: a single element can
+    // contribute several (`box`, multiple `style` props, `text`) and each one
+    // is tallied separately, matching what `printed`/`derived` actually hold.
+    // `folded` keeps that same unit for consistency with its neighbours on
+    // this line. The per-line `+N inside` a body line carries (`inside()`
+    // below, sourced from `Change.descendants` in `changes.ts`) is
+    // deliberately the other unit — a count of *elements* folded under one
+    // parent, because "4 elements are inside this subtree" is the fact a
+    // reader wants there, not "4 elements produced 7 change records between
+    // them". The two numbers describe the same fold in different units on
+    // purpose; neither is a miscount of the other.
+    const folded = changes.filter((change) => change.subsumed !== undefined).length;
+    const caveat = truncationCaveat(meta);
+    const notMeasuredLine = notMeasuredCaveat(meta);
+    // `cdp` and `walk` do not see the same page on shadow DOM (`DigestMeta`
+    // carries the same fact in the digest header, for the same reason) — a
+    // diff across the two capability tiers can report hundreds of changes that
+    // are artefacts of which path captured, not of the page (F4). Shown only
+    // when both sides know their strategy; a hand-built `DiffMeta` need not.
+    const strategyLine = meta.strategyBefore && meta.strategyAfter
+        ? `  ${meta.strategyBefore} → ${meta.strategyAfter}`
+        : '';
+    const header = [
+        `${meta.before} → ${meta.after}  ${meta.viewportBefore} → ${meta.viewportAfter}${strategyLine}`,
+        `${added} added  ${removed} removed  ${printed.length - added - removed - ambiguous} changed  ` +
+            `${derived.length} derived  ${folded} folded` +
+            (ambiguous > 0 ? `  ${ambiguous} boundary-ambiguous` : ''),
+        ...(caveat ? [caveat] : []),
+        ...(notMeasuredLine ? [notMeasuredLine] : []),
+    ];
+    let shown = body;
+    if (shown.length > maxLines) {
+        // The notice counts against the budget rather than sitting outside it: a cap
+        // the reader cannot see is indistinguishable from complete output, so the
+        // one line that says a cap was hit is never the line that gets cut.
+        const kept = Math.max(0, maxLines - 1);
+        // `--limit` is the CLI flag that actually sets `maxLines` (`dnumb diff
+        // --limit N`); this used to name a flag the CLI has never had
+        // (`--max-lines`), which fails with "Unknown option" if a reader tries it.
+        shown = [...body.slice(0, kept), `…+${body.length - kept} not listed (--limit)`];
+    }
+    // The fabrication control. Six readers saw this on a page where nothing moved
+    // and reported nothing; anything softer invites a reading of "probably fine".
+    if (shown.length === 0)
+        shown = ['(no observable change)'];
+    return `${header.join('\n')}\n\n${shown.join('\n')}\n`;
+}

package/dist/diff/render.d.cts

@@ -0,0 +1,2 @@
+import type { Change, DiffMeta, DiffOptions } from "./types.cjs";
+export declare function renderDiff(changes: readonly Change[], meta: DiffMeta, options?: DiffOptions): string;

package/dist/diff/render.d.ts

@@ -0,0 +1,2 @@
+import type { Change, DiffMeta, DiffOptions } from "./types.js";
+export declare function renderDiff(changes: readonly Change[], meta: DiffMeta, options?: DiffOptions): string;