@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/ui_conformance_probe.ts

@@ -60,6 +60,37 @@
  * run now SAYS so. The correspondence problem — getting handles into a handover
  * — is untouched, and nothing here promotes the probe out of shadow.
  *
+ * WHAT THAT RUN NOW REPORTS, and it is a smaller thing than the five rows.
+ * A reference with no handle carries a `page_signature`: per width, how many
+ * rendered leaves of each KIND there are — control, heading, media, text, empty
+ * — a multiset of `<child count>:<row|column|mixed>` over containers with two or
+ * more rendered children, and whether the page overflows horizontally. Counts
+ * and a flag; no aggregate, no coordinate, no size, no tag. It reports a removed
+ * element, a lost control, a container that stopped stacking and a page that
+ * started overflowing.
+ *
+ * AND WHAT IT STILL CANNOT. It establishes no correspondence between a
+ * reference element and a target one, so it can name no node, cannot be matched
+ * against a declared deviation, and is not a finding. Behaviour produces nothing
+ * from it: a removed hover colour and a dead click handler change no leaf, no
+ * arrangement and no overflow, and remain the business of the `interaction`
+ * dimension, which needs handles. A change in size or spacing produces nothing
+ * either, by the same construction that keeps it silent on a faithful port. And
+ * a second defect behind a removed child is masked, because a container that has
+ * lost a child drops out of the multiset entirely. The fixture README registers
+ * all of it, with the one place the reading disagrees with the table it was
+ * measured against.
+ *
+ * SO "IT REPORTS A REMOVED ELEMENT" IS TRUE OF A SINGLE CHANGE AND NOT IN
+ * GENERAL, and the difference is worth the sentence. These are COUNTS: a
+ * removal offset by an addition of the same kind at the same width nets to
+ * nothing, and so does a reparenting that leaves the arrangement multiset
+ * standing. Content removed from inside a heading or a control is invisible for
+ * the same reason the wrapper around one is — the reading does not look in
+ * there. Arrangement is decided over consecutive children in DOM order, so a
+ * flex or grid reorder that changes only visual order produces nothing, and the
+ * overflow flag is horizontal only.
+ *
  * THE NOISE CONTROL. Computed-style comparison over every property fires on
  * font fallbacks and token indirection nobody cares about, so the compared set
  * is curated (`COMPARED_PROPERTIES`) to the properties a design token actually
@@ -146,10 +177,39 @@ export interface NodeObservation {
     click_effect: string | null;
 }
 
