@ggui-ai/ui-visual-tester 0.16.0 → 0.18.0

package/dist/fixture-runtime.d.ts

@@ -29,6 +29,8 @@ type ActionClassification = 'agent-bound' | 'context-bound';
 interface RunInput {
     readonly componentCode: string;
     readonly contract: unknown;
+    /** Parsed JSON of the commit's fixture props; a plain object or nothing. */
+    readonly sampleProps: unknown;
     readonly actionName: string;
     readonly classification: ActionClassification;
     readonly settleMs: number;
@@ -39,13 +41,23 @@ type RunOutcome = {
     readonly diagnostic: string;
 } | {
     readonly status: 'action-not-rendered';
+    readonly diagnostic: string;
 } | {
     readonly status: 'action-no-effect';
     readonly diagnostic: string;
+}
+/** #1040: the named control was never reachable enabled — not measured; `reason` says why. */
+ | {
+    readonly status: 'action-unreachable';
+    readonly reason: 'disabled-after-priming' | 'behind-navigation';
+    readonly diagnostic: string;
 } | {
     readonly status: 'ok';
     readonly dispatchFired: boolean;
     readonly domChanged: boolean;
+    /** Which pass found the control that produced the signal, and how many were clicked to get there. */
+    readonly via?: 'named' | 'fallback';
+    readonly clicked?: number;
 };
 declare global {
     interface Window {

package/dist/fixture-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fixture-runtime.d.ts","sourceRoot":"","sources":["../src/fixture-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,cAAc,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,gBAAgB,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,gBAAgB,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,kBAAkB,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,cAAc,MAAM,0BAA0B,CAAC;AAC3D,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AA0CtC,UAAU,cAAc;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,KAAK,oBAAoB,GAAG,aAAa,GAAG,eAAe,CAAC;AAE5D,UAAU,QAAQ;IAChB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,oBAAoB,CAAC;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,KAAK,UAAU,GACX;IAAE,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACjE;IAAE,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAA;CAAE,GAC1C;IAAE,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACpE;IACE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEN,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,wBAAwB,CAAC,EAAE,cAAc,EAAE,CAAC;QAC5C,gCAAgC,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;QAC5E,QAAQ,CAAC,EAAE,YAAY,CAAC;QACxB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;QACvB,iBAAiB,CAAC,EAAE,OAAO,gBAAgB,CAAC;QAC5C,iBAAiB,CAAC,EAAE,OAAO,gBAAgB,CAAC;QAC5C,mBAAmB,CAAC,EAAE,OAAO,kBAAkB,CAAC;QAChD,eAAe,CAAC,EAAE,OAAO,cAAc,CAAC;QACxC,qBAAqB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACjD;CACF;AAED,UAAU,YAAY;IACpB,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,QAAQ,EAAE,OAAO,cAAc,CAAC;IAChC,UAAU,EAAE,OAAO,gBAAgB,CAAC;IACpC,UAAU,EAAE,OAAO,gBAAgB,CAAC;IACpC,YAAY,EAAE,OAAO,kBAAkB,CAAC;IACxC,QAAQ,EAAE,OAAO,cAAc,CAAC;IAChC;;;;;;;;OAQG;IACH,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,IAAI,EAAE,OAAO,IAAI,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC"}
+{"version":3,"file":"fixture-runtime.d.ts","sourceRoot":"","sources":["../src/fixture-runtime.ts"],"names":[],"mappings":"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"}

package/dist/fixture-runtime.js

@@ -70,27 +70,247 @@ function installRegistry() {
     window.__GGUI_APP_COMPONENTS = registry.appComponents;
     return registry;
 }
-function findActionButton(root, label) {
-    const ariaMatch = root.querySelector(`[aria-label="${CSS.escape(label)}"]`);
-    if (ariaMatch instanceof HTMLElement)
-        return ariaMatch;
-    const lc = label.toLowerCase();
-    const candidates = root.querySelectorAll('button, [role="button"], a, [data-action]');
-    for (const el of Array.from(candidates)) {
-        if (!(el instanceof HTMLElement))
-            continue;
+/**
+ * What a generated component may wire an action to. Kept to real controls
+ * (a `<div onClick>` that names nothing is not a contract affordance).
+ */
+const CLICKABLE_SELECTOR = 'button, [role="button"], input[type="submit"], input[type="button"], ' +
+    'input[type="checkbox"], input[type="radio"], [role="switch"], [role="checkbox"], ' +
+    '[role="menuitem"], [role="tab"], [role="option"], [data-action]';
+// Deliberately NOT candidates: <a href> (a click navigates the fixture page
+// away and aborts every remaining check) and <summary> (its click toggles the
+// parent <details> — a DOM change that says nothing about the action).
+/** Per-control wait in the fallback pass — enough for a synchronous dispatch + a render. */
+const FALLBACK_CLICK_WAIT_MS = 600;
+/**
+ * #1040: how many times ONE control whose click revealed new controls (a wizard's Next, a tab) may be
+ * clicked again while the action's own control is still not visible. Bounds a walk through a
+ * multi-step form; a toggle that keeps revealing and hiding a panel cannot spin the probe.
+ */
+const MAX_NAVIGATOR_RECLICKS = 8;
+/**
+ * ONE deadline covers both passes for an action: max(the caller's wait, this
+ * floor). A few loosely-matching decoys can no longer run an action for
+ * minutes; the floor keeps very short test waits from starving the fallback.
+ */
+const ACTION_BUDGET_FLOOR_MS = 6000;
+function norm(text) {
+    return text.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+/**
+ * The controls to try, the way the harness's render-check finds them (#996):
+ * pass 1 = controls that NAME the action — `data-action` by value (the one
+ * hook that names the action rather than its label), then aria-label / text
+ * carrying the label or the name; pass 2 = every other enabled clickable, in
+ * DOM order. A generated component that wires `useAction('toggleItem')` to an
+ * unnamed checkbox is found by pass 2 and judged by what its click dispatches.
+ */
+/** The one disabled predicate: the collector's and the walk's reveal signal must not drift apart. */
+function isControlDisabled(el) {
+    return el.hasAttribute('disabled') || el.getAttribute('aria-disabled') === 'true';
+}
+function collectActionCandidates(root, name, label) {
+    const every = Array.from(root.querySelectorAll(CLICKABLE_SELECTOR)).filter((el) => el instanceof HTMLElement);
+    const isDisabled = isControlDisabled;
+    const lcName = name.toLowerCase();
+    const lcLabel = label.toLowerCase();
+    const nameKey = norm(name);
+    const labelKey = norm(label);
+    // How the harness names a control: `data-action` by value first (#996), then the aria label or the text.
+    const namesAction = (el) => {
+        const dataAction = (el.getAttribute('data-action') ?? '').toLowerCase();
+        if (dataAction === lcName)
+            return 'value';
+        const aria = (el.getAttribute('aria-label') ?? '').toLowerCase();
         const txt = (el.textContent ?? '').trim().toLowerCase();
-        if (txt.length > 0 && txt.includes(lc))
-            return el;
+        const ariaNames = aria.length > 0 && (aria.includes(lcLabel) || (nameKey.length > 0 && norm(aria).includes(nameKey)));
+        const textNames = txt.length > 0 &&
+            (txt.includes(lcLabel) ||
+                (nameKey.length > 0 && norm(txt).includes(nameKey)) ||
+                (labelKey.length > 0 && norm(txt).includes(labelKey)));
+        return ariaNames || textNames ? 'text' : null;
+    };
+    const disabledEls = every.filter(isDisabled);
+    const disabled = disabledEls.length;
+    const namedDisabled = disabledEls.filter((el) => namesAction(el) !== null).length;
+    const all = every.filter((el) => !isDisabled(el) &&
+        // an already-checked radio fires no change on click — nothing to observe
+        !(el instanceof HTMLInputElement && el.type === 'radio' && el.checked));
+    const byValue = [];
+    const byText = [];
+    const rest = [];
+    for (const el of all) {
+        const how = namesAction(el);
+        if (how === 'value')
+            byValue.push(el);
+        else if (how === 'text')
+            byText.push(el);
+        else
+            rest.push(el);
+    }
+    return { named: [...byValue, ...byText], fallback: rest, disabled, namedDisabled, allClickables: every };
+}
+// #1040: date-like types too — a wizard's first step is routinely gated on one ("preferred follow-up
+// date"), and a Next that never enables hides every step behind it from the probe.
+const TEXT_LIKE_INPUT_TYPES = new Set([
+    'text', 'email', 'search', 'url', 'tel', 'number', 'password', '',
+    'date', 'time', 'month', 'week', 'datetime-local',
+]);
+function sampleValueFor(el) {
+    const type = el instanceof HTMLInputElement ? el.type : 'textarea';
+    switch (type) {
+        case 'number':
+            return '1';
+        case 'email':
+            return 'probe@example.com';
+        case 'url':
+            return 'https://example.com';
+        case 'tel':
+            return '5550100';
+        case 'date':
+            return '2026-01-15';
+        case 'time':
+            return '09:30';
+        case 'month':
+            return '2026-01';
+        case 'week':
+            return '2026-W03';
+        case 'datetime-local':
+            return '2026-01-15T09:30';
+        default:
+            return 'probe';
     }
-    for (const el of Array.from(root.querySelectorAll('*'))) {
-        if (!(el instanceof HTMLElement))
+}
+/** Set a value the way React notices it: through the prototype's native setter, then an input + change event. */
+function setNativeValue(el, value) {
+    const proto = el instanceof HTMLTextAreaElement
+        ? HTMLTextAreaElement.prototype
+        : el instanceof HTMLSelectElement
+            ? HTMLSelectElement.prototype
+            : HTMLInputElement.prototype;
+    const setter = Object.getOwnPropertyDescriptor(proto, 'value')?.set;
+    if (setter)
+        setter.call(el, value);
+    else
+        el.value = value;
+    el.dispatchEvent(new Event('input', { bubbles: true }));
+    el.dispatchEvent(new Event('change', { bubbles: true }));
+}
+/**
+ * The generic minimum a user does before pressing Send / Submit / Complete
+ * (#1021): give every empty text-like input and textarea a value, every
+ * unset select its first real option, every unchecked radio group its first
+ * radio. Checkboxes are never touched — they are often the action itself.
+ * Returns how many controls were primed.
+ */
+function primeInputs(root) {
+    let primed = 0;
+    const editable = (el) => !el.disabled && !(el instanceof HTMLSelectElement) ? !el.readOnly : !el.disabled;
+    for (const el of Array.from(root.querySelectorAll('input, textarea'))) {
+        if (!(el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) || !editable(el))
             continue;
-        const txt = (el.textContent ?? '').trim().toLowerCase();
-        if (txt === lc)
-            return el;
+        if (el instanceof HTMLInputElement && !TEXT_LIKE_INPUT_TYPES.has(el.type))
+            continue;
+        if (el.value.trim().length > 0)
+            continue;
+        setNativeValue(el, sampleValueFor(el));
+        if (el.value.trim().length > 0)
+            primed += 1;
+    }
+    for (const el of Array.from(root.querySelectorAll('select'))) {
+        if (!(el instanceof HTMLSelectElement) || el.disabled)
+            continue;
+        const current = el.options[el.selectedIndex];
+        if (current !== undefined && current.value.trim().length > 0)
+            continue;
+        const first = Array.from(el.options).find((o) => o.value.trim().length > 0 && !o.disabled);
+        if (first === undefined)
+            continue;
+        setNativeValue(el, first.value);
+        primed += 1;
+    }
+    const seenGroups = new Set();
+    for (const el of Array.from(root.querySelectorAll('input[type="radio"]'))) {
+        if (!(el instanceof HTMLInputElement) || el.disabled)
+            continue;
+        const group = el.name || '';
+        if (seenGroups.has(group))
+            continue;
+        seenGroups.add(group);
+        const members = group
+            ? Array.from(root.querySelectorAll(`input[type="radio"][name="${CSS.escape(group)}"]`)).filter((m) => m instanceof HTMLInputElement)
+            : [el];
+        if (members.some((m) => m.checked))
+            continue;
+        const first = members.find((m) => !m.disabled);
+        if (first === undefined)
+            continue;
+        first.click();
+        primed += 1;
+    }
+    return primed;
+}
+function countNamedDispatches(actionName) {
+    return (window.__ggui_test_dispatches__ ?? []).filter((d) => d.actionName === actionName).length;
+}
+function snapshot(container, actionName) {
+    return {
+        text: container.textContent ?? '',
+        html: container.innerHTML,
+        named: countNamedDispatches(actionName),
+        total: (window.__ggui_test_dispatches__ ?? []).length,
+    };
+}
+/** Poll for the required signal after a click. `dispatchFired` counts only dispatches of THIS action. */
+async function observe(container, actionName, before, req, waitMs) {
+    const start = Date.now();
+    let dispatchFired = false;
+    let domChanged = false;
+    while (Date.now() - start < waitMs) {
+        await delay(50);
+        if (!dispatchFired && countNamedDispatches(actionName) > before.named) {
+            dispatchFired = true;
+        }
+        if (!domChanged) {
+            const afterText = container.textContent ?? '';
+            const afterHtml = container.innerHTML;
+            if (afterText !== before.text || afterHtml !== before.html) {
+                domChanged = true;
+            }
+        }
+        if (dispatchFired && domChanged)
+            break;
+        // Early-exit once the REQUIRED signal has fired (don't wait for the other one).
+        if (req.requireDispatch && dispatchFired)
+            break;
+        if (req.requireDom && domChanged)
+            break;
+    }
+    const otherActions = (window.__ggui_test_dispatches__ ?? [])
+        .slice(before.total)
+        .map((d) => d.actionName)
+        .filter((n) => n !== actionName);
+    return { dispatchFired, domChanged, otherActions: [...new Set(otherActions)] };
+}
+function satisfied(req, obs) {
+    return (req.requireDispatch ? obs.dispatchFired : true) && (req.requireDom ? obs.domChanged : true);
+}
+/**
+ * A control's identity across re-renders: its path from the mount root by tag
+ * and sibling index (plus an input's type). A re-rendered equivalent at the
+ * same position counts as already tried; a detached node never gets clicked.
+ */
+function signatureOf(root, el) {
+    const parts = [];
+    let cur = el;
+    while (cur !== null && cur !== root) {
+        const parent = cur.parentElement;
+        const idx = parent === null ? 0 : Array.prototype.indexOf.call(parent.children, cur);
+        const type = cur instanceof HTMLInputElement ? `[${cur.type}]` : '';
+        parts.push(`${cur.tagName.toLowerCase()}${type}:${idx}`);
+        cur = parent;
     }
-    return null;
+    return parts.reverse().join('/');
 }
 async function evaluateComponent(code) {
     const cleaned = stripMarkers(code);
@@ -104,7 +324,12 @@ async function evaluateComponent(code) {
     }
     return Comp;
 }
-function mountTree(Comp) {
+function propsOf(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function mountTree(Comp, props) {
     const container = document.createElement('div');
     container.id = 'ggui-vt-mount';
     document.body.replaceChildren(container);
@@ -127,7 +352,9 @@ function mountTree(Comp) {
         subscribe: () => () => { },
     };
     const root = ReactDomClient.createRoot(container);
-    const componentElement = React.createElement(Comp, {});
+    // The commit's fixture props: a component that draws its controls from
+    // props (a board's tasks, a list's items) mounts EMPTY without them.
+    const componentElement = React.createElement(Comp, props);
     const tree = React.createElement(Wire.GguiWireProvider, {
         config: wireConfig,
         children: componentElement,
@@ -182,7 +409,7 @@ async function run(input) {
     let handles = null;
     try {
         try {
-            handles = mountTree(Comp);
+            handles = mountTree(Comp, propsOf(input.sampleProps));
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -199,55 +426,162 @@ async function run(input) {
                 diagnostic: `actionSpec.${input.actionName} missing`,
             };
         }
-        const button = findActionButton(handles.container, entry.label);
-        if (button === null) {
-            return { status: 'action-not-rendered' };
+        const req = signalRequirement(input.classification);
+        const container = handles.container;
+        // Prime inputs first (#1021): Send/Submit/Complete are commonly disabled
+        // until something is typed or chosen — the minimum a user does before them.
+        const primed = primeInputs(container);
+        if (primed > 0)
+            await delay(150);
+        const first = collectActionCandidates(container, input.actionName, entry.label);
+        if (first.named.length === 0 && first.fallback.length === 0) {
+            if (first.namedDisabled > 0) {
+                // #1040: the action's own control is there, disabled, and nothing else is clickable —
+                // the action is gated on input the probe did not provide. Not missing, not a miss: not measured.
+                return {
+                    status: 'action-unreachable',
+                    reason: 'disabled-after-priming',
+                    diagnostic: `${first.disabled} control(s) rendered, all disabled (${first.namedDisabled} naming the action) — the action is gated on input the probe did not provide ` +
+                        `(primed ${primed} input(s)); actionSpec.${input.actionName} (label "${entry.label}")`,
+                };
+            }
+            return {
+                status: 'action-not-rendered',
+                diagnostic: `no clickable control in the rendered DOM for actionSpec.${input.actionName} (label "${entry.label}")` +
+                    (first.disabled > 0 ? ` — ${first.disabled} control(s) rendered disabled, none naming the action` : '') +
+                    ` (primed ${primed} input(s))`,
+            };
         }
-        const beforeText = handles.container.textContent ?? '';
-        const beforeHtml = handles.container.innerHTML;
-        const dispatchesBefore = (window.__ggui_test_dispatches__ ?? []).length;
-        button.click();
-        const start = Date.now();
-        let dispatchFired = false;
-        let domChanged = false;
-        while (Date.now() - start < input.waitMs) {
-            await delay(50);
-            if (!dispatchFired &&
-                (window.__ggui_test_dispatches__ ?? []).length > dispatchesBefore) {
-                dispatchFired = true;
+        // One deadline for the whole action. Named controls get the caller's wait
+        // (or what is left of the budget); fallback controls get a short slice each.
+        const deadline = Date.now() + Math.max(input.waitMs, ACTION_BUDGET_FLOOR_MS);
+        const remaining = () => Math.max(0, deadline - Date.now());
+        let clicked = 0;
+        let bestDispatch = false;
+        let bestDom = false;
+        const otherActions = new Set();
+        const attempt = async (el, waitMs, via) => {
+            const before = snapshot(container, input.actionName);
+            clicked += 1;
+            el.click();
+            const obs = await observe(container, input.actionName, before, req, waitMs);
+            bestDispatch = bestDispatch || obs.dispatchFired;
+            bestDom = bestDom || obs.domChanged;
+            for (const a of obs.otherActions)
+                otherActions.add(a);
+            return satisfied(req, obs)
+                ? { status: 'ok', dispatchFired: obs.dispatchFired, domChanged: obs.domChanged, via, clicked }
+                : null;
+        };
+        // Re-collect LIVE candidates before EVERY click: an earlier click may have
+        // re-rendered the tree (a filter, a tab, an opened editor), detaching what
+        // was collected and adding what was not there. A control is tried once,
+        // by its DOM path; a detached node is never the one clicked.
+        const tried = new Set();
+        let exhausted = false;
+        // #1040: was the NAMED control ever clicked enabled (a real attempt), was it ever seen disabled (a
+        // gate), and did a click make NEW controls appear (a step, a tab, a revealed section — navigation,
+        // as distinct from a re-render of what was already there)?
+        let namedAttempted = false;
+        let namedDisabledSeen = first.namedDisabled;
+        let navigated = false;
+        let knownSignatures = new Set(first.allClickables.map((el) => signatureOf(container, el)));
+        // #1040: the walk. A wizard's Next is ONE element at ONE DOM path on every step, so "tried once by
+        // path" stopped the probe at step 1 forever, and the terminal control never mounted. A control
+        // whose click revealed controls the probe had not seen is a NAVIGATOR: while the action's own
+        // control is not visible, the probe clicks it again (bounded) before exploring further — the way
+        // a user presses Next until the last step. Inputs a step reveals are primed like the first step's.
+        const navigators = new Map();
+        let lastClickedSignature;
+        // The action's OWN control is keyed by path AND text: a wizard renders Complete at the path Next
+        // occupied on every earlier step, and "tried by path" would read it as the Next already clicked.
+        const namedKey = (el) => `${signatureOf(container, el)}|${(el.textContent ?? '').trim()}`;
+        const triedNamed = new Set();
+        // A step is "revealed" when a control the probe had not seen appears OR a control it had only
+        // seen disabled becomes enabled (a wizard's Back on step 2, a Next a step's own field unlocked).
+        const stateOf = (el) => `${signatureOf(container, el)}|${isControlDisabled(el) ? 'off' : 'on'}`;
+        let knownStates = new Set(first.allClickables.map(stateOf));
+        for (;;) {
+            if (remaining() === 0) {
+                exhausted = true;
+                break;
             }
-            if (!domChanged) {
-                const afterText = handles.container.textContent ?? '';
-                const afterHtml = handles.container.innerHTML;
-                if (afterText !== beforeText || afterHtml !== beforeHtml) {
-                    domChanged = true;
+            let live = collectActionCandidates(container, input.actionName, entry.label);
+            // Disabled controls count: a step that reveals a disabled Complete IS navigation into the gate.
+            const liveSignatures = live.allClickables.map((el) => signatureOf(container, el));
+            const liveStates = live.allClickables.map(stateOf);
+            // `navigated` (the reason on an unreachable exit) keeps its meaning: controls the probe had not
+            // seen appeared. `revealed` (the walk) is wider: that, or a control seen only disabled enabling.
+            if (clicked > 0 && liveSignatures.some((sig) => !knownSignatures.has(sig)))
+                navigated = true;
+            const revealed = clicked > 0 && liveStates.some((state) => !knownStates.has(state));
+            knownSignatures = new Set([...knownSignatures, ...liveSignatures]);
+            knownStates = new Set([...knownStates, ...liveStates]);
+            if (revealed) {
+                if (lastClickedSignature !== undefined && !navigators.has(lastClickedSignature))
+                    navigators.set(lastClickedSignature, 0);
+                // The revealed step may carry its own gate ("name", "date") — give it what the first step got.
+                if (primeInputs(container) > 0) {
+                    await delay(150);
+                    live = collectActionCandidates(container, input.actionName, entry.label);
                 }
             }
-            if (dispatchFired && domChanged)
-                break;
-            // Early-exit if the REQUIRED signal has fired (don't wait for the
-            // other one — speeds up the slow stage when the wiring is correct).
-            const req = signalRequirement(input.classification);
-            if (req.requireDispatch && dispatchFired)
-                break;
-            if (req.requireDom && domChanged)
+            namedDisabledSeen = Math.max(namedDisabledSeen, live.namedDisabled);
+            const untried = (list) => list.find((el) => el.isConnected && !tried.has(signatureOf(container, el)));
+            const nextNamed = live.named.find((el) => el.isConnected && !triedNamed.has(namedKey(el)));
+            const navigator = nextNamed === undefined
+                ? live.fallback.find((el) => {
+                    const sig = signatureOf(container, el);
+                    return el.isConnected && (navigators.get(sig) ?? MAX_NAVIGATOR_RECLICKS) < MAX_NAVIGATOR_RECLICKS;
+                })
+                : undefined;
+            // Untried controls first — including the ones the last click revealed — and only when nothing
+            // untried remains, the navigator again: a wizard walks (one extra Back click); an "Add item"
+            // or a tab is not clicked eight more times before what it revealed gets its turn.
+            const next = nextNamed ?? untried(live.fallback) ?? navigator;
+            if (next === undefined)
                 break;
+            const via = nextNamed !== undefined ? 'named' : 'fallback';
+            if (via === 'named')
+                namedAttempted = true;
+            const nextSignature = signatureOf(container, next);
+            if (navigator !== undefined && next === navigator)
+                navigators.set(nextSignature, (navigators.get(nextSignature) ?? 0) + 1);
+            if (via === 'named')
+                triedNamed.add(namedKey(next));
+            tried.add(nextSignature);
+            lastClickedSignature = nextSignature;
+            const hit = await attempt(next, via === 'named' ? Math.min(input.waitMs, remaining()) : Math.min(FALLBACK_CLICK_WAIT_MS, remaining()), via);
+            if (hit !== null)
+                return hit;
         }
-        const req = signalRequirement(input.classification);
-        const required = (req.requireDispatch ? dispatchFired : true) &&
-            (req.requireDom ? domChanged : true);
-        if (!required) {
-            const missing = [];
-            if (req.requireDispatch && !dispatchFired)
-                missing.push('dispatch');
-            if (req.requireDom && !domChanged)
-                missing.push('DOM change');
+        const missing = [];
+        if (req.requireDispatch && !bestDispatch)
+            missing.push('dispatch');
+        if (req.requireDom && !bestDom)
+            missing.push('DOM change');
+        const others = otherActions.size > 0 ? `; other actions dispatched: ${[...otherActions].join(', ')}` : '';
+        const navigatorReclicks = [...navigators.values()].reduce((sum, n) => sum + n, 0);
+        // #1040: the named control was seen only disabled and never clicked enabled — the probe could not
+        // reach the action. Not measured, with the reason: a click made new controls appear (the gate sits
+        // behind navigation the probe walked into but could not finish) or none did (the gate is input the
+        // probe did not provide). An enabled named control that was clicked and did nothing stays the miss.
+        if (!namedAttempted && namedDisabledSeen > 0) {
+            const reason = navigated ? 'behind-navigation' : 'disabled-after-priming';
             return {
-                status: 'action-no-effect',
-                diagnostic: `${req.description}; observed dispatch=${dispatchFired}, domChanged=${domChanged}; missing=${missing.join('+')}`,
+                status: 'action-unreachable',
+                reason,
+                diagnostic: `actionSpec.${input.actionName} (label "${entry.label}") rendered disabled on every observation (${namedDisabledSeen} matching control(s)) and was never clicked enabled; ` +
+                    `clicked ${clicked} other control(s) (${tried.size} distinct; primed ${primed} input(s); navigator re-clicks=${navigatorReclicks}); new controls appeared after a click=${navigated}; DOM changed=${bestDom}` +
+                    `${exhausted ? '; budget exhausted' : ''}${others}`,
             };
         }
-        return { status: 'ok', dispatchFired, domChanged };
+        return {
+            status: 'action-no-effect',
+            diagnostic: `${req.description}; clicked ${clicked} control(s) (${tried.size} distinct; first collection ${first.named.length} named, ${first.fallback.length} fallback, ${first.disabled} disabled; primed ${primed} input(s)` +
+                `; navigator re-clicks=${navigatorReclicks}${exhausted ? '; budget exhausted' : ''}); best observed dispatch=${bestDispatch}, domChanged=${bestDom}; ` +
+                `missing=${missing.join('+')}${others}`,
+        };
     }
     finally {
         window.removeEventListener('error', onWindowError);

package/dist/index.d.ts

@@ -52,20 +52,27 @@
  *
  * For each entry in `contract.actionSpec`:
  *
- *   1. Render the component in a real Chromium tab via Playwright.
- *   2. Find a button matching the action's `label` (aria-label first,
- *      then visible-text contains, case-insensitive).
- *   3. Snapshot the current DOM state.
- *   4. Click the button.
- *   5. Wait up to `timeoutMs` for the required signal (per the gate
- *      above) to fire.
+ *   1. Render the component in a real Chromium tab via Playwright, with
+ *      `sampleProps` (the commit's fixture props) — a component that draws its
+ *      controls from props has nothing to click without them.
+ *   2. Collect the controls to try, the way the harness's render-check
+ *      does (#996): first those that NAME the action (`data-action` by
+ *      value, then aria-label / text carrying the label or the name), then
+ *      every other enabled clickable in DOM order.
+ *   3. For each candidate: snapshot the DOM, click, wait up to `timeoutMs`
+ *      (named) or a bounded slice of it (fallback) for the required signal
+ *      (per the gate above); stop at the first control that produces it.
+ *      Only dispatches of THIS action count; others are reported.
+ *   4. `action-not-rendered` means no clickable control exists at all.
+ *   5. `action-no-effect` means controls were clicked and none produced
+ *      the required signal — the diagnostic says how many, and what was seen.
  *   6. Classify: ok / action-no-effect / action-not-rendered /
  *      render-failed.
  *
  * Empty `actionSpec` returns `{ ok: true, failures: [] }` (not
  * applicable — nothing to test).
  */
-import type { DataContract } from '@ggui-ai/protocol';
+import type { DataContract, JsonObject } from '@ggui-ai/protocol';
 import type { Browser as PlaywrightBrowser, BrowserContext as PlaywrightBrowserContext, Page as PlaywrightPage, LaunchOptions as PlaywrightLaunchOptions } from 'playwright-core';
 /**
  * Minimal Playwright `chromium` surface the validator depends on.
@@ -85,6 +92,13 @@ export type { PlaywrightBrowser, PlaywrightBrowserContext, PlaywrightPage, };
 export interface ValidateContractBehaviorInput {
     readonly componentCode: string;
     readonly contract: DataContract;
+    /**
+     * The props the component was generated for (the commit's fixture props —
+     * the same object the visual judge receives). Without them a component that
+     * renders its controls from props (a board's tasks, a list's items) mounts
+     * EMPTY and has nothing to click, which reads as action-not-rendered.
+     */
+    readonly sampleProps?: JsonObject;
     readonly timeoutMs?: number;
     /**
      * Playwright module. Pass `{ chromium }` from `playwright-core` or
@@ -93,11 +107,37 @@ export interface ValidateContractBehaviorInput {
      */
     readonly playwright: PlaywrightModule;
 }
-export type BehaviorFailureKind = 'action-no-effect' | 'action-not-rendered' | 'render-failed' | 'timeout';
+/**
+ * Extensibly-closed (docs/protocol/VERSION-POLICY.md §1.2): members are added
+ * in MINOR releases of this package. A reader that meets a kind it does not
+ * name MUST treat it as a failure of unknown kind — never as success, never
+ * as "not rendered". An exhaustive `switch` over this union stops compiling
+ * at the next member; that is the intended nudge at upgrade, not a wire
+ * break. The report wire (`benchmark-report.v2`) carries the kind as a
+ * string and its readers copy it verbatim (ggui#1014, ggui#1040).
+ */
+export type BehaviorFailureKind = 'action-no-effect' | 'action-not-rendered'
+/**
+ * The named action's control was present but the static probe could not reach it enabled
+ * (ggui#1040). NOT MEASURED — never a miss, never "not rendered"; symmetric across arms by
+ * construction. `BehaviorFailure.reason` says why.
+ */
+ | 'action-unreachable' | 'render-failed' | 'timeout';
+/**
+ * Why an action was unreachable (ggui#1040). `disabled-after-priming`: the action's control rendered
+ * disabled and no click of the probe's made new controls appear — the gate is input the probe did not
+ * provide. `behind-navigation`: a click made new controls appear (a step, a tab, a revealed section)
+ * and the action's control was still never observed enabled — the gate sits behind navigation the
+ * probe walked into but could not finish. Measured by the clickable-candidate set changing, not by a
+ * DOM diff.
+ */
+export type BehaviorUnreachableReason = 'disabled-after-priming' | 'behind-navigation';
 export interface BehaviorFailure {
     readonly kind: BehaviorFailureKind;
     readonly actionName?: string;
     readonly diagnostic: string;
+    /** Present when `kind` is `action-unreachable` (ggui#1040). */
+    readonly reason?: BehaviorUnreachableReason;
 }
 export interface ValidateContractBehaviorResult {
     readonly ok: boolean;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EACV,OAAO,IAAI,iBAAiB,EAC5B,cAAc,IAAI,wBAAwB,EAC1C,IAAI,IAAI,cAAc,EACtB,aAAa,IAAI,uBAAuB,EACzC,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE;QACjB,MAAM,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;KACvE,CAAC;CACH;AAED,yDAAyD;AACzD,YAAY,EACV,iBAAiB,EACjB,wBAAwB,EACxB,cAAc,GACf,CAAC;AAEF,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;CACvC;AAED,MAAM,MAAM,mBAAmB,GAC3B,kBAAkB,GAClB,qBAAqB,GACrB,eAAe,GACf,SAAS,CAAC;AAEd,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;CAC/C;AAED,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAEzD;;;;GAIG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,SAAkB,IAAI,iCAAiC;;CASxD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,KAAK,EACV,OAAO,IAAI,iBAAiB,EAC5B,cAAc,IAAI,wBAAwB,EAC1C,IAAI,IAAI,cAAc,EACtB,aAAa,IAAI,uBAAuB,EACzC,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE;QACjB,MAAM,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;KACvE,CAAC;CACH;AAED,yDAAyD;AACzD,YAAY,EACV,iBAAiB,EACjB,wBAAwB,EACxB,cAAc,GACf,CAAC;AAEF,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,UAAU,CAAC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;CACvC;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,GAC3B,kBAAkB,GAClB,qBAAqB;AACvB;;;;GAIG;GACD,oBAAoB,GACpB,eAAe,GACf,SAAS,CAAC;AAEd;;;;;;;GAOG;AACH,MAAM,MAAM,yBAAyB,GAAG,wBAAwB,GAAG,mBAAmB,CAAC;AAEvF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,CAAC,EAAE,yBAAyB,CAAC;CAC7C;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;CAC/C;AAED,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAEzD;;;;GAIG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,SAAkB,IAAI,iCAAiC;;CASxD"}