@michaelmagan/dnumb 0.1.0

package/dist/query.cjs

@@ -0,0 +1,1152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryError = exports.Q_VERBS = void 0;
+exports.look = look;
+exports.query = query;
+/**
+ * The offline verbs.
+ *
+ * Pure functions over a `Bundle` — no filesystem, no browser, no clock. That is
+ * what makes `dnumb --from capture.json q describe e91` answerable six months
+ * later on a machine with neither the app nor a browser, which is the entire
+ * claim the capture bundle makes.
+ *
+ * Nothing here adjudicates. Every verb reports the measurement and the adjacent
+ * facts, in the same register as `snapshot/facts.ts`: no severity, no
+ * thresholds, no "problem". A rule engine standing between the measurement and
+ * the model is what killed the predecessor to this tool.
+ *
+ * Each verb returns both renderings at once. They are built from one pass over
+ * one context, so `--json` can never report something the text does not — the
+ * alternative is a CLI that re-derives meaning from a structure and the two
+ * outputs drifting apart on the verb nobody reads twice.
+ */
+const distances_js_1 = require("./analysis/distances.cjs");
+const layout_tree_js_1 = require("./analysis/layout-tree.cjs");
+const region_query_js_1 = require("./analysis/region-query.cjs");
+const index_js_1 = require("./digest/index.cjs");
+const color_js_1 = require("./snapshot/color.cjs");
+const facts_js_1 = require("./snapshot/facts.cjs");
+const not_measured_js_1 = require("./snapshot/not-measured.cjs");
+exports.Q_VERBS = [
+    'describe',
+    'find',
+    'at',
+    'within',
+    'distance',
+    'nearest',
+    'facts',
+    'color',
+];
+/**
+ * A verb could not answer the question as asked. The message is the whole
+ * product: it names what was wrong and the command that fixes it, because an
+ * agent that gets `no element "e99"` and no route forward will guess.
+ */
+class QueryError extends Error {
+    name = 'QueryError';
+}
+exports.QueryError = QueryError;
+const DEFAULT_LIMIT = 50;
+const DEFAULT_K = 4;
+const TEXT_TRUNCATE = 30;
+const round = (n) => Math.round(n);
+/** Integers stay integers; a distance keeps one decimal and no more. */
+const num = (n) => (Number.isInteger(n) ? String(n) : n.toFixed(1));
+const sides = (b) => `${num(b.top)} ${num(b.right)} ${num(b.bottom)} ${num(b.left)}`;
+function context(bundle) {
+    const byId = new Map(bundle.elements.map((el) => [el.id, el]));
+    const facts = new Map();
+    for (const el of bundle.elements) {
+        const found = (0, facts_js_1.factsFor)(el, byId);
+        if (found.length > 0)
+            facts.set(el.id, found);
+    }
+    // Same `keepIds` the digest passes, for the same reason: the `0x1239` column
+    // the facts model exists to surface has no visible box either, and a point
+    // query that silently cannot hit it is a point query that lies.
+    const { tree, dropped } = (0, layout_tree_js_1.buildLayoutTree)(bundle.elements, { keepIds: new Set(facts.keys()) });
+    return {
+        bundle,
+        byId,
+        facts,
+        tree,
+        notInTree: dropped.invisible + dropped.svgInternal + dropped.wrappers,
+    };
+}
+/**
+ * One record as a digest line.
+ *
+ * `digest/render.ts` builds its lines from `LayoutNode`s inside a tree walk and
+ * does not export the piece that formats one, so this is the flat, record-shaped
+ * twin rather than a second grammar: same order, same tokens, no flow or gap
+ * (both are properties of a node's position among its siblings, which a match
+ * list has thrown away).
+ */
+function digestLine(el, facts, suffix = '') {
+    let head = `${el.id} ${el.tag}`;
+    if (el.testId)
+        head += `#${el.testId}`;
+    else if (el.role)
+        head += `.${el.role}`;
+    const label = el.name || el.text;
+    if (label) {
+        head += ` "${label.length > TEXT_TRUNCATE ? `${label.slice(0, TEXT_TRUNCATE)}…` : label}"`;
+    }
+    const geometry = `@${round(el.rect.x)},${round(el.rect.y)} ${round(el.rect.width)}x${round(el.rect.height)}`;
+    return [head, geometry, suffix, ...facts.map((f) => `[${f}]`)].filter(Boolean).join(' ');
+}
+const factTexts = (ctx, id) => (ctx.facts.get(id) ?? []).map((f) => f.text);
+function nodeLine(ctx, node, suffix = '') {
+    const el = ctx.byId.get(node.elementId);
+    if (el)
+        return digestLine(el, factTexts(ctx, node.elementId), suffix);
+    const geometry = `@${round(node.rect.x)},${round(node.rect.y)} ${round(node.rect.width)}x${round(node.rect.height)}`;
+    return [node.elementId, node.tag, geometry, suffix].filter(Boolean).join(' ');
+}
+function nodeMatch(ctx, node) {
+    const el = ctx.byId.get(node.elementId);
+    return {
+        id: node.elementId,
+        tag: node.tag,
+        kind: node.kind,
+        rect: node.rect,
+        ...(el?.role ? { role: el.role } : {}),
+        ...(el?.name ? { name: el.name } : {}),
+        ...(el?.text ? { text: el.text } : {}),
+        facts: factTexts(ctx, node.elementId),
+    };
+}
+function findNode(nodes, match) {
+    for (const node of nodes) {
+        if (match(node))
+            return node;
+        const inChild = findNode(node.children, match);
+        if (inChild)
+            return inChild;
+    }
+    return null;
+}
+/** The trailing digits of `e13`, or `NaN` for an id with no ordinal in it. */
+const ordinal = (id) => Number.parseInt(id.replace(/^\D+/, ''), 10);
+/** Ids a typo of `id` most plausibly meant: prefix relatives first, then ordinal neighbours. */
+function nearbyIds(ctx, id) {
+    const ids = ctx.bundle.elements.map((el) => el.id);
+    const related = ids.filter((x) => x.startsWith(id) || id.startsWith(x));
+    if (related.length > 0)
+        return related.slice(0, 5);
+    const target = ordinal(id);
+    if (!Number.isFinite(target))
+        return ids.slice(0, 5);
+    // `|| Number.POSITIVE_INFINITY` used to be here to push an id with no
+    // ordinal (NaN) to the back — but `0 || Number.POSITIVE_INFINITY` is also
+    // `Number.POSITIVE_INFINITY`, since 0 is falsy. That sorted the one id at
+    // distance zero — the exact ordinal match, e.g. `e20` when the typo was
+    // `x20` — to the very back, where `.slice(0, 5)` always dropped it. Only
+    // NaN (no ordinal at all) should fall back to infinity; a real distance of
+    // zero is the closest possible match, not the furthest.
+    const away = (x) => {
+        const diff = Math.abs(ordinal(x) - target);
+        return Number.isNaN(diff) ? Number.POSITIVE_INFINITY : diff;
+    };
+    return [...ids]
+        .sort((a, b) => away(a) - away(b))
+        .slice(0, 5)
+        .sort();
+}
+function requireElement(ctx, id) {
+    const el = ctx.byId.get(id);
+    if (el)
+        return el;
+    const near = nearbyIds(ctx, id);
+    const notMeasured = coverageCaveat(ctx);
+    throw new QueryError(`no element "${id}" in bundle "${ctx.bundle.name}" (${ctx.bundle.elements.length} records).` +
+        (near.length > 0 ? ` Nearby ids: ${near.join(', ')}.` : '') +
+        // An id that looks missing may not be missing from the page -- it may be
+        // inside a shadow root or an iframe this capture never entered, which
+        // looks identical to "does not exist" unless said out loud here.
+        (notMeasured ? ` This capture also has ${notMeasured} it could not see into.` : '') +
+        // Same reasoning as `notMeasured` above: a missing id may just be past
+        // where a truncated capture stopped, which looks identical to "never
+        // existed" unless this says so. Without this, "no element e5001 in
+        // bundle (5000 records)" reads as "the page has 5000 elements", when
+        // 5000 is only where this capture gave up.
+        (ctx.bundle.truncated
+            ? ` This capture is also truncated — it stopped at the element cap, so the page has more ` +
+                `than ${ctx.bundle.elements.length} elements and "${id}" may exist past where it stopped.`
+            : '') +
+        ' Ids are stable within one capture only — `q find <text>` searches by text, tag or role.');
+}
+/**
+ * Every list verb below counts against `ctx.bundle.elements.length` — "279 of
+ * 5000 records match". On a truncated bundle that reads as "5000 is the whole
+ * page", when 5000 is only where this capture gave up (`look`'s own
+ * `# TRUNCATED:` header line, `digest/render.ts`). Same disclosure
+ * `notMeasuredNote` makes for shadow DOM and iframes, for the same reason: a
+ * bound this file did not choose must never read as a claim of completeness.
+ */
+const truncatedNote = (ctx) => ctx.bundle.truncated
+    ? [
+        `# TRUNCATED: this capture stopped at the element cap; the page has more than ` +
+            `${ctx.bundle.elements.length} elements, so the counts above cover only what was captured`,
+    ]
+    : [];
+/** A positional that has to be a coordinate, with the verb's own usage in the complaint. */
+function coordinate(raw, verb, usage) {
+    const value = raw === undefined ? Number.NaN : Number.parseFloat(raw);
+    if (!Number.isFinite(value)) {
+        throw new QueryError(`${verb} needs numbers: ${usage}. Got "${raw ?? ''}".`);
+    }
+    return value;
+}
+/** Applied to both renderings, never to just one — a cap the JSON does not report is a lie. */
+function cap(items, limit) {
+    if (limit <= 0 || items.length <= limit)
+        return { shown: items, hidden: 0 };
+    return { shown: items.slice(0, limit), hidden: items.length - limit };
+}
+const HIDDEN_NOTE = (hidden) => hidden > 0 ? [`…+${hidden} not listed (--limit 0 for all)`] : [];
+/* -------------------------------------------------------------------------- */
+/** `look` — the digest, which is the format the whole package exists to print. */
+function look(bundle, options = {}) {
+    const ctx = context(bundle);
+    if (options.focus !== undefined) {
+        // `renderDigest` answers an unknown focus with an empty body, which reads
+        // exactly like a page that has nothing in it.
+        const key = options.focus;
+        if (!findNode(ctx.tree, (n) => n.elementId === key || n.tag === key)) {
+            throw new QueryError(`--focus "${key}" matches no layout node in bundle "${bundle.name}".` +
+                ` Nearby ids: ${nearbyIds(ctx, key).join(', ')}. --focus takes an element id or a tag name.`);
+        }
+    }
+    const text = (0, index_js_1.renderDigest)({
+        elements: bundle.elements,
+        truncated: bundle.truncated,
+        viewport: bundle.viewport,
+        notMeasured: bundle.notMeasured,
+    }, {
+        url: bundle.url,
+        viewport: bundle.viewport,
+        state: bundle.name,
+        capturedAt: bundle.capturedAt,
+        strategy: bundle.strategy,
+        ...(bundle.cdpFellBack ? { cdpFellBack: true } : {}),
+    }, {
+        ...(options.focus !== undefined ? { focus: options.focus } : {}),
+        ...(options.edges ? { edges: true } : {}),
+        ...(options.budgetChars !== undefined ? { budgetChars: options.budgetChars } : {}),
+        ...(options.budgetLines !== undefined ? { budgetLines: options.budgetLines } : {}),
+    }).trimEnd();
+    return {
+        text,
+        json: {
+            verb: 'look',
+            bundle: {
+                name: bundle.name,
+                url: bundle.url,
+                capturedAt: bundle.capturedAt,
+                viewport: bundle.viewport,
+                strategy: bundle.strategy,
+                ...(bundle.cdpFellBack ? { cdpFellBack: true } : {}),
+                truncated: bundle.truncated,
+                records: bundle.elements.length,
+                notMeasured: bundle.notMeasured,
+            },
+            digest: text,
+        },
+    };
+}
+/**
+ * `describe` used to print `color <fg> on <bg>` unconditionally, so a
+ * transparent element printed `color rgb(102,102,102) on rgba(0, 0, 0, 0)`.
+ * The word "on" asserts a relationship nothing here measured: text with a
+ * transparent background is drawn on whatever is actually behind it — an
+ * ancestor's background, an image, a gradient, or an unrelated element.
+ *
+ * That relationship is now a real compositing walk
+ * (`snapshot/color.ts`, per `docs/notes/03-color.md` §3-4), and this is the
+ * §4 grammar line in place of the old sentence — but only where the
+ * measurement gate applies (visible, with its own text; §4's "no text, no
+ * ink-on-backdrop question to answer").
+ *
+ * `colorFactFor` has exactly two early-outs, both the same "visible, with
+ * its own text" gate `q color`/`docs/digest.md` §4 states, never a third
+ * reason: `!el.visible` or `!el.text` (see `snapshot/color.ts#colorFactFor`).
+ * So when it returns `null`, this element was never eligible for a color
+ * fact at all — the backdrop compositing walk was never run, not run and
+ * inconclusive.
+ *
+ * P1-2: this used to print "(transparent — what this text is actually drawn
+ * on was not measured)" for the transparent-background case, which is the
+ * same wording the genuine `gradient`/`image`/`under`/`behind` refusals use
+ * for a compositing walk that *was* attempted and came back unmeasured —
+ * implying an attempt that failed, on an element the gate never let one
+ * start for. It also said "this text" unconditionally, which is false on
+ * exactly the element this branch exists to describe: one with no own text
+ * at all. `q color <id>` on the same element already states the true reason
+ * (`no color fact: this element has no own direct text (the gate is
+ * "visible, with its own text")`); this says the same thing, in the same
+ * words, rather than a second, contradictory account of why nothing is
+ * here.
+ */
+function paintValue(el, byId, elements, canvas) {
+    const fact = (0, color_js_1.colorFactFor)(el, byId, elements, canvas);
+    if (fact)
+        return (0, color_js_1.renderColorFact)(fact);
+    const reason = !el.visible ? 'is not visible' : 'has no own direct text';
+    const base = `color ${el.color}; background-color ${el.backgroundColor} ` +
+        `(no color fact: this element ${reason} — the gate is "visible, with its own text")`;
+    // The color-fact grammar folds size/weight/opacity into its own line; the
+    // fallback (gate not met) still owes a reader those, so it states them
+    // itself.
+    return `${base} · ${el.fontSize}/${el.fontWeight}${el.opacity < 1 ? ` · opacity ${num(el.opacity)}` : ''}`;
+}
+/** `q describe <id>` — everything the capture knows about one element. */
+function describe(ctx, args) {
+    const id = args[0];
+    if (!id)
+        throw new QueryError('describe needs an element id: `q describe e12`.');
+    const el = requireElement(ctx, id);
+    const facts = ctx.facts.get(id) ?? [];
+    const rows = [
+        [
+            'box',
+            `@${num(el.rect.x)},${num(el.rect.y)} ${num(el.rect.width)}x${num(el.rect.height)} · content ${num(el.clientWidth)}x${num(el.clientHeight)} · scroll ${num(el.scrollWidth)}x${num(el.scrollHeight)}`,
+        ],
+        [
+            'spacing',
+            `margin ${sides(el.margin)} · padding ${sides(el.padding)} · border ${sides(el.border)} · gap ${num(el.gap.row)}/${num(el.gap.column)}`,
+        ],
+        [
+            'layout',
+            `display:${el.display} position:${el.position} flex-direction:${el.flexDirection} grid-template-columns:${el.gridTemplateColumns}`,
+        ],
+        [
+            'overflow',
+            `x:${el.overflowX} y:${el.overflowY} · text-overflow:${el.textOverflow} white-space:${el.whiteSpace} overflow-wrap:${el.overflowWrap}`,
+        ],
+        [
+            'paint',
+            `${paintValue(el, ctx.byId, ctx.bundle.elements, ctx.bundle.documentBackground)} · text-align:${el.textAlign} visibility:${el.visibility} visible=${el.visible}`,
+        ],
+        [
+            'a11y',
+            `role=${el.role ?? '—'} name=${el.name ? `"${el.name}"` : '—'} heading-level=${el.headingLevel ?? '—'} aria-expanded=${el.ariaExpanded ?? '—'}`,
+        ],
+        ['ids', `testid=${el.testId ?? '—'} dom-id=${el.domId ?? '—'} class=${el.className || '—'}`],
+        ['text', el.text ? `"${el.text}"` : '—'],
+        [
+            'tree',
+            `parent ${el.parentId ?? '—'} · ${el.childIds.length} ${el.childIds.length === 1 ? 'child' : 'children'}${el.childIds.length > 0 ? ` ${el.childIds.join(', ')}` : ''}`,
+        ],
+    ];
+    if (el.clip) {
+        const c = el.clip;
+        rows.push([
+            'clip',
+            `by ${c.by} ${c.byTag} [overflow:${c.overflow}, ${c.scrollable ? 'scrollable' : 'not scrollable'}]` +
+                ` · hidden top ${num(c.hidden.top)} right ${num(c.hidden.right)} bottom ${num(c.hidden.bottom)} left ${num(c.hidden.left)}` +
+                ` · ${num(c.visible.width)}x${num(c.visible.height)} visible`,
+        ]);
+    }
+    if (ctx.bundle.truncated) {
+        // This one element is real either way -- `requireElement` found it -- but
+        // its *tree* (parent/children ids just above) can itself be capped, so
+        // the same disclosure `truncatedNote` makes for the list verbs belongs
+        // here too, not just on the "no such element" error path.
+        rows.push([
+            'truncated',
+            `this capture stopped at the element cap (${ctx.bundle.elements.length} records) — more elements may exist past where it stopped`,
+        ]);
+    }
+    // The head line is byte-identical to the one `look` prints for this element,
+    // facts included, so an id read off a digest lands somewhere recognisable.
+    // There is no separate `facts` row: restating them below would be the digest
+    // saying one thing twice, which is what the step-2 grammar redesign removed.
+    const text = [
+        digestLine(el, facts.map((f) => f.text)),
+        ...rows.map(([key, value]) => `  ${key.padEnd(9)}${value}`),
+    ].join('\n');
+    return {
+        text,
+        json: {
+            verb: 'describe',
+            element: el,
+            facts: facts.map((f) => ({ kind: f.kind, text: f.text })),
+            parent: el.parentId,
+            children: el.childIds,
+            clip: el.clip ?? null,
+            inLayoutTree: findNode(ctx.tree, (n) => n.elementId === id) !== null,
+            truncated: ctx.bundle.truncated,
+            notMeasured: ctx.bundle.notMeasured,
+        },
+    };
+}
+/**
+ * The compound token a digest line actually prints: `tag.role` or
+ * `tag#testid`, no space between the tag and its sigil (`digestLine` above
+ * and `render.ts`'s `label()` are the two producers). Mirrors
+ * `digest/parse.ts`'s own annotation grammar — `[.#][^\s"]+` after a bare tag
+ * — so the query side can never accept a shape the parser would reject.
+ *
+ * Before this, an agent that read `li.listitem` off a digest line and pasted
+ * it into `q find` got zero matches, because `find` only ever matched `tag`,
+ * `role` or `testId` each whole and alone: the exact string the tool itself
+ * printed was not valid input to the tool.
+ *
+ * The tag half allows a hyphen — `[a-zA-Z][a-zA-Z0-9-]*`, the same shape
+ * `digest/parse.ts`'s own `idTagMatch` uses — because every custom element
+ * tag name contains one (the platform requires it: `sl-menu`, `md-select`).
+ * Before this allowed it, `sl-menu.menu` off a digest line for a web
+ * component matched nothing either, for the identical reason `li.listitem`
+ * used to: the regex accepted the shape a plain HTML tag takes and rejected
+ * the shape a custom element's tag actually takes.
+ */
+const ANNOTATED_QUERY = /^([a-zA-Z][a-zA-Z0-9-]*)?([.#])([^\s"]+)$/;
+function parseAnnotatedQuery(needle) {
+    const match = ANNOTATED_QUERY.exec(needle);
+    if (!match)
+        return null;
+    const [, tag, sigil, value] = match;
+    if (!value)
+        return null;
+    return {
+        tag: tag ? tag.toLowerCase() : null,
+        field: sigil === '#' ? 'testId' : 'role',
+        value: value.toLowerCase(),
+    };
+}
+/**
+ * The one honest sentence a zero-match compound query gets. Not a suggestion
+ * engine — it names what was tried (the query parses as the digest's own
+ * `tag.role` / `tag#testid` form, and that exact combination was searched)
+ * and the two things trying each half alone would tell the caller.
+ *
+ * `#` here means test id, never a dom id — CSS's own `#id` convention says
+ * otherwise, and `diff`'s renderer produced `#domId` compounds before B9,
+ * so a needle typed or copied with that expectation (`table#hnmain` meaning
+ * "dom id hnmain") parses fine but searches the wrong field entirely. The
+ * plain "no element has tag X with test id Y" that used to be the whole
+ * message is true about the one field this compound form actually checks,
+ * but says nothing about the field it did not -- dom id -- so a reader who
+ * meant dom id reads a bare negative and has no way to tell "does not
+ * exist" from "exists, under a field this form never searches" (B9-routed).
+ * When the bare value *is* some element's dom id, this names it -- a
+ * positive fact about the field the compound form skipped, not a second,
+ * broader negative it never earned.
+ */
+function annotatedZeroHint(ctx, query) {
+    const field = query.field === 'testId' ? 'test id' : 'role';
+    const halves = query.tag ? [query.tag, query.value] : [query.value];
+    const scope = query.tag
+        ? `tag "${query.tag}" with ${field} "${query.value}"`
+        : `${field} "${query.value}"`;
+    const domMatch = query.field === 'testId'
+        ? ctx.bundle.elements.find((candidate) => candidate.domId?.toLowerCase() === query.value &&
+            (query.tag === null || candidate.tag === query.tag))
+        : undefined;
+    const domNote = domMatch
+        ? ` "${query.value}" is a dom id on ${domMatch.id} -- \`#\` in this compound form means test ` +
+            `id, not dom id; \`q find ${query.value}\` matches dom ids as a bare field.`
+        : '';
+    return (` "${needleFor(query)}" also parses as the digest's tag+${field} form; no element has ${scope}.` +
+        `${domNote} Try ${halves.map((h) => `\`q find ${h}\``).join(' or ')} to search one half alone.`);
+}
+const needleFor = (query) => `${query.tag ?? ''}${query.field === 'testId' ? '#' : '.'}${query.value}`;
+/**
+ * A digest line truncates text and the accessible name to 30 characters and
+ * appends this glyph when it does — usually the record behind the line never
+ * contains it, so a needle copied verbatim off a digest line, ellipsis
+ * included, would otherwise fail `.includes()` against every element's
+ * stored (untruncated) text: the rendered form and the queryable form would
+ * disagree on one character.
+ *
+ * "Usually", not "never": a record's own real, complete text can end in this
+ * glyph too — a page's own "See all…" link is nine characters of real
+ * content, not a truncation artifact. Stripping it unconditionally used to
+ * turn that needle into "See all", which then also matched "See allowance
+ * details" right along with it — a false positive `q find` is supposed to be
+ * unable to produce. `matchNeedle` below tries the needle exactly as given
+ * first, and only strips this glyph as a fallback when the literal needle
+ * finds nothing.
+ */
+const ELLIPSIS = '…';
+/**
+ * `e13`, `e0` — the id shape every digest line starts with. `collect.ts`'s
+ * `nextId` is the only producer and it is always the letter `e`, so this is
+ * deliberately narrower than "letters then digits": a real tag like `h1` or
+ * `h2` fits that looser shape too, and would get this hint instead of an
+ * honest "no such tag in this bundle".
+ */
+const ID_SHAPE = /^e\d+$/;
+/**
+ * `find` searches text, not ids — `q describe <id>` does, and its own error
+ * already points here for the reverse mix-up. An id-shaped needle that
+ * exists in this bundle gets routed straight to `describe`. One that does
+ * not exist must not: before this checked `ctx.byId`, `q find e99999` on a
+ * bundle with no `e99999` still said "try `q describe e99999`", which itself
+ * exits 1 — a hint that sends the caller into a second dead end instead of
+ * naming what was wrong. That case gets the same nearby-id hint `describe`
+ * gives instead.
+ */
+function idShapedHint(ctx, needle) {
+    if (ctx.byId.has(needle)) {
+        return (` "${needle}" looks like an element id, not a search term. Ids are not searched by ` +
+            `\`find\` — try \`q describe ${needle}\`.`);
+    }
+    const near = nearbyIds(ctx, needle);
+    return (` "${needle}" looks like an element id, but no element has that id in bundle "${ctx.bundle.name}" ` +
+        `(${ctx.bundle.elements.length} records).` +
+        (near.length > 0 ? ` Nearby ids: ${near.join(', ')}.` : ''));
+}
+/** One matching pass against a single needle value: exact fields matched whole, text and the
+ * accessible name matched as substrings, plus the compound `tag.role`/`tag#testid` form. */
+function matchNeedle(ctx, raw) {
+    const n = raw.toLowerCase();
+    const annotated = parseAnnotatedQuery(raw);
+    const hits = ctx.bundle.elements.filter((el) => {
+        if (el.tag === n ||
+            el.role?.toLowerCase() === n ||
+            el.testId?.toLowerCase() === n ||
+            el.domId?.toLowerCase() === n ||
+            el.text.toLowerCase().includes(n) ||
+            (el.name?.toLowerCase().includes(n) ?? false)) {
+            return true;
+        }
+        if (!annotated)
+            return false;
+        if (annotated.tag && el.tag !== annotated.tag)
+            return false;
+        const field = annotated.field === 'testId' ? el.testId : el.role;
+        return field?.toLowerCase() === annotated.value;
+    });
+    return { hits, annotated };
+}
+/**
+ * `q find <text|tag|role|tag.role|tag#testid>` — one needle against several
+ * fields.
+ *
+ * Tag, role, test id and DOM id are names and are matched whole; text and the
+ * accessible name are prose and are matched as substrings. `class` is matched
+ * against nothing at all, per the step-1 finding that class tokens are churn.
+ * A needle shaped like a digest annotation (`li.listitem`, `button#save-btn`,
+ * or the bare `.role`/`#testid` half) additionally matches conjunctively on
+ * tag and role/test id together — see `parseAnnotatedQuery` above.
+ */
+function find(ctx, args, limit) {
+    const needle = args[0];
+    if (!needle)
+        throw new QueryError('find needs something to look for: `q find "Save"`.');
+    // The needle exactly as given, first — see the `ELLIPSIS` doc comment for
+    // why this cannot unconditionally strip a trailing ellipsis before it
+    // compares anything. Only when that finds nothing, and the needle ends in
+    // the digest's truncation glyph, retry with the glyph stripped: the case
+    // this fallback exists for is a needle copied off a digest line, where the
+    // glyph was appended by `digestLine`'s own 30-character truncation and the
+    // record behind the line never contained it.
+    let { hits, annotated } = matchNeedle(ctx, needle);
+    if (hits.length === 0 && needle.endsWith(ELLIPSIS)) {
+        const trimmed = needle.slice(0, -ELLIPSIS.length);
+        if (trimmed) {
+            const fallback = matchNeedle(ctx, trimmed);
+            if (fallback.hits.length > 0) {
+                hits = fallback.hits;
+                annotated = fallback.annotated;
+            }
+        }
+    }
+    const { shown, hidden } = cap(hits, limit);
+    const zeroHint = hits.length === 0
+        ? annotated
+            ? annotatedZeroHint(ctx, annotated)
+            : ID_SHAPE.test(needle)
+                ? idShapedHint(ctx, needle)
+                : ''
+        : '';
+    const header = `# find "${needle}" — ${hits.length} of ${ctx.bundle.elements.length} records match on tag, role, test id, dom id, text or accessible name` +
+        zeroHint;
+    return {
+        text: [
+            header,
+            ...truncatedNote(ctx),
+            ...notMeasuredNote(ctx),
+            ...shown.map((el) => digestLine(el, factTexts(ctx, el.id))),
+            ...HIDDEN_NOTE(hidden),
+        ].join('\n'),
+        json: {
+            verb: 'find',
+            query: needle,
+            total: hits.length,
+            hidden,
+            truncated: ctx.bundle.truncated,
+            notMeasured: ctx.bundle.notMeasured,
+            matches: shown.map((el) => ({
+                id: el.id,
+                tag: el.tag,
+                role: el.role,
+                name: el.name,
+                text: el.text,
+                rect: el.rect,
+                facts: factTexts(ctx, el.id),
+            })),
+        },
+    };
+}
+/** Records that never reached the layout tree, stated rather than left implicit. */
+const treeNote = (ctx) => ctx.notInTree > 0
+    ? [
+        `# ${ctx.notInTree} of ${ctx.bundle.elements.length} records are not layout nodes (invisible, zero-size, SVG internals, or folded into a wrapper) and cannot be hit`,
+    ]
+    : [];
+/**
+ * `formatNotMeasured` (`snapshot/not-measured.ts`) returns `null` for a walk
+ * capture with zero *open* shadow roots -- correct for the digest identity
+ * line, which discloses the walk/closed-roots blind spot on its own strategy
+ * segment regardless of count (`digest/render.ts`'s `strategyLabelFor`,
+ * `# dnumb digest v2 ... — walk (closed shadow roots undetectable)`). None of
+ * the `q` verbs render that identity line, so `formatNotMeasured` alone is
+ * their *only* vehicle for this disclosure -- and it stayed silent on
+ * exactly the bundles where a walk capture's blindness to shadow content is
+ * least visible: a page that happened to have no *open* shadow root looks
+ * identical to a page with none at all, even though a walk capture cannot
+ * see into a shadow root's content either way, open or closed (B12). This
+ * wraps the formatter so that blind spot is never gated on a nonzero count
+ * for the one capture path where the count itself can never say "no shadow
+ * content exists".
+ */
+function coverageCaveat(ctx) {
+    const measured = (0, not_measured_js_1.formatNotMeasured)(ctx.bundle.notMeasured);
+    if (measured)
+        return measured;
+    return ctx.bundle.notMeasured.shadowRoots.closed === 'unknown'
+        ? 'not measured: shadow DOM (walk capture — closed shadow roots are undetectable, and no ' +
+            'shadow root content is visible to this strategy)'
+        : null;
+}
+/**
+ * Shadow DOM and iframe content this capture never saw, stated for the same
+ * reason as `treeNote`: a query verb that comes back empty or short and says
+ * nothing about this reads as "not on the page", and it may only be "not in
+ * this bundle".
+ */
+const notMeasuredNote = (ctx) => {
+    const line = coverageCaveat(ctx);
+    return line ? [`# ${line} — a match inside one of these would not appear here`] : [];
+};
+/**
+ * `q at <x> <y>` — the vision→geometry bridge: a model reads a coordinate off a
+ * screenshot and asks what is there.
+ *
+ * Innermost first. Paint order would be the better answer for stacked content
+ * and the CDP capture does request `paintOrders`, but spec 1 records do not
+ * carry it, so ordering is by ascending area and the header says so rather than
+ * implying a z-order the data cannot support.
+ */
+function at(ctx, args, limit) {
+    const x = coordinate(args[0], 'at', '`q at 120 240`');
+    const y = coordinate(args[1], 'at', '`q at 120 240`');
+    const hits = (0, region_query_js_1.nodesAtPoint)(ctx.tree, x, y);
+    const { shown, hidden } = cap(hits, limit);
+    const header = `# at ${num(x)},${num(y)} — ${hits.length} ${hits.length === 1 ? 'node contains' : 'nodes contain'} this point, innermost first`;
+    return {
+        text: [
+            header,
+            ...truncatedNote(ctx),
+            ...treeNote(ctx),
+            ...notMeasuredNote(ctx),
+            ...shown.map((node) => nodeLine(ctx, node)),
+            ...HIDDEN_NOTE(hidden),
+        ].join('\n'),
+        json: {
+            verb: 'at',
+            point: { x, y },
+            total: hits.length,
+            hidden,
+            truncated: ctx.bundle.truncated,
+            notInTree: ctx.notInTree,
+            notMeasured: ctx.bundle.notMeasured,
+            matches: shown.map((node) => nodeMatch(ctx, node)),
+        },
+    };
+}
+/** `q within <x> <y> <w> <h>` — partial overlap counts, most-overlapping first. */
+function within(ctx, args, limit) {
+    const usage = '`q within 0 0 400 300`';
+    const x = coordinate(args[0], 'within', usage);
+    const y = coordinate(args[1], 'within', usage);
+    const width = coordinate(args[2], 'within', usage);
+    const height = coordinate(args[3], 'within', usage);
+    if (width <= 0 || height <= 0) {
+        throw new QueryError(`within needs a positive width and height; got ${num(width)}x${num(height)}.`);
+    }
+    const hits = (0, region_query_js_1.nodesInRegion)(ctx.tree, { x, y, width, height });
+    const { shown, hidden } = cap(hits, limit);
+    const header = `# within ${num(x)},${num(y)} ${num(width)}x${num(height)} — ${hits.length} ${hits.length === 1 ? 'node overlaps' : 'nodes overlap'} this region, largest overlap first`;
+    return {
+        text: [
+            header,
+            ...truncatedNote(ctx),
+            ...treeNote(ctx),
+            ...notMeasuredNote(ctx),
+            ...shown.map((m) => nodeLine(ctx, m.node, `∩${num(round(m.intersectionArea))}px²`)),
+            ...HIDDEN_NOTE(hidden),
+        ].join('\n'),
+        json: {
+            verb: 'within',
+            region: { x, y, width, height },
+            total: hits.length,
+            hidden,
+            truncated: ctx.bundle.truncated,
+            notInTree: ctx.notInTree,
+            notMeasured: ctx.bundle.notMeasured,
+            matches: shown.map((m) => ({
+                ...nodeMatch(ctx, m.node),
+                intersectionArea: m.intersectionArea,
+            })),
+        },
+    };
+}
+/** A signed per-axis gap, with the sign spelled out — `-18` alone reads as a typo. */
+const axisGap = (value) => value >= 0 ? `+${num(value)} gap` : `${num(value)} overlap`;
+/**
+ * `nodeMatch` shaped, for an `ElementRecord` rather than a `LayoutNode` --
+ * `distance` and `nearest` both take element ids, but only `nearest` walks
+ * the tree already (`findNode`). `distance` is purely geometric (it reads
+ * `a.rect`/`b.rect` directly, per its own doc comment) and answerable for an
+ * id that never became its own layout node, so it cannot require one the way
+ * `nodeMatch` does. When the element *is* a tree node, this reuses
+ * `nodeMatch` verbatim -- same fields, same order -- so `--json` never
+ * disagrees with the tree-node shape `at`/`within`/`nearest` already print;
+ * when it is not, it falls back to the same fields `nodeMatch` would carry
+ * anyway (role/name/text/facts come from `ctx.byId`, not from tree
+ * membership), just without a `kind` no layout node exists to supply (B10).
+ */
+function elementMatch(ctx, el) {
+    const node = findNode(ctx.tree, (n) => n.elementId === el.id);
+    if (node)
+        return nodeMatch(ctx, node);
+    return {
+        id: el.id,
+        tag: el.tag,
+        rect: el.rect,
+        ...(el.role ? { role: el.role } : {}),
+        ...(el.name ? { name: el.name } : {}),
+        ...(el.text ? { text: el.text } : {}),
+        facts: factTexts(ctx, el.id),
+    };
+}
+/** `q distance <idA> <idB>` — edge-to-edge, per axis, and centre to centre. */
+function distanceBetween(ctx, args) {
+    const [idA, idB] = args;
+    if (!idA || !idB)
+        throw new QueryError('distance needs two element ids: `q distance e12 e18`.');
+    const a = requireElement(ctx, idA);
+    const b = requireElement(ctx, idB);
+    const d = (0, distances_js_1.distance)(a.rect, b.rect);
+    return {
+        text: [
+            digestLine(a, factTexts(ctx, a.id)),
+            digestLine(b, factTexts(ctx, b.id)),
+            `edge ${num(d.edge)} · center ${num(d.center)} · dx ${axisGap(d.dx)} · dy ${axisGap(d.dy)}`,
+            ...notMeasuredNote(ctx),
+        ].join('\n'),
+        json: {
+            verb: 'distance',
+            // Used to be `{ id, tag, rect }` alone -- role, name, text and facts
+            // all printed on the text lines above but silently dropped from
+            // `--json`, the exact defect this file's own header says `--json` can
+            // never commit (B10): the same fix `nearest` already got, carried
+            // across to the one other verb `nodeMatch`-shaped data never reached.
+            a: elementMatch(ctx, a),
+            b: elementMatch(ctx, b),
+            edge: d.edge,
+            center: d.center,
+            dx: d.dx,
+            dy: d.dy,
+            truncated: ctx.bundle.truncated,
+            notMeasured: ctx.bundle.notMeasured,
+        },
+    };
+}
+/** `q nearest <id>` — the k closest layout nodes by edge distance. */
+function nearestTo(ctx, args, k) {
+    const id = args[0];
+    if (!id)
+        throw new QueryError('nearest needs an element id: `q nearest e12`.');
+    requireElement(ctx, id);
+    if (!findNode(ctx.tree, (n) => n.elementId === id)) {
+        // Distance is computed between tree nodes, and the tree drops invisible
+        // boxes and folds wrapper chains into their child. Naming the surviving
+        // ancestor turns a dead end into the next command.
+        let ancestor = ctx.byId.get(id)?.parentId ?? null;
+        while (ancestor && !findNode(ctx.tree, (n) => n.elementId === ancestor)) {
+            ancestor = ctx.byId.get(ancestor)?.parentId ?? null;
+        }
+        throw new QueryError(`"${id}" is in bundle "${ctx.bundle.name}" but is not its own layout node — it is invisible, zero-size, or folded into a wrapper.` +
+            (ancestor
+                ? ` Its nearest surviving ancestor is ${ancestor}: try \`q nearest ${ancestor}\`.`
+                : ' Run `look` to see which ids are layout nodes.') +
+            ` \`q describe ${id}\` still reports its geometry.`);
+    }
+    const results = (0, distances_js_1.nearest)(ctx.tree, id, k);
+    const header = `# nearest ${id} — ${results.length} closest by edge distance, ancestors and descendants excluded (--k <n> for more)`;
+    return {
+        text: [
+            header,
+            ...truncatedNote(ctx),
+            ...notMeasuredNote(ctx),
+            ...results.map((r) => {
+                const node = findNode(ctx.tree, (n) => n.elementId === r.id);
+                const suffix = `edge ${num(r.edge)} · dx ${axisGap(r.dx)} · dy ${axisGap(r.dy)}`;
+                return node ? nodeLine(ctx, node, suffix) : `${r.id} ${suffix}`;
+            }),
+        ].join('\n'),
+        json: {
+            verb: 'nearest',
+            id,
+            k,
+            truncated: ctx.bundle.truncated,
+            notMeasured: ctx.bundle.notMeasured,
+            // `nearest()` (`analysis/distances.ts`) returns only `{id, edge, dx,
+            // dy}` — the geometry `nodeMatch` carries (rect, tag, role, name,
+            // facts) is exactly what `at`/`within` put in *their* `--json`, and
+            // dropping it here for `nearest` alone falsified this file's own
+            // header claim that `--json` never reports less than the text: the
+            // text rendering above resolves each neighbour through `nodeLine`,
+            // which prints the digest line, facts included.
+            neighbours: results.map((r) => {
+                const node = findNode(ctx.tree, (n) => n.elementId === r.id);
+                return {
+                    ...(node ? nodeMatch(ctx, node) : { id: r.id }),
+                    edge: r.edge,
+                    dx: r.dx,
+                    dy: r.dy,
+                };
+            }),
+        },
+    };
+}
+/** `q facts` — every element carrying a fact, one per line, in document order. */
+function facts(ctx, limit) {
+    const carrying = ctx.bundle.elements.filter((el) => ctx.facts.has(el.id));
+    const { shown, hidden } = cap(carrying, limit);
+    const header = `# facts — ${carrying.length} of ${ctx.bundle.elements.length} records ${carrying.length === 1 ? 'carries' : 'carry'} facts`;
+    return {
+        text: [
+            header,
+            ...truncatedNote(ctx),
+            ...notMeasuredNote(ctx),
+            ...shown.map((el) => digestLine(el, factTexts(ctx, el.id))),
+            ...HIDDEN_NOTE(hidden),
+        ].join('\n'),
+        json: {
+            verb: 'facts',
+            total: carrying.length,
+            hidden,
+            truncated: ctx.bundle.truncated,
+            notMeasured: ctx.bundle.notMeasured,
+            elements: shown.map((el) => ({
+                id: el.id,
+                tag: el.tag,
+                rect: el.rect,
+                facts: (ctx.facts.get(el.id) ?? []).map((f) => ({ kind: f.kind, text: f.text })),
+            })),
+        },
+    };
+}
+/** Integer px when exact, one decimal otherwise — the same rounding facts.ts
+ * and clip.ts use for a measurement, applied to font size and stroke width. */
+const colorPx = (n) => Number.isInteger(n) ? String(n) : n.toFixed(1).replace(/\.0$/, '');
+function sizeRangeLabel(pxs) {
+    const min = Math.min(...pxs);
+    const max = Math.max(...pxs);
+    return min === max ? `${colorPx(min)}px` : `${colorPx(min)}-${colorPx(max)}px`;
+}
+function weightRangeLabel(weights) {
+    const uniq = [...new Set(weights)].sort((a, b) => a - b);
+    return uniq.length === 1 ? String(uniq[0]) : `${uniq[0]}-${uniq[uniq.length - 1]}`;
+}
+/** Rows sort by ratio ascending, unmeasured last -- presentation, never
+ * adjudication (`docs/notes/03-color.md` §6: "the sort is disclosed" and
+ * nothing is dropped). Ties (every unmeasured row shares "no ratio") break
+ * by element count, then alphabetically, so the order is stable and does not
+ * depend on capture-time happenstance. */
+function sortColorPairs(pairs) {
+    return [...pairs].sort((a, b) => {
+        if (a.ratio !== null && b.ratio !== null && a.ratio !== b.ratio)
+            return a.ratio - b.ratio;
+        if ((a.ratio === null) !== (b.ratio === null))
+            return a.ratio === null ? 1 : -1;
+        if (b.elementIds.length !== a.elementIds.length)
+            return b.elementIds.length - a.elementIds.length;
+        return `${a.fg} ${a.bgLabel}`.localeCompare(`${b.fg} ${b.bgLabel}`);
+    });
+}
+const COLOR_EXAMPLE_CAP = 6;
+/**
+ * A pair's effective-opacity values, deduped and sorted -- the raw material
+ * for both `pairRow`'s token and `pairJson`'s field. `groupColorFacts`
+ * (`snapshot/color.ts`) folds a pair down to `fg`/`bgLabel`/`ratio`/count/
+ * size/weight and drops `effectiveOpacity` entirely, so a pair carries no
+ * memory of it on its own; this recovers it from the ungrouped facts the
+ * same way `pairRow`'s `examples` recovers element ids, keyed by the same
+ * `elementIds` the pair already carries. `null` on a `ColorFact` means "at
+ * full opacity" (`ColorFact.effectiveOpacity`'s own doc comment), so those
+ * are filtered out rather than treated as a measurement of zero.
+ */
+function pairOpacities(elementIds, factsById) {
+    const values = elementIds
+        .map((id) => factsById.get(id)?.effectiveOpacity)
+        .filter((o) => o !== null && o !== undefined);
+    return [...new Set(values)].sort((a, b) => a - b);
+}
+/**
+ * A closed `sl-dialog` with `opacity:0` composites to `ratio 1.00` on every
+ * descendant -- correct arithmetic, but a reader who does not also see
+ * `opacity ×0` reads that row as the page's worst *visible* contrast
+ * problem, when the counter-fact that explains the number is exactly what
+ * made it uninformative. `q describe` and `q color <id>` both keep this
+ * token (`renderColorFact`); `q color`'s grouped rows dropped it the moment
+ * `groupColorFacts` folded per-element facts into a pair (A6-routed). Same
+ * range convention as `sizeRangeLabel`/`weightRangeLabel` beside it: a
+ * single value prints bare, a spread prints as `min-max`.
+ */
+const opacityToken = (opacities) => opacities.length === 0
+    ? ''
+    : `    opacity ×${opacities.length === 1 ? num(opacities[0]) : `${num(opacities[0])}-${num(opacities[opacities.length - 1])}`}`;
+function pairRow(pair, opacities) {
+    const label = `${pair.fg} on ${pair.bgLabel}`;
+    const ratio = pair.ratio !== null ? pair.ratio.toFixed(2) : 'unmeasured';
+    const count = `${pair.elementIds.length} ${pair.elementIds.length === 1 ? 'el' : 'els'}`;
+    const sizes = `${sizeRangeLabel(pair.fontSizesPx)}/${weightRangeLabel(pair.weights)}`;
+    const examples = pair.elementIds.length > COLOR_EXAMPLE_CAP
+        ? `${pair.elementIds.slice(0, COLOR_EXAMPLE_CAP).join(', ')}, …`
+        : pair.elementIds.join(', ');
+    return `${label}    ratio ${ratio}    ${count}    ${sizes}${opacityToken(opacities)}    ${examples}`;
+}
+function pairJson(pair, opacities) {
+    return {
+        fg: pair.fg,
+        bg: pair.bgLabel,
+        ratio: pair.ratio,
+        ratioReason: pair.ratioReason,
+        fontSizePx: [Math.min(...pair.fontSizesPx), Math.max(...pair.fontSizesPx)],
+        fontWeight: [...new Set(pair.weights)].sort((a, b) => a - b),
+        // `null` when every element in this pair is at full opacity -- same
+        // "nothing to disclose" convention `effectiveOpacity` itself uses.
+        opacity: opacities.length > 0 ? opacities : null,
+        elements: pair.elementIds,
+    };
+}
+/** `q color` — one row per (ink, backdrop) pair, ratio ascending, unmeasured
+ * last (`docs/notes/03-color.md` §6). Thousands of elements compress to
+ * dozens of rows on a real page: the token discipline this verb exists for. */
+function colorPairs(ctx, limit) {
+    const colorFacts = (0, color_js_1.colorFactsForAll)(ctx.bundle.elements, ctx.bundle.documentBackground);
+    const factsById = new Map(colorFacts.map((f) => [f.elementId, f]));
+    const pairs = sortColorPairs((0, color_js_1.groupColorFacts)(colorFacts));
+    const unmeasured = colorFacts.filter((f) => f.ratio === null).length;
+    const { shown, hidden } = cap(pairs, limit);
+    const opacitiesFor = (pair) => pairOpacities(pair.elementIds, factsById);
+    const header = `# color — ${pairs.length} fg/bg ${pairs.length === 1 ? 'pair' : 'pairs'} across ` +
+        `${colorFacts.length} text ${colorFacts.length === 1 ? 'element' : 'elements'}` +
+        (unmeasured > 0 ? `; ${unmeasured} unmeasured` : '');
+    return {
+        text: [
+            header,
+            ...truncatedNote(ctx),
+            ...notMeasuredNote(ctx),
+            ...shown.map((pair) => pairRow(pair, opacitiesFor(pair))),
+            ...HIDDEN_NOTE(hidden),
+        ].join('\n'),
+        json: {
+            verb: 'color',
+            pairs: pairs.length,
+            textElements: colorFacts.length,
+            unmeasured,
+            hidden,
+            truncated: ctx.bundle.truncated,
+            rows: shown.map((pair) => pairJson(pair, opacitiesFor(pair))),
+        },
+    };
+}
+/** `q color --all` — one line per gated element, same convention as `q facts`. */
+function colorAll(ctx, limit) {
+    const colorFacts = (0, color_js_1.colorFactsForAll)(ctx.bundle.elements, ctx.bundle.documentBackground);
+    const { shown, hidden } = cap(colorFacts, limit);
+    const header = `# color --all — ${colorFacts.length} text elements`;
+    const lineFor = (fact) => {
+        const el = ctx.byId.get(fact.elementId);
+        const head = el ? digestLine(el, []) : fact.elementId;
+        return `${head} ${(0, color_js_1.renderColorFact)(fact)}`;
+    };
+    return {
+        text: [
+            header,
+            ...truncatedNote(ctx),
+            ...notMeasuredNote(ctx),
+            ...shown.map(lineFor),
+            ...HIDDEN_NOTE(hidden),
+        ].join('\n'),
+        json: {
+            verb: 'color',
+            all: true,
+            total: colorFacts.length,
+            hidden,
+            truncated: ctx.bundle.truncated,
+            elements: shown.map((f) => ({ id: f.elementId, ...f })),
+        },
+    };
+}
+/**
+ * `textShadow`, `textStrokeWidth` and `textStrokeColor` were added to
+ * `ElementRecord` for color capture and are required, not optional --
+ * `snapshot/types.ts` declares all three as plain `string`, every real
+ * capture path populates them, and `parseBundle` backfills them for a
+ * bundle written before the fields existed. The only way one is `undefined`
+ * at runtime is a hand-built record that skips a field its own type
+ * declares required -- TypeScript cannot catch that at the JS boundary a
+ * hand-assembled object or an unvalidated `JSON.parse` crosses. Interpolating
+ * that straight into a sentence prints the literal string `undefined` into
+ * something that otherwise reads as a measurement, which is exactly the
+ * fabrication this package exists to refuse. This mirrors
+ * `snapshot/color.ts`'s own `requireColorField` (not exported, so not
+ * reused directly -- this is the same diagnosis in the same voice, not a
+ * second decision) rather than let a caller substitute a raw `undefined`.
+ */
+function requireStringField(elementId, field, value) {
+    if (typeof value !== 'string') {
+        throw new Error(`dnumb: element "${elementId}" has no "${field}" (added for color capture -- every real ` +
+            'capture sets it, and parseBundle backfills it for a bundle written before this field ' +
+            'existed). A hand-built ElementRecord must include it -- see the type exported from ' +
+            '"@michaelmagan/dnumb/spec", or produce the record with capture()/parseBundle instead of by hand.');
+    }
+    return value;
+}
+/**
+ * `q color <id>` — the single-element long form: the full composite chain
+ * (each layer's own color, alpha and owning ancestor), the overlap finding,
+ * raw vs. effective ink, and shadow/stroke values verbatim
+ * (`docs/notes/03-color.md` §6).
+ */
+function colorDescribe(ctx, args) {
+    const id = args[0];
+    if (!id)
+        throw new QueryError('color needs an element id: `q color e12`.');
+    const el = requireElement(ctx, id);
+    const fact = (0, color_js_1.colorFactFor)(el, ctx.byId, ctx.bundle.elements, ctx.bundle.documentBackground);
+    if (!fact) {
+        // Not a usage error -- the element is real, it simply does not qualify
+        // for a color fact (not visible, or no own text: §4's measurement gate).
+        // Refusing honestly, with the reason, is the whole discipline this
+        // module exists to hold; a thrown error here would hide that reason
+        // behind an exit code instead of printing it.
+        const reason = !el.visible ? 'is not visible' : 'has no own direct text';
+        const text = `${digestLine(el, factTexts(ctx, id))}\nno color fact: this element ${reason} (the gate is "visible, with its own text").`;
+        return {
+            text,
+            json: { verb: 'color', id, applies: false, reason },
+        };
+    }
+    const resolved = (0, color_js_1.resolveBackdrop)(el, ctx.byId, ctx.bundle.documentBackground);
+    const overlay = (0, color_js_1.detectOverlay)(el, ctx.byId, ctx.bundle.elements);
+    const chain = resolved.chain
+        .map((layer) => `${layer.id} ${layer.color} α${layer.alpha.toFixed(2)}`)
+        .join(' → ');
+    const overlaySummary = overlay
+        ? `${overlay.reason} ${overlay.via} -- the ancestor walk below is what it would have found had the overlay not intervened`
+        : 'none found';
+    // `hitStackIds`/`paintOrder` are genuinely nullable (`string[] | null`,
+    // `number | null` in `snapshot/types.ts`) -- an old capture path really
+    // has no such signal, and `null` says that honestly. `!== null` used to
+    // guard this, which also passes for `undefined`: a record whose key is
+    // simply absent (violating the type the same way the string color fields
+    // above can) sailed through and then threw on `.length` a line later.
+    // `Array.isArray` is the same distinction `snapshot/color.ts#detectOverlay`
+    // already draws between "measured as nothing" (a real, empty array or a
+    // real `null`) and "never measured" (the key is not there at all).
+    // `typeof ... === 'number'`, not `!== null`, for the identical reason on
+    // `paintOrder`'s side of the same branch -- `undefined !== null` is also
+    // `true`, which would print `paintOrder (cdp): undefined` instead of
+    // falling through to the honest "no overlap signal" case.
+    const hitSignal = Array.isArray(el.hitStackIds)
+        ? `hit-stack (walk): ${el.hitStackIds.length > 0 ? el.hitStackIds.join(', ') : '(empty)'}`
+        : typeof el.paintOrder === 'number'
+            ? `paintOrder (cdp): ${el.paintOrder}`
+            : 'no overlap signal captured for this element';
+    const rows = [
+        ['grammar', (0, color_js_1.renderColorFact)(fact)],
+        ['chain', chain || '(none)'],
+        ['overlay', overlaySummary],
+        ['overlap-in', hitSignal],
+        [
+            'ink',
+            `raw color:${el.color} opacity:${num(el.opacity)} · effective ${fact.fg}` +
+                (fact.effectiveOpacity !== null
+                    ? ` (opacity ×${num(fact.effectiveOpacity)} combined through ancestors)`
+                    : ''),
+        ],
+        [
+            'shadow',
+            requireStringField(id, 'textShadow', el.textShadow) === 'none'
+                ? 'none'
+                : `raw text-shadow: ${el.textShadow}`,
+        ],
+        [
+            'stroke',
+            requireStringField(id, 'textStrokeWidth', el.textStrokeWidth) === '0px'
+                ? 'none'
+                : `raw -webkit-text-stroke-width:${el.textStrokeWidth} -webkit-text-stroke-color:` +
+                    `${requireStringField(id, 'textStrokeColor', el.textStrokeColor)}`,
+        ],
+    ];
+    const text = [
+        digestLine(el, factTexts(ctx, id)),
+        ...rows.map(([key, value]) => `  ${key.padEnd(11)}${value}`),
+    ].join('\n');
+    return {
+        text,
+        json: {
+            verb: 'color',
+            id,
+            applies: true,
+            fact,
+            chain: resolved.chain,
+            overlay,
+        },
+    };
+}
+/** Dispatches one `q` verb. Throws `QueryError` for anything the caller can fix. */
+function query(bundle, verb, args = [], options = {}) {
+    const known = exports.Q_VERBS.join(' | ');
+    if (!verb)
+        throw new QueryError(`q needs a verb: ${known}.`);
+    if (!exports.Q_VERBS.includes(verb)) {
+        throw new QueryError(`unknown verb "q ${verb}". Known: ${known}.`);
+    }
+    const ctx = context(bundle);
+    const limit = options.limit ?? DEFAULT_LIMIT;
+    switch (verb) {
+        case 'describe':
+            return describe(ctx, args);
+        case 'find':
+            return find(ctx, args, limit);
+        case 'at':
+            return at(ctx, args, limit);
+        case 'within':
+            return within(ctx, args, limit);
+        case 'distance':
+            return distanceBetween(ctx, args);
+        case 'nearest':
+            return nearestTo(ctx, args, options.k ?? DEFAULT_K);
+        case 'facts':
+            return facts(ctx, limit);
+        default:
+            // `color`. `--all` and a specific element id are mutually exclusive
+            // views (the per-element list vs. the single-element long form); an id
+            // wins when both are given, since it is the more specific request.
+            if (args[0] !== undefined)
+                return colorDescribe(ctx, args);
+            return options.all ? colorAll(ctx, limit) : colorPairs(ctx, limit);
+    }
+}