+/**
+ * The kinds a leaf is counted as. Four are the roadmap's; `empty` is the
+ * residual and is named rather than folded into `text`, because "a wrapper that
+ * renders nothing" and "a paragraph" are different things to lose.
+ */
+export const LEAF_KINDS = ['control', 'heading', 'media', 'text', 'empty'] as const;
+export type LeafKind = (typeof LEAF_KINDS)[number];
+
+/** One width's reading. Counts and a flag — no coordinate, no size, no tag. */
+export interface WidthSignature {
+    /** Every kind is present, including the zeroes: absent would read as 0 anyway. */
+    leaves: Record<LeafKind, number>;
+    /** A multiset: `<child count>:<row|column|mixed>` to how many containers carry it. */
+    arrangement: Record<string, number>;
+    overflow: boolean;
+}
+
+/** Keyed by viewport width, as a string, because JSON keys are strings. */
+export type PageSignatureReading = Record<string, WidthSignature>;
+
 export interface Observation {
     variant: string;
     source: string;
     nodes: NodeObservation[];
+    /**
+     * OPTIONAL, AND THAT IS THE CONTRACT RATHER THAN A CONVENIENCE. An
+     * observation captured before this field existed has no signature, and a
+     * reader must say `not_available` for it — never "no change", which is the
+     * same fabricated green the five dimensions already refuse. Making the field
+     * required would have forced every committed record to be re-captured on a
+     * host with a browser before anything could read them at all.
+     */
+    signature?: PageSignatureReading;
 }
 
 export interface Declaration {
@@ -180,6 +240,61 @@ export interface DimensionRow {
     reason?: string;
 }
 
+/** One leaf kind whose count moved between the two sides, at one width. */
+export interface LeafChange {
+    kind: LeafKind;
+    reference: number;
+    target: number;
+}
+
+/** One arrangement key whose multiplicity moved. A key absent on a side is 0. */
+export interface ArrangementChange {
+    key: string;
+    reference: number;
+    target: number;
+}
+
+export interface WidthReading {
+    width: string;
+    /** Changed kinds only. An empty array means every kind held. */
+    leaves: LeafChange[];
+    /** Changed keys only. An empty array means the multiset held. */
+    arrangement: ArrangementChange[];
+    /** A PAIR, never a change flag: both sides are stated at every width. */
+    overflow: { reference: boolean; target: boolean };
+}
+
+/**
+ * THE FIXED SENTENCE, and it is fixed because the reading is easy to over-read.
+ * A reader who takes a changed count for a located defect will go looking for
+ * the node it happened to, and there is no such node: this reading never put the
+ * two sides' elements into correspondence, which is the entire reason it can be
+ * taken on a handover with no handles at all.
+ */
+export const PAGE_SIGNATURE_SCOPE =
+    'This reading names kinds of leaf and of container, never nodes. It establishes no ' +
+    'correspondence between a reference element and a target one, so it cannot be matched ' +
+    'against a declared deviation and it is not a finding.';
+
+/**
+ * The handle-free reading as it reaches the artefact.
+ *
+ * A FIELD, NEVER A SIXTH DIMENSION. The five dimension rows answer "was this
+ * node compared, and what diverged"; this answers neither, because it has no
+ * node. Giving it a row would make `findings` a count over two different kinds
+ * of statement and would break the invariant that no dimension is exercised on
+ * zero nodes — which is the one thing the roadmap this comes from was told to
+ * keep untouched.
+ */
+export interface PageSignatureField {
+    status: 'read' | 'not_available';
+    /** Present on `not_available` only, naming which side was missing it. */
+    reason?: string;
+    scope: typeof PAGE_SIGNATURE_SCOPE;
+    /** One entry per viewport width when read; empty when not available. */
+    widths: WidthReading[];
+}
+
 export interface SuppressedDeviation {
     probe_id: string;
     property: string;
@@ -213,6 +328,14 @@ export interface ProbeArtefact {
     dimensions: DimensionRow[];
     findings: Finding[];
     declared_suppressed: SuppressedDeviation[];
+    /**
+     * PRESENT ONLY WHERE THE REFERENCE COLLECTED NO HANDLE. With handles there
+     * are five dimensions that can answer about located nodes, and a second,
+     * weaker reading beside them would be read as corroboration it is not:
+     * a kind-level count agreeing with a per-node comparison adds nothing and
+     * disagreeing with one says nothing about which is right.
+     */
+    page_signature?: PageSignatureField;
 }
 
 // ---------------------------------------------------------------- pure core
@@ -273,6 +396,97 @@ const EMPTY_REFERENCE_REASON =
     'compare against. The capture ran and collected zero nodes: this is a property of the ' +
     'handover, not of this machine.';
 
+/**
+ * The handle-free reading, taken from two captured signatures.
+ *
+ * ABSENT IS `not_available`, NEVER "NO CHANGE", and that is the same contract
+ * `findings: null` carries one level up. An observation captured before the
+ * capture learned to sweep widths has no signature at all; reporting it as
+ * unchanged would be a comparison that never happened, presented as a clean one.
+ * The check runs on BOTH sides, because a reader that only looked at the
+ * reference would say "no change" for a target captured by an older probe.
+ */
+/**
+ * Is one width's record complete enough to be read?
+ *
+ * VALIDATED AT THE BOUNDARY, BECAUSE THE INTERFACE DOES NOT REACH IT. An
+ * observation arrives through `JSON.parse` and an unchecked cast, so
+ * `WidthSignature` is a claim about the file rather than a guarantee. The first
+ * version read a missing leaf count as `a.leaves[k] ?? 0`, which turns a
+ * structurally incomplete record into a confident "this kind is at zero" and
+ * can report a change that is an artefact of the file being short. That is the
+ * fabricated-clean reading the rest of this module refuses, arriving through the
+ * one door nothing was watching.
+ */
+function widthIsComplete(row: unknown): row is WidthSignature {
+    if (!row || typeof row !== 'object') return false;
+    const r = row as Partial<WidthSignature>;
+    if (typeof r.overflow !== 'boolean') return false;
+    if (!r.leaves || typeof r.leaves !== 'object') return false;
+    if (!r.arrangement || typeof r.arrangement !== 'object') return false;
+    // A COUNT IS AN INTEGER. `Number.isFinite` admitted 3.7, which is not a
+    // number of leaves any capture can produce, so a hand-edited or
+    // half-written record carrying one would have been read as a reading.
+    const countable = (v: unknown): boolean => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
+    if (!LEAF_KINDS.every((k) => countable((r.leaves as Record<string, unknown>)[k]))) return false;
+    return Object.values(r.arrangement as Record<string, unknown>).every(countable);
+}
+
+export function readPageSignature(reference: Observation, target: Observation): PageSignatureField {
+    const missing: string[] = [];
+    if (!reference.signature) missing.push('the reference');
+    if (!target.signature) missing.push('the target');
+    const incomplete =
+        !missing.length &&
+        VIEWPORTS.some(
+            (w) => !widthIsComplete(reference.signature?.[String(w)]) || !widthIsComplete(target.signature?.[String(w)]),
+        );
+    if (missing.length || incomplete) {
+        return {
+            status: 'not_available',
+            scope: PAGE_SIGNATURE_SCOPE,
+            reason: missing.length
+                ? `${missing.join(' and ')} carries no page signature, so there was nothing to read. ` +
+                  'An observation captured before the probe swept widths has none; this is not a ' +
+                  'statement that the two pages agree.'
+                : 'a page signature is present but is not complete at every width the probe sweeps — a ' +
+                  'width is absent, or a leaf count or overflow flag is missing or not a count. A short ' +
+                  'record read as zeroes would report a change the file never recorded, so the whole ' +
+                  'reading is withheld. Re-capture rather than read it.',
+            widths: [],
+        };
+    }
+
+    const widths = VIEWPORTS.map((w) => {
+        const key = String(w);
+        const a = reference.signature![key]!;
+        const b = target.signature![key]!;
+        // No `?? 0` here, and the asymmetry with the arrangement block below is
+        // the whole point. Every leaf kind is present in a record the validator
+        // accepted, so a default would only ever paper over a record it rejected.
+        const leaves: LeafChange[] = LEAF_KINDS.filter((k) => a.leaves[k] !== b.leaves[k]).map((k) => ({
+            kind: k,
+            reference: a.leaves[k],
+            target: b.leaves[k],
+        }));
+        // The union of both sides' keys, so a key that exists only in the target
+        // is reported as 0 -> n rather than silently skipped. A multiset read
+        // from one side alone is the add-half blindness the structure dimension
+        // already had to be taught out of.
+        //
+        // `?? 0` IS CORRECT HERE and wrong one block up. The multiset is sparse
+        // by construction: a key absent on a side means no container on that side
+        // had that shape, which is a measured zero, not a short record.
+        const arrangementKeys = [...new Set([...Object.keys(a.arrangement), ...Object.keys(b.arrangement)])].sort();
+        const arrangement: ArrangementChange[] = arrangementKeys
+            .filter((k) => (a.arrangement[k] ?? 0) !== (b.arrangement[k] ?? 0))
+            .map((k) => ({ key: k, reference: a.arrangement[k] ?? 0, target: b.arrangement[k] ?? 0 }));
+        return { width: key, leaves, arrangement, overflow: { reference: a.overflow, target: b.overflow } };
+    });
+
+    return { status: 'read', scope: PAGE_SIGNATURE_SCOPE, widths };
+}
+
 export function evaluate(
     reference: Observation,
     target: Observation,
@@ -309,6 +523,11 @@ export function evaluate(
             })),
             findings: [],
             declared_suppressed: [],
+            // The one branch that carries it. Everything above this line is the
+            // honest statement that nothing was compared; this is the one thing
+            // that could still be said about the pages, and saying it does not
+            // move a single row above out of `not_applicable`.
+            page_signature: readPageSignature(reference, target),
         };
     }
 
@@ -591,6 +810,173 @@ const READ_STYLES = (el: Element, props: readonly string[]): Record<string, stri
     return out;
 };
 
+/**
+ * The handle-free reading, taken in the page. Serialized into the browser by
+ * `page.evaluate`, so it closes over nothing and takes its vocabulary as an
+ * argument.
+ *
+ * WHAT IT DOES NOT LOOK INSIDE, which is the whole design rather than an
+ * optimisation. A control, a heading and a media element are counted as one
+ * leaf each and never descended into. The literal reading — "an element with no
+ * rendered element child" — would make `<button>Save</button>` a control and
+ * `<button><span>Save</span></button>` a text leaf inside a container, so
+ * wrapping a label in a span, which is the most ordinary thing a component
+ * framework does on a faithful port, would read as a lost control. That is the
+ * exact false-positive class the census-by-tag prototype was refuted for, and
+ * refusing to look inside a semantic atom excludes it by construction instead of
+ * by a tolerance. An `<svg>` is the same case from the other side: descending
+ * into its paths would make the count a function of how complex the icon is.
+ *
+ * THE COST, stated rather than discovered later: an `<a>` that wraps a whole
+ * card is one control leaf, and everything inside it is invisible to this
+ * reading. That is a loss of SENSITIVITY, never a false report, and this
+ * reading is built to prefer silence over noise — it is registered as a limit
+ * in the fixture README beside the other two.
+ *
+ * Row, column or mixed is decided from the rendered boxes of consecutive
+ * children and then thrown away: nothing a coordinate could be reconstructed
+ * from reaches the record.
+ *
+ * FLAT ON PURPOSE — no inner helper and no recursion, and that is a constraint
+ * of the carrier rather than a style. This file is run through a transform that
+ * keeps function names, which wraps every named inner function in a `__name`
+ * helper that exists in the module and not in the page. `page.evaluate`
+ * serializes the function and nothing else, so the first version of this
+ * reading threw `ReferenceError: __name is not defined` in the browser on its
+ * first run. An explicit stack has no inner function to be named.
+ */
+const READ_SIGNATURE = (kinds: readonly string[]): {
+    leaves: Record<string, number>;
+    arrangement: Record<string, number>;
+    overflow: boolean;
+} => {
+    // CURATED, NOT EXHAUSTIVE — the same stance `COMPARED_PROPERTIES` takes one
+    // screen up, and stated because the prose around this reads like a semantic
+    // classification rather than a selector list. An element carrying a role
+    // outside this set is counted by what it contains rather than as a control.
+    const CONTROL =
+        'a[href],button,input,select,textarea,summary,[role="button"],[role="link"],' +
+        '[role="checkbox"],[role="switch"],[role="tab"],[role="menuitem"],[role="radio"],' +
+        '[role="slider"],[role="spinbutton"],[role="combobox"],[role="option"],[contenteditable]';
+    const HEADING = 'h1,h2,h3,h4,h5,h6,[role="heading"]';
+    const MEDIA = 'img,svg,canvas,video,audio,picture,iframe,object,embed,[role="img"]';
+
+    const leaves: Record<string, number> = {};
+    for (const k of kinds) leaves[k] = 0;
+    const arrangement: Record<string, number> = {};
+
+    const stack: Element[] = document.body ? [document.body] : [];
+    while (stack.length) {
+        const el = stack.pop() as Element;
+
+        let kind = '';
+        if (el.matches(CONTROL)) kind = 'control';
+        else if (el.matches(HEADING)) kind = 'heading';
+        else if (el.matches(MEDIA)) kind = 'media';
+        if (kind) {
+            leaves[kind] = (leaves[kind] ?? 0) + 1;
+            continue;
+        }
+
+        // A BOXLESS ELEMENT IS TRANSPARENT, NOT ABSENT — the two are opposites
+        // and the first version of this conflated them. "A zero box is not
+        // rendered" is true of the ELEMENT and says nothing about its children:
+        // `display: contents` generates no box at all while rendering its
+        // subtree normally, and a zero-height wrapper with overflowing content
+        // is the same case from the other side. Dropping such an element
+        // together with its subtree made every control inside a
+        // `display: contents` wrapper invisible — measured at 0 where the page
+        // showed 2 — which is the census reporting a loss that did not happen.
+        // So a boxless, non-hidden element is neither a leaf nor a container:
+        // its children are lifted into its parent's list, in document order, and
+        // it contributes nothing of its own. An element that is boxless AND has
+        // no children still contributes nothing, exactly as before.
+        const children: Element[] = [];
+        let liftedText = '';
+        const pending: Element[] = Array.from(el.children);
+        while (pending.length) {
+            const c = pending.shift() as Element;
+            const cs = getComputedStyle(c);
+            if (cs.display === 'none' || cs.visibility === 'hidden') continue;
+            const r = c.getBoundingClientRect();
+            if (r.width > 0 && r.height > 0) {
+                children.push(c);
+                continue;
+            }
+            // A TRANSPARENT ELEMENT STILL RENDERS ITS OWN DIRECT TEXT, and the
+            // first version of this lift did not see it. `children` is elements
+            // only, so `<div style="display: contents">Visible text</div>`
+            // beside a rendered sibling lifted nothing, its parent stayed a
+            // container rather than becoming a text leaf, and the text was
+            // counted nowhere. Measured: `text: 0` on a page that renders it.
+            //
+            // NARROWED TO `display: contents` ON PURPOSE. That is the one case
+            // where the element provably generates no box AND its content is
+            // laid out by the parent, so the text certainly renders. Any other
+            // zero-box element is ambiguous — a `height: 0; overflow: hidden`
+            // wrapper CLIPS its text — and counting there would invent a leaf,
+            // which is the one direction this reading must not fail in. Such an
+            // element keeps lifting its element children and loses its own text:
+            // sensitivity, not a false report.
+            if (cs.display === 'contents') {
+                for (const n of Array.from(c.childNodes)) {
+                    if (n.nodeType === 3) liftedText += n.nodeValue ?? '';
+                }
+            }
+            pending.unshift(...Array.from(c.children));
+        }
+
+        if (children.length === 0) {
+            // RENDERED TEXT, NOT TEXT CONTENT. `textContent` includes the text
+            // of `display: none` and `visibility: hidden` descendants, so a
+            // wrapper whose only content is hidden counted as a text leaf — the
+            // census inventing a leaf the page does not show, which is the exact
+            // mirror of the defect above. `innerText` is the rendered reading and
+            // is the right primitive; `textContent` stays as the fallback for an
+            // element that has no `innerText`, such as a non-HTML one.
+            //
+            // The lifted text is deliberately NOT added on top: `innerText` is
+            // this element's whole RENDERED text and already includes whatever a
+            // transparent child contributed. Crediting it in both places counted
+            // one run twice — measured `text: 2` for a single
+            // `<p><span style="display: contents">hello</span></p>`.
+            const asHtml = el as Partial<HTMLElement>;
+            const shown = typeof asHtml.innerText === 'string' ? asHtml.innerText : (el.textContent ?? '');
+            kind = shown.trim().length ? 'text' : 'empty';
+            leaves[kind] = (leaves[kind] ?? 0) + 1;
+            continue;
+        }
+
+        // A CONTAINER IS NOT CLASSIFIED BY ITS TEXT, which is exactly where the
+        // lifted text would otherwise be lost: this element has a rendered child,
+        // so it never reaches the branch above and its `innerText` is never read.
+        // The text a transparent child contributed is credited here, once, and
+        // only here. Direct text of a container that sits behind no transparent
+        // child stays uncounted — a pre-existing property of counting leaves,
+        // registered as a limit rather than quietly changed under a defect fix.
+        if (liftedText.trim().length) leaves['text'] = (leaves['text'] ?? 0) + 1;
+
+        if (children.length > 1) {
+            let shape = '';
+            for (let i = 1; i < children.length; i += 1) {
+                const a = (children[i - 1] as Element).getBoundingClientRect();
+                const b = (children[i] as Element).getBoundingClientRect();
+                const sharesRows = Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top) > 0;
+                const sharesColumns = Math.min(a.right, b.right) - Math.max(a.left, b.left) > 0;
+                shape += !sharesRows ? 'c' : sharesColumns ? 'm' : 'r';
+            }
+            const axis = /^r+$/.test(shape) ? 'row' : /^c+$/.test(shape) ? 'column' : 'mixed';
+            const key = `${children.length}:${axis}`;
+            arrangement[key] = (arrangement[key] ?? 0) + 1;
+        }
+
+        for (const c of children) stack.push(c);
+    }
+
+    const doc = document.documentElement;
+    return { leaves, arrangement, overflow: doc.scrollWidth > doc.clientWidth };
+};
+
 export async function captureVariant(indexHtml: string): Promise<Observation> {
     const pw = loadPlaywright();
     if (!pw) throw new Error('captureVariant: @playwright/test is not resolvable on this host');
@@ -598,6 +984,7 @@ export async function captureVariant(indexHtml: string): Promise<Observation> {
     const url = pathToFileURL(indexHtml).href;
     const props = [...COMPARED_PROPERTIES];
     const nodes: NodeObservation[] = [];
+    const signature: PageSignatureReading = {};
 
     try {
         const page = await browser.newPage({ viewport: { width: VIEWPORTS[0], height: 900 } });
@@ -606,6 +993,23 @@ export async function captureVariant(indexHtml: string): Promise<Observation> {
             els.map((e) => e.getAttribute('data-probe-id') ?? ''),
         );
 
+        // OUTSIDE THE PER-HANDLE LOOP, which is the one structural thing this
+        // change does. Every width sweep this file had lived inside that loop, so
+        // a page with no handles was never resized at all and the capture of the
+        // commonest input in the tree — a handover carrying no `data-probe-id` —
+        // consisted of opening the page and closing it. Four resizes and one DOM
+        // walk each now happen whether or not a handle is ever found.
+        //
+        // Before the loop rather than after it, so the loop starts from the same
+        // state it always did; the viewport is put back explicitly rather than
+        // left to the loop's own first `setViewportSize`, because relying on that
+        // would couple two things that have no reason to stay coupled.
+        for (const w of VIEWPORTS) {
+            await page.setViewportSize({ width: w, height: 900 });
+            signature[String(w)] = (await page.evaluate(READ_SIGNATURE, [...LEAF_KINDS])) as WidthSignature;
+        }
+        await page.setViewportSize({ width: VIEWPORTS[0], height: 900 });
+
         for (const id of ids.filter(Boolean).sort()) {
             const sel = `[data-probe-id="${id}"]`;
             await page.setViewportSize({ width: VIEWPORTS[0], height: 900 });
@@ -664,7 +1068,7 @@ export async function captureVariant(indexHtml: string): Promise<Observation> {
         await browser.close();
     }
 
-    return { variant: path.basename(path.dirname(indexHtml)), source: indexHtml, nodes };
+    return { variant: path.basename(path.dirname(indexHtml)), source: indexHtml, nodes, signature };
 }
 
 /**