@sun-asterisk/sungen 3.2.29 → 3.2.31

package/dist/orchestrator/templates/specs-checked-state.js

@@ -0,0 +1,261 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.probeControl = probeControl;
+exports.setCheckedState = setCheckedState;
+exports.expectCheckedState = expectCheckedState;
+/**
+ * Budget for EACH PHASE of a check/uncheck step — classification, the action, and the post-click
+ * verification each get their own (deliberately: see setCheckedState). So the worst case is a small
+ * multiple of this, not this. Raise it for a slow CI box with `SUNGEN_TOGGLE_TIMEOUT_MS`; without an
+ * escape hatch this would silently override a project that raised Playwright's own `actionTimeout`.
+ */
+const ENV_TIMEOUT = Number(process.env.SUNGEN_TOGGLE_TIMEOUT_MS);
+// Guard the parse: `=0` means "no timeout" to Playwright (hang forever) and a negative is nonsense —
+// neither should be inherited from a typo'd env var.
+const TOGGLE_TIMEOUT_MS = Number.isFinite(ENV_TIMEOUT) && ENV_TIMEOUT > 0 ? ENV_TIMEOUT : 8000;
+const POLL_INTERVAL_MS = 100;
+/**
+ * Runs IN THE PAGE, so it must stay self-contained: Playwright serialises it and the browser has
+ * none of this module's scope.
+ *
+ * It also must contain NO inner function of its own — not even an arrow helper. A bundler with
+ * keepNames (esbuild, which is what Playwright itself transpiles specs with) rewrites every named
+ * inner function to `__name(fn, "…")`, that wrapper travels inside the serialised source, and the
+ * page throws `ReferenceError: __name is not defined` on EVERY check step. Straight-line code with
+ * the normalise repeated inline is the price of being serialisable; `tests/runtime/
+ * checked-state.run.ts` pins it so the next edit cannot quietly reintroduce a helper.
+ *
+ * Structurally typed rather than via the DOM lib names because this file is also typechecked
+ * inside the compiler build, whose tsconfig carries no DOM lib.
+ */
+function probeControl(node, declared) {
+    const el = node;
+    const tag = String(el.tagName ?? '').trim().toLowerCase(); // lowercase: XHTML serves it so
+    const type = String(el.type ?? '').trim().toLowerCase();
+    const role = String(el.getAttribute('role') ?? '').trim().toLowerCase();
+    const ariaCheckableRole = role === 'checkbox' || role === 'radio' || role === 'switch';
+    const buttonLike = tag === 'button' || role === 'button'
+        || (tag === 'input' && (type === 'button' || type === 'submit' || type === 'reset'));
+    // A DECLARED signal wins over every ARIA reading below (issue #730). The author reached for this
+    // escape hatch precisely because the component publishes no usable ARIA, so second-guessing them
+    // from a stray role would put the step back on the path that could not work. Self OR descendant:
+    // a card picker swaps the class on the control itself, while a custom checkbox often mounts a
+    // checkmark <svg class="is-checked"> inside instead — both are the same declaration to the author.
+    // `classList.contains` is exact-token by definition; `[class~="…"]` is its selector equivalent,
+    // so neither needs the class escaped and neither can half-match ("is-checked-disabled").
+    if (declared && declared.class) {
+        const onSelf = el.classList != null && el.classList.contains(declared.class);
+        const onChild = !onSelf && el.querySelector('[class~="' + declared.class + '"]') != null;
+        return { source: 'class', on: onSelf || onChild, buttonLike };
+    }
+    // The same declaration published as a boolean attribute instead of a class. Self ONLY, unlike the
+    // class above: a class swap can legitimately live on a checkmark child, but `data-checked` on a
+    // descendant is a different control's state, and reading it would assert the wrong element.
+    if (declared && declared.attribute) {
+        const raw = el.getAttribute(declared.attribute);
+        return { source: 'attribute', on: String(raw ?? '').trim().toLowerCase() === 'true', buttonLike };
+    }
+    // A native input needs no ARIA attribute — Playwright reads `.checked` directly.
+    if (tag === 'input' && (type === 'checkbox' || type === 'radio'))
+        return { source: 'native', on: false, buttonLike };
+    // An ARIA checkable publishes state through `aria-checked`, which is what Playwright reads. Only
+    // hand it over when that attribute is actually there: `<button role="switch" aria-pressed="…">`
+    // is a common authoring slip, and routing it to .check() makes Playwright click, re-read the
+    // aria-checked that does not exist, and die on "did not change its state".
+    if (ariaCheckableRole && el.hasAttribute('aria-checked'))
+        return { source: 'native', on: false, buttonLike };
+    if (el.hasAttribute('aria-pressed')) {
+        return { source: 'aria-pressed', on: String(el.getAttribute('aria-pressed') ?? '').trim().toLowerCase() === 'true', buttonLike };
+    }
+    if (el.hasAttribute('aria-checked')) {
+        return { source: 'aria-checked', on: String(el.getAttribute('aria-checked') ?? '').trim().toLowerCase() === 'true', buttonLike };
+    }
+    // Role claims checkable but nothing is published — let Playwright raise its own, precise error.
+    if (ariaCheckableRole)
+        return { source: 'native', on: false, buttonLike };
+    return { source: 'none', on: false, buttonLike };
+}
+/** The declaration both helpers forward into the page. Undefined when nothing was declared, so a
+ *  control with real ARIA keeps being read exactly as it was before any of this existed. */
+const declaredSignal = (options) => (options?.checkedClass ? { class: options.checkedClass }
+    : options?.checkedAttribute ? { attribute: options.checkedAttribute }
+        : undefined);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Time left on a budget, floored at 250ms. Never 0 — to Playwright that means "no timeout", i.e.
+ * hang forever. And never a sliver either: a 1ms floor makes the last poll fail with
+ * `Timeout 1ms exceeded`, which masks the real, explanatory error this helper is about to throw.
+ * The floor lets a budget overrun by at most 250ms; the loops below terminate on the deadline.
+ */
+const left = (deadline) => Math.max(250, deadline - Date.now());
+/** Read the live state. A REMOVED attribute means off: `aria-pressed={on || undefined}` is a common
+ *  React/Vue idiom, so requiring a literal "false" would fail a control that is correctly off. */
+async function readOn(target, attr, deadline) {
+    const raw = await target.getAttribute(attr, { timeout: left(deadline) });
+    return String(raw ?? '').trim().toLowerCase() === 'true';
+}
+/**
+ * Drive `target` to the requested on/off state, idempotently.
+ *
+ * @param target the control
+ * @param want   `true` = checked/pressed, `false` = unchecked/unpressed
+ * @param label  the `[Selector Ref]` from the feature file, used only in error messages
+ * @param options.checkedClass `checked:`/`selected:` from selectors.yaml — the class marking ON,
+ *        for a control that publishes no ARIA at all (issue #730). Overrides every ARIA reading.
+ * @param options.checkedAttribute the same declaration published as a boolean attribute
+ *        ('true'/'false') instead of a class. A selector declares one or the other, never both.
+ */
+async function setCheckedState(target, want, label, options) {
+    const timeout = options?.timeout ?? TOGGLE_TIMEOUT_MS;
+    const declared = declaredSignal(options);
+    // TWO budgets, not one shared deadline: a control that hydrates late would otherwise spend the
+    // whole budget being classified and leave the post-click check a single sample — which then
+    // reports "the click landed on the label" when the real problem was the clock.
+    const classifyDeadline = Date.now() + timeout;
+    // `locator.evaluate` waits only for ATTACHED. Playwright's own .check() re-resolved the locator on
+    // every actionability retry, so a control that gains its role/aria-* on hydration still worked —
+    // classifying once at first attach would turn a slow mount into a hard failure.
+    let probe = await target.evaluate(probeControl, declared, { timeout: left(classifyDeadline) });
+    while (probe.source === 'none' && classifyDeadline - Date.now() > POLL_INTERVAL_MS) {
+        await sleep(POLL_INTERVAL_MS);
+        probe = await target.evaluate(probeControl, declared, { timeout: left(classifyDeadline) });
+    }
+    if (probe.source === 'native') {
+        if (want)
+            await target.check({ timeout });
+        else
+            await target.uncheck({ timeout });
+        return;
+    }
+    // A declared class: drive it the way the ARIA path below drives a toggle — click ONLY when the
+    // current state differs, then require the class to reach the requested state. Same idempotence,
+    // and the same refusal to report success on a blind click.
+    if (probe.source === 'class' || probe.source === 'attribute') {
+        if (probe.on === want)
+            return;
+        await target.click({ timeout });
+        const classStart = Date.now();
+        const classDeadline = classStart + timeout;
+        for (;;) {
+            const after = await target.evaluate(probeControl, declared, { timeout: left(classDeadline) });
+            if (after.on === want)
+                return;
+            if (classDeadline - Date.now() <= POLL_INTERVAL_MS) {
+                throw new Error(`[${label}] did not become ${want ? 'checked' : 'unchecked'} within ${Date.now() - classStart}ms of `
+                    + `being clicked — the declared ${probe.source} "${declared?.class ?? declared?.attribute}" still reads `
+                    + `${want ? 'off' : 'on'}${probe.source === 'class' ? ' on the element and on its descendants' : ''}. `
+                    + `Either the click landed on the label rather than the control, or that is not the `
+                    + `${probe.source} this component swaps for its on/off state.`);
+            }
+            await sleep(POLL_INTERVAL_MS);
+        }
+    }
+    if (probe.source === 'none') {
+        // Absence on a PRESSABLE control means off — a toggle written as `aria-pressed={on || undefined}`
+        // (React/Vue, and several component libraries a QA team does not own) drops the attribute
+        // entirely when unpressed. Treating that as an error made `uncheck` pass on the first run and
+        // fail on the second, which is precisely the rerun-dependent flake this helper exists to stop.
+        if (probe.buttonLike) {
+            if (!want) {
+                // Nothing to do — but say so, because the alternative is a green step that did nothing at
+                // all (a mis-resolved selector pointing at a plain button looks exactly like this).
+                console.warn(`[sungen] uncheck [${label}]: the control publishes no aria-pressed/aria-checked, so it was `
+                    + `read as already unpressed and NOT clicked. If it should have been a toggle, expose `
+                    + `aria-pressed in both states; if this is not a toggle at all, the step is a no-op.`);
+                return;
+            }
+            // Not a blind click: press once, then REQUIRE the control to publish the requested state.
+            // A plain button publishes nothing afterwards either, so it still fails — just one click later.
+            await target.click({ timeout });
+            const pressedStart = Date.now();
+            const pressedDeadline = pressedStart + timeout;
+            for (;;) {
+                const after = await target.evaluate(probeControl, undefined, { timeout: left(pressedDeadline) });
+                if (after.source !== 'none' && after.on === want)
+                    return;
+                if (pressedDeadline - Date.now() <= POLL_INTERVAL_MS) {
+                    throw new Error(`Cannot check [${label}] — it published no aria-pressed/aria-checked before the click and `
+                        + `still none ${Date.now() - pressedStart}ms after it, so it is a plain button rather than a `
+                        + `toggle. Give the control a real ARIA toggle state, or use "toggles [${label}]" if an `
+                        + `unconditional flip is what you meant.`);
+                }
+                await sleep(POLL_INTERVAL_MS);
+            }
+        }
+        // Not pressable and publishes nothing — there is no reading of this that makes the step meaningful.
+        throw new Error(`Cannot ${want ? 'check' : 'uncheck'} [${label}] — it is not a checkbox/radio/switch, is not a `
+            + `button, and publishes no aria-pressed/aria-checked, so it has no on/off state to set. Point the `
+            + `selector at the control itself, or give it a real ARIA toggle role.`);
+    }
+    const attr = probe.source;
+    // Already in the requested state → nothing to do. This is the idempotence `check` promises.
+    if (probe.on === want)
+        return;
+    await target.click({ timeout });
+    // Fresh budget: this measures the CONTROL's reaction, not time already spent finding it.
+    const verifyStart = Date.now();
+    const verifyDeadline = verifyStart + timeout;
+    for (;;) {
+        if (await readOn(target, attr, verifyDeadline) === want)
+            return;
+        if (verifyDeadline - Date.now() <= POLL_INTERVAL_MS) {
+            throw new Error(`[${label}] did not become ${want ? 'pressed' : 'unpressed'} within ${Date.now() - verifyStart}ms of being `
+                + `clicked — ${attr} still reads ${want ? 'off' : 'on'}. Either the click landed on the label rather than `
+                + `the control, or the handler did not change the state.`);
+        }
+        await sleep(POLL_INTERVAL_MS);
+    }
+}
+/**
+ * Assert the on/off state of the same control family — the read side of #675.
+ *
+ * `expect(locator).toBeChecked()` throws the identical "Not a checkbox or radio button" on a
+ * `<button aria-pressed>`, so driving a toggle worked while asserting it did not. Polls like
+ * Playwright's own web-first assertions rather than sampling once, and reads state exactly the way
+ * setCheckedState does, so an action and the assertion after it can never disagree about what the
+ * control says. Uses `locator.isChecked()` (not `expect`) for the native family, which keeps this
+ * file free of any test-runner dependency.
+ */
+async function expectCheckedState(target, expected, label, options) {
+    const timeout = options?.timeout ?? TOGGLE_TIMEOUT_MS;
+    // Same signal the action side drives (issue #730) — passing it here is what keeps the invariant
+    // above true for a class-only control too: `source: 'class'` falls into the generic `probe.on`
+    // branch below, so check-then-assert cannot disagree.
+    const declared = declaredSignal(options);
+    const start = Date.now();
+    const deadline = start + timeout;
+    for (;;) {
+        const probe = await target.evaluate(probeControl, declared, { timeout: left(deadline) });
+        let actual = null;
+        if (probe.source === 'native')
+            actual = await target.isChecked({ timeout: left(deadline) });
+        else if (probe.source !== 'none')
+            actual = probe.on;
+        else if (probe.buttonLike) {
+            // Absence on a pressable control reads as off, mirroring setCheckedState. But a plain button
+            // and a correctly-off toggle are indistinguishable HERE, and this is an ASSERTION: returning
+            // green having verified nothing is worse than the loud "Not a checkbox or radio button" it
+            // replaced. So say so, exactly as the action side does for the same reading.
+            if (!expected) {
+                console.warn(`[sungen] see [${label}] is unchecked: the control publishes no aria-pressed/aria-checked, `
+                    + `so it was read as unpressed WITHOUT verifying anything. If it should be a toggle, expose `
+                    + `aria-pressed in both states; if it is not a toggle, this assertion proves nothing.`);
+            }
+            actual = false;
+        }
+        if (actual === expected)
+            return;
+        if (deadline - Date.now() <= POLL_INTERVAL_MS) {
+            if (actual === null) {
+                throw new Error(`Cannot assert [${label}] is ${expected ? 'checked' : 'unchecked'} — it is not a `
+                    + `checkbox/radio/switch, is not a button, and publishes no aria-pressed/aria-checked, so it `
+                    + `reports no state to assert. Point the selector at the control itself, or give it a real `
+                    + `ARIA toggle role.`);
+            }
+            throw new Error(`Expected [${label}] to be ${expected ? 'checked' : 'unchecked'}, but it is `
+                + `${actual ? 'checked' : 'unchecked'} after ${Date.now() - start}ms.`);
+        }
+        await sleep(POLL_INTERVAL_MS);
+    }
+}
+//# sourceMappingURL=specs-checked-state.js.map

package/dist/orchestrator/templates/specs-checked-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"specs-checked-state.js","sourceRoot":"","sources":["../../../src/orchestrator/templates/specs-checked-state.ts"],"names":[],"mappings":";;AA+DA,oCAkDC;AAuCD,0CAgHC;AAYD,gDA+CC;AA3SD;;;;;GAKG;AACH,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC;AACjE,qGAAqG;AACrG,qDAAqD;AACrD,MAAM,iBAAiB,GAAG,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAK,CAAC;AAChG,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAe7B;;;;;;;;;;;;;GAaG;AACH,SAAgB,YAAY,CAAC,IAAa,EAAE,QAAyB;IACnE,MAAM,EAAE,GAAG,IAKV,CAAC;IACF,MAAM,GAAG,GAAG,MAAM,CAAC,EAAE,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAG,gCAAgC;IAC7F,MAAM,IAAI,GAAG,MAAM,CAAC,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACxD,MAAM,IAAI,GAAG,MAAM,CAAC,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACxE,MAAM,iBAAiB,GAAG,IAAI,KAAK,UAAU,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,QAAQ,CAAC;IACvF,MAAM,UAAU,GAAG,GAAG,KAAK,QAAQ,IAAI,IAAI,KAAK,QAAQ;WACnD,CAAC,GAAG,KAAK,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC;IAEvF,iGAAiG;IACjG,iGAAiG;IACjG,iGAAiG;IACjG,8FAA8F;IAC9F,mGAAmG;IACnG,gGAAgG;IAChG,yFAAyF;IACzF,IAAI,QAAQ,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,EAAE,CAAC,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC7E,MAAM,OAAO,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,aAAa,CAAC,WAAW,GAAG,QAAQ,CAAC,KAAK,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC;QACzF,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,IAAI,OAAO,EAAE,UAAU,EAAE,CAAC;IAChE,CAAC;IACD,kGAAkG;IAClG,gGAAgG;IAChG,4FAA4F;IAC5F,IAAI,QAAQ,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC;QACnC,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QAChD,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,MAAM,EAAE,UAAU,EAAE,CAAC;IACpG,CAAC;IAED,iFAAiF;IACjF,IAAI,GAAG,KAAK,OAAO,IAAI,CAAC,IAAI,KAAK,UAAU,IAAI,IAAI,KAAK,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IACrH,iGAAiG;IACjG,gGAAgG;IAChG,6FAA6F;IAC7F,2EAA2E;IAC3E,IAAI,iBAAiB,IAAI,EAAE,CAAC,YAAY,CAAC,cAAc,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IAC7G,IAAI,EAAE,CAAC,YAAY,CAAC,cAAc,CAAC,EAAE,CAAC;QACpC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,YAAY,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,MAAM,EAAE,UAAU,EAAE,CAAC;IACnI,CAAC;IACD,IAAI,EAAE,CAAC,YAAY,CAAC,cAAc,CAAC,EAAE,CAAC;QACpC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,YAAY,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,MAAM,EAAE,UAAU,EAAE,CAAC;IACnI,CAAC;IACD,gGAAgG;IAChG,IAAI,iBAAiB;QAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IAC1E,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;AACnD,CAAC;AAED;4FAC4F;AAC5F,MAAM,cAAc,GAAG,CACrB,OAA8D,EAClC,EAAE,CAAC,CAC/B,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,YAAY,EAAE;IACrD,CAAC,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,gBAAgB,EAAE;QACnE,CAAC,CAAC,SAAS,CAChB,CAAC;AAEF,MAAM,KAAK,GAAG,CAAC,EAAU,EAAiB,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AACnF;;;;;GAKG;AACH,MAAM,IAAI,GAAG,CAAC,QAAgB,EAAU,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;AAEhF;kGACkG;AAClG,KAAK,UAAU,MAAM,CAAC,MAAe,EAAE,IAAqC,EAAE,QAAgB;IAC5F,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACzE,OAAO,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;GAUG;AACI,KAAK,UAAU,eAAe,CACnC,MAAe,EAAE,IAAa,EAAE,KAAa,EAC7C,OAAgF;IAEhF,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,iBAAiB,CAAC;IACtD,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACzC,+FAA+F;IAC/F,4FAA4F;IAC5F,+EAA+E;IAC/E,MAAM,gBAAgB,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC;IAE9C,mGAAmG;IACnG,iGAAiG;IACjG,gFAAgF;IAChF,IAAI,KAAK,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,YAAY,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC;IAC/F,OAAO,KAAK,CAAC,MAAM,KAAK,MAAM,IAAI,gBAAgB,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,gBAAgB,EAAE,CAAC;QACnF,MAAM,KAAK,CAAC,gBAAgB,CAAC,CAAC;QAC9B,KAAK,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,YAAY,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC;IAC7F,CAAC;IAED,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,IAAI;YAAE,MAAM,MAAM,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;;YACrC,MAAM,MAAM,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;QACvC,OAAO;IACT,CAAC;IAED,+FAA+F;IAC/F,gGAAgG;IAChG,2DAA2D;IAC3D,IAAI,KAAK,CAAC,MAAM,KAAK,OAAO,IAAI,KAAK,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;QAC7D,IAAI,KAAK,CAAC,EAAE,KAAK,IAAI;YAAE,OAAO;QAC9B,MAAM,MAAM,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;QAChC,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC9B,MAAM,aAAa,GAAG,UAAU,GAAG,OAAO,CAAC;QAC3C,SAAS,CAAC;YACR,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,YAAY,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;YAC9F,IAAI,KAAK,CAAC,EAAE,KAAK,IAAI;gBAAE,OAAO;YAC9B,IAAI,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,gBAAgB,EAAE,CAAC;gBACnD,MAAM,IAAI,KAAK,CACb,IAAI,KAAK,oBAAoB,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,WAAW,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU,QAAQ;sBACnG,gCAAgC,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,KAAK,IAAI,QAAQ,EAAE,SAAS,gBAAgB;sBACvG,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,wCAAwC,CAAC,CAAC,CAAC,EAAE,IAAI;sBACrG,mFAAmF;sBACnF,GAAG,KAAK,CAAC,MAAM,6CAA6C,CAC/D,CAAC;YACJ,CAAC;YACD,MAAM,KAAK,CAAC,gBAAgB,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAED,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAC5B,kGAAkG;QAClG,0FAA0F;QAC1F,8FAA8F;QAC9F,+FAA+F;QAC/F,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;YACrB,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,0FAA0F;gBAC1F,oFAAoF;gBACpF,OAAO,CAAC,IAAI,CACV,qBAAqB,KAAK,mEAAmE;sBAC3F,qFAAqF;sBACrF,mFAAmF,CACtF,CAAC;gBACF,OAAO;YACT,CAAC;YACD,0FAA0F;YAC1F,gGAAgG;YAChG,MAAM,MAAM,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;YAChC,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAChC,MAAM,eAAe,GAAG,YAAY,GAAG,OAAO,CAAC;YAC/C,SAAS,CAAC;gBACR,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,YAAY,EAAE,SAAS,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC;gBACjG,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM,IAAI,KAAK,CAAC,EAAE,KAAK,IAAI;oBAAE,OAAO;gBACzD,IAAI,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,gBAAgB,EAAE,CAAC;oBACrD,MAAM,IAAI,KAAK,CACb,iBAAiB,KAAK,qEAAqE;0BACzF,cAAc,IAAI,CAAC,GAAG,EAAE,GAAG,YAAY,qDAAqD;0BAC5F,uEAAuE,KAAK,WAAW;0BACvF,uCAAuC,CAC1C,CAAC;gBACJ,CAAC;gBACD,MAAM,KAAK,CAAC,gBAAgB,CAAC,CAAC;YAChC,CAAC;QACH,CAAC;QACD,oGAAoG;QACpG,MAAM,IAAI,KAAK,CACb,UAAU,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,KAAK,KAAK,kDAAkD;cAC9F,kGAAkG;cAClG,qEAAqE,CACxE,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC;IAC1B,4FAA4F;IAC5F,IAAI,KAAK,CAAC,EAAE,KAAK,IAAI;QAAE,OAAO;IAC9B,MAAM,MAAM,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;IAEhC,yFAAyF;IACzF,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC/B,MAAM,cAAc,GAAG,WAAW,GAAG,OAAO,CAAC;IAC7C,SAAS,CAAC;QACR,IAAI,MAAM,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,cAAc,CAAC,KAAK,IAAI;YAAE,OAAO;QAChE,IAAI,cAAc,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,gBAAgB,EAAE,CAAC;YACpD,MAAM,IAAI,KAAK,CACb,IAAI,KAAK,oBAAoB,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,WAAW,IAAI,CAAC,GAAG,EAAE,GAAG,WAAW,cAAc;kBAC1G,aAAa,IAAI,gBAAgB,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,qDAAqD;kBACzG,uDAAuD,CAC1D,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,CAAC,gBAAgB,CAAC,CAAC;IAChC,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACI,KAAK,UAAU,kBAAkB,CACtC,MAAe,EAAE,QAAiB,EAAE,KAAa,EACjD,OAAgF;IAEhF,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,iBAAiB,CAAC;IACtD,gGAAgG;IAChG,+FAA+F;IAC/F,sDAAsD;IACtD,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACzC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,MAAM,QAAQ,GAAG,KAAK,GAAG,OAAO,CAAC;IACjC,SAAS,CAAC;QACR,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,YAAY,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QACzF,IAAI,MAAM,GAAmB,IAAI,CAAC;QAClC,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ;YAAE,MAAM,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;aACvF,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM;YAAE,MAAM,GAAG,KAAK,CAAC,EAAE,CAAC;aAC/C,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;YAC1B,6FAA6F;YAC7F,6FAA6F;YAC7F,2FAA2F;YAC3F,6EAA6E;YAC7E,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,OAAO,CAAC,IAAI,CACV,iBAAiB,KAAK,sEAAsE;sBAC1F,2FAA2F;sBAC3F,oFAAoF,CACvF,CAAC;YACJ,CAAC;YACD,MAAM,GAAG,KAAK,CAAC;QACjB,CAAC;QACD,IAAI,MAAM,KAAK,QAAQ;YAAE,OAAO;QAChC,IAAI,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,gBAAgB,EAAE,CAAC;YAC9C,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;gBACpB,MAAM,IAAI,KAAK,CACb,kBAAkB,KAAK,QAAQ,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,iBAAiB;sBAChF,4FAA4F;sBAC5F,0FAA0F;sBAC1F,mBAAmB,CACtB,CAAC;YACJ,CAAC;YACD,MAAM,IAAI,KAAK,CACb,aAAa,KAAK,WAAW,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,cAAc;kBAC3E,GAAG,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,UAAU,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,KAAK,CACvE,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,CAAC,gBAAgB,CAAC,CAAC;IAChC,CAAC;AACH,CAAC"}

package/dist/orchestrator/templates/specs-checked-state.ts

@@ -0,0 +1,324 @@
+/* eslint-disable */
+/**
+ * Sungen checked-state helper — auto-generated into specs/checked-state.ts. DO NOT EDIT.
+ *
+ * Playwright's `.check()` / `.uncheck()` accept ONLY native checkbox/radio inputs and
+ * `role=checkbox|radio|switch`. Anything else throws "Not a checkbox or radio button" (#675).
+ * A toggle BUTTON — `<button aria-pressed>`, the correct ARIA pattern for a pressed/unpressed
+ * control — is none of those, so a bare `.check()` could never drive one.
+ *
+ * Rewriting the Gherkin to `click` is NOT an equivalent workaround, and that is the whole reason
+ * this helper exists: `click` flips UNCONDITIONALLY, so a scenario that re-runs, or starts from an
+ * unknown state, drives the toggle the WRONG way. Idempotence — end up in the requested state
+ * regardless of where you started — is the entire meaning of `check` / `uncheck`.
+ *
+ * The mechanism is chosen from the ELEMENT at run time, not from the selector's declared role,
+ * because the resolved selector is very often a testid/CSS locator carrying no role at all — so
+ * codegen cannot know what it will hit.
+ *
+ * Deliberately depends on NOTHING but the `Locator` TYPE: no `expect`, no test-runner context. That
+ * keeps the branching testable against a fake locator without a browser (tests/runtime/
+ * checked-state.run.ts) — this file runs inside every user's suite, so its logic is worth pinning.
+ */
+import type { Locator } from '@playwright/test';
+
+/**
+ * Budget for EACH PHASE of a check/uncheck step — classification, the action, and the post-click
+ * verification each get their own (deliberately: see setCheckedState). So the worst case is a small
+ * multiple of this, not this. Raise it for a slow CI box with `SUNGEN_TOGGLE_TIMEOUT_MS`; without an
+ * escape hatch this would silently override a project that raised Playwright's own `actionTimeout`.
+ */
+const ENV_TIMEOUT = Number(process.env.SUNGEN_TOGGLE_TIMEOUT_MS);
+// Guard the parse: `=0` means "no timeout" to Playwright (hang forever) and a negative is nonsense —
+// neither should be inherited from a typo'd env var.
+const TOGGLE_TIMEOUT_MS = Number.isFinite(ENV_TIMEOUT) && ENV_TIMEOUT > 0 ? ENV_TIMEOUT : 8_000;
+const POLL_INTERVAL_MS = 100;
+
+/** A signal DECLARED in selectors.yaml: the class token, or the boolean attribute, marking ON. */
+export interface DeclaredSignal { class?: string; attribute?: string }
+
+/** Where the control publishes its on/off state — decided in the page, from the real element. */
+export type StateSource = 'native' | 'aria-pressed' | 'aria-checked' | 'class' | 'attribute' | 'none';
+export interface ControlProbe {
+  source: StateSource;
+  /** Current state, already normalised. Meaningless when `source` is 'native' (Playwright reads it). */
+  on: boolean;
+  /** Button-like: a control a human would press. Decides how a MISSING state is read — see below. */
+  buttonLike: boolean;
+}
+
+/**
+ * Runs IN THE PAGE, so it must stay self-contained: Playwright serialises it and the browser has
+ * none of this module's scope.
+ *
+ * It also must contain NO inner function of its own — not even an arrow helper. A bundler with
+ * keepNames (esbuild, which is what Playwright itself transpiles specs with) rewrites every named
+ * inner function to `__name(fn, "…")`, that wrapper travels inside the serialised source, and the
+ * page throws `ReferenceError: __name is not defined` on EVERY check step. Straight-line code with
+ * the normalise repeated inline is the price of being serialisable; `tests/runtime/
+ * checked-state.run.ts` pins it so the next edit cannot quietly reintroduce a helper.
+ *
+ * Structurally typed rather than via the DOM lib names because this file is also typechecked
+ * inside the compiler build, whose tsconfig carries no DOM lib.
+ */
+export function probeControl(node: unknown, declared?: DeclaredSignal): ControlProbe {
+  const el = node as {
+    tagName: string; type?: string;
+    getAttribute(n: string): string | null; hasAttribute(n: string): boolean;
+    classList: { contains(c: string): boolean };
+    querySelector(s: string): unknown;
+  };
+  const tag = String(el.tagName ?? '').trim().toLowerCase();   // lowercase: XHTML serves it so
+  const type = String(el.type ?? '').trim().toLowerCase();
+  const role = String(el.getAttribute('role') ?? '').trim().toLowerCase();
+  const ariaCheckableRole = role === 'checkbox' || role === 'radio' || role === 'switch';
+  const buttonLike = tag === 'button' || role === 'button'
+    || (tag === 'input' && (type === 'button' || type === 'submit' || type === 'reset'));
+
+  // A DECLARED signal wins over every ARIA reading below (issue #730). The author reached for this
+  // escape hatch precisely because the component publishes no usable ARIA, so second-guessing them
+  // from a stray role would put the step back on the path that could not work. Self OR descendant:
+  // a card picker swaps the class on the control itself, while a custom checkbox often mounts a
+  // checkmark <svg class="is-checked"> inside instead — both are the same declaration to the author.
+  // `classList.contains` is exact-token by definition; `[class~="…"]` is its selector equivalent,
+  // so neither needs the class escaped and neither can half-match ("is-checked-disabled").
+  if (declared && declared.class) {
+    const onSelf = el.classList != null && el.classList.contains(declared.class);
+    const onChild = !onSelf && el.querySelector('[class~="' + declared.class + '"]') != null;
+    return { source: 'class', on: onSelf || onChild, buttonLike };
+  }
+  // The same declaration published as a boolean attribute instead of a class. Self ONLY, unlike the
+  // class above: a class swap can legitimately live on a checkmark child, but `data-checked` on a
+  // descendant is a different control's state, and reading it would assert the wrong element.
+  if (declared && declared.attribute) {
+    const raw = el.getAttribute(declared.attribute);
+    return { source: 'attribute', on: String(raw ?? '').trim().toLowerCase() === 'true', buttonLike };
+  }
+
+  // A native input needs no ARIA attribute — Playwright reads `.checked` directly.
+  if (tag === 'input' && (type === 'checkbox' || type === 'radio')) return { source: 'native', on: false, buttonLike };
+  // An ARIA checkable publishes state through `aria-checked`, which is what Playwright reads. Only
+  // hand it over when that attribute is actually there: `<button role="switch" aria-pressed="…">`
+  // is a common authoring slip, and routing it to .check() makes Playwright click, re-read the
+  // aria-checked that does not exist, and die on "did not change its state".
+  if (ariaCheckableRole && el.hasAttribute('aria-checked')) return { source: 'native', on: false, buttonLike };
+  if (el.hasAttribute('aria-pressed')) {
+    return { source: 'aria-pressed', on: String(el.getAttribute('aria-pressed') ?? '').trim().toLowerCase() === 'true', buttonLike };
+  }
+  if (el.hasAttribute('aria-checked')) {
+    return { source: 'aria-checked', on: String(el.getAttribute('aria-checked') ?? '').trim().toLowerCase() === 'true', buttonLike };
+  }
+  // Role claims checkable but nothing is published — let Playwright raise its own, precise error.
+  if (ariaCheckableRole) return { source: 'native', on: false, buttonLike };
+  return { source: 'none', on: false, buttonLike };
+}
+
+/** The declaration both helpers forward into the page. Undefined when nothing was declared, so a
+ *  control with real ARIA keeps being read exactly as it was before any of this existed. */
+const declaredSignal = (
+  options?: { checkedClass?: string; checkedAttribute?: string },
+): DeclaredSignal | undefined => (
+  options?.checkedClass ? { class: options.checkedClass }
+    : options?.checkedAttribute ? { attribute: options.checkedAttribute }
+      : undefined
+);
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+/**
+ * Time left on a budget, floored at 250ms. Never 0 — to Playwright that means "no timeout", i.e.
+ * hang forever. And never a sliver either: a 1ms floor makes the last poll fail with
+ * `Timeout 1ms exceeded`, which masks the real, explanatory error this helper is about to throw.
+ * The floor lets a budget overrun by at most 250ms; the loops below terminate on the deadline.
+ */
+const left = (deadline: number): number => Math.max(250, deadline - Date.now());
+
+/** Read the live state. A REMOVED attribute means off: `aria-pressed={on || undefined}` is a common
+ *  React/Vue idiom, so requiring a literal "false" would fail a control that is correctly off. */
+async function readOn(target: Locator, attr: 'aria-pressed' | 'aria-checked', deadline: number): Promise<boolean> {
+  const raw = await target.getAttribute(attr, { timeout: left(deadline) });
+  return String(raw ?? '').trim().toLowerCase() === 'true';
+}
+
+/**
+ * Drive `target` to the requested on/off state, idempotently.
+ *
+ * @param target the control
+ * @param want   `true` = checked/pressed, `false` = unchecked/unpressed
+ * @param label  the `[Selector Ref]` from the feature file, used only in error messages
+ * @param options.checkedClass `checked:`/`selected:` from selectors.yaml — the class marking ON,
+ *        for a control that publishes no ARIA at all (issue #730). Overrides every ARIA reading.
+ * @param options.checkedAttribute the same declaration published as a boolean attribute
+ *        ('true'/'false') instead of a class. A selector declares one or the other, never both.
+ */
+export async function setCheckedState(
+  target: Locator, want: boolean, label: string,
+  options?: { timeout?: number; checkedClass?: string; checkedAttribute?: string },
+): Promise<void> {
+  const timeout = options?.timeout ?? TOGGLE_TIMEOUT_MS;
+  const declared = declaredSignal(options);
+  // TWO budgets, not one shared deadline: a control that hydrates late would otherwise spend the
+  // whole budget being classified and leave the post-click check a single sample — which then
+  // reports "the click landed on the label" when the real problem was the clock.
+  const classifyDeadline = Date.now() + timeout;
+
+  // `locator.evaluate` waits only for ATTACHED. Playwright's own .check() re-resolved the locator on
+  // every actionability retry, so a control that gains its role/aria-* on hydration still worked —
+  // classifying once at first attach would turn a slow mount into a hard failure.
+  let probe = await target.evaluate(probeControl, declared, { timeout: left(classifyDeadline) });
+  while (probe.source === 'none' && classifyDeadline - Date.now() > POLL_INTERVAL_MS) {
+    await sleep(POLL_INTERVAL_MS);
+    probe = await target.evaluate(probeControl, declared, { timeout: left(classifyDeadline) });
+  }
+
+  if (probe.source === 'native') {
+    if (want) await target.check({ timeout });
+    else await target.uncheck({ timeout });
+    return;
+  }
+
+  // A declared class: drive it the way the ARIA path below drives a toggle — click ONLY when the
+  // current state differs, then require the class to reach the requested state. Same idempotence,
+  // and the same refusal to report success on a blind click.
+  if (probe.source === 'class' || probe.source === 'attribute') {
+    if (probe.on === want) return;
+    await target.click({ timeout });
+    const classStart = Date.now();
+    const classDeadline = classStart + timeout;
+    for (;;) {
+      const after = await target.evaluate(probeControl, declared, { timeout: left(classDeadline) });
+      if (after.on === want) return;
+      if (classDeadline - Date.now() <= POLL_INTERVAL_MS) {
+        throw new Error(
+          `[${label}] did not become ${want ? 'checked' : 'unchecked'} within ${Date.now() - classStart}ms of `
+          + `being clicked — the declared ${probe.source} "${declared?.class ?? declared?.attribute}" still reads `
+          + `${want ? 'off' : 'on'}${probe.source === 'class' ? ' on the element and on its descendants' : ''}. `
+          + `Either the click landed on the label rather than the control, or that is not the `
+          + `${probe.source} this component swaps for its on/off state.`,
+        );
+      }
+      await sleep(POLL_INTERVAL_MS);
+    }
+  }
+
+  if (probe.source === 'none') {
+    // Absence on a PRESSABLE control means off — a toggle written as `aria-pressed={on || undefined}`
+    // (React/Vue, and several component libraries a QA team does not own) drops the attribute
+    // entirely when unpressed. Treating that as an error made `uncheck` pass on the first run and
+    // fail on the second, which is precisely the rerun-dependent flake this helper exists to stop.
+    if (probe.buttonLike) {
+      if (!want) {
+        // Nothing to do — but say so, because the alternative is a green step that did nothing at
+        // all (a mis-resolved selector pointing at a plain button looks exactly like this).
+        console.warn(
+          `[sungen] uncheck [${label}]: the control publishes no aria-pressed/aria-checked, so it was `
+          + `read as already unpressed and NOT clicked. If it should have been a toggle, expose `
+          + `aria-pressed in both states; if this is not a toggle at all, the step is a no-op.`,
+        );
+        return;
+      }
+      // Not a blind click: press once, then REQUIRE the control to publish the requested state.
+      // A plain button publishes nothing afterwards either, so it still fails — just one click later.
+      await target.click({ timeout });
+      const pressedStart = Date.now();
+      const pressedDeadline = pressedStart + timeout;
+      for (;;) {
+        const after = await target.evaluate(probeControl, undefined, { timeout: left(pressedDeadline) });
+        if (after.source !== 'none' && after.on === want) return;
+        if (pressedDeadline - Date.now() <= POLL_INTERVAL_MS) {
+          throw new Error(
+            `Cannot check [${label}] — it published no aria-pressed/aria-checked before the click and `
+            + `still none ${Date.now() - pressedStart}ms after it, so it is a plain button rather than a `
+            + `toggle. Give the control a real ARIA toggle state, or use "toggles [${label}]" if an `
+            + `unconditional flip is what you meant.`,
+          );
+        }
+        await sleep(POLL_INTERVAL_MS);
+      }
+    }
+    // Not pressable and publishes nothing — there is no reading of this that makes the step meaningful.
+    throw new Error(
+      `Cannot ${want ? 'check' : 'uncheck'} [${label}] — it is not a checkbox/radio/switch, is not a `
+      + `button, and publishes no aria-pressed/aria-checked, so it has no on/off state to set. Point the `
+      + `selector at the control itself, or give it a real ARIA toggle role.`,
+    );
+  }
+
+  const attr = probe.source;
+  // Already in the requested state → nothing to do. This is the idempotence `check` promises.
+  if (probe.on === want) return;
+  await target.click({ timeout });
+
+  // Fresh budget: this measures the CONTROL's reaction, not time already spent finding it.
+  const verifyStart = Date.now();
+  const verifyDeadline = verifyStart + timeout;
+  for (;;) {
+    if (await readOn(target, attr, verifyDeadline) === want) return;
+    if (verifyDeadline - Date.now() <= POLL_INTERVAL_MS) {
+      throw new Error(
+        `[${label}] did not become ${want ? 'pressed' : 'unpressed'} within ${Date.now() - verifyStart}ms of being `
+        + `clicked — ${attr} still reads ${want ? 'off' : 'on'}. Either the click landed on the label rather than `
+        + `the control, or the handler did not change the state.`,
+      );
+    }
+    await sleep(POLL_INTERVAL_MS);
+  }
+}
+
+/**
+ * Assert the on/off state of the same control family — the read side of #675.
+ *
+ * `expect(locator).toBeChecked()` throws the identical "Not a checkbox or radio button" on a
+ * `<button aria-pressed>`, so driving a toggle worked while asserting it did not. Polls like
+ * Playwright's own web-first assertions rather than sampling once, and reads state exactly the way
+ * setCheckedState does, so an action and the assertion after it can never disagree about what the
+ * control says. Uses `locator.isChecked()` (not `expect`) for the native family, which keeps this
+ * file free of any test-runner dependency.
+ */
+export async function expectCheckedState(
+  target: Locator, expected: boolean, label: string,
+  options?: { timeout?: number; checkedClass?: string; checkedAttribute?: string },
+): Promise<void> {
+  const timeout = options?.timeout ?? TOGGLE_TIMEOUT_MS;
+  // Same signal the action side drives (issue #730) — passing it here is what keeps the invariant
+  // above true for a class-only control too: `source: 'class'` falls into the generic `probe.on`
+  // branch below, so check-then-assert cannot disagree.
+  const declared = declaredSignal(options);
+  const start = Date.now();
+  const deadline = start + timeout;
+  for (;;) {
+    const probe = await target.evaluate(probeControl, declared, { timeout: left(deadline) });
+    let actual: boolean | null = null;
+    if (probe.source === 'native') actual = await target.isChecked({ timeout: left(deadline) });
+    else if (probe.source !== 'none') actual = probe.on;
+    else if (probe.buttonLike) {
+      // Absence on a pressable control reads as off, mirroring setCheckedState. But a plain button
+      // and a correctly-off toggle are indistinguishable HERE, and this is an ASSERTION: returning
+      // green having verified nothing is worse than the loud "Not a checkbox or radio button" it
+      // replaced. So say so, exactly as the action side does for the same reading.
+      if (!expected) {
+        console.warn(
+          `[sungen] see [${label}] is unchecked: the control publishes no aria-pressed/aria-checked, `
+          + `so it was read as unpressed WITHOUT verifying anything. If it should be a toggle, expose `
+          + `aria-pressed in both states; if it is not a toggle, this assertion proves nothing.`,
+        );
+      }
+      actual = false;
+    }
+    if (actual === expected) return;
+    if (deadline - Date.now() <= POLL_INTERVAL_MS) {
+      if (actual === null) {
+        throw new Error(
+          `Cannot assert [${label}] is ${expected ? 'checked' : 'unchecked'} — it is not a `
+          + `checkbox/radio/switch, is not a button, and publishes no aria-pressed/aria-checked, so it `
+          + `reports no state to assert. Point the selector at the control itself, or give it a real `
+          + `ARIA toggle role.`,
+        );
+      }
+      throw new Error(
+        `Expected [${label}] to be ${expected ? 'checked' : 'unchecked'}, but it is `
+        + `${actual ? 'checked' : 'unchecked'} after ${Date.now() - start}ms.`,
+      );
+    }
+    await sleep(POLL_INTERVAL_MS);
+  }
+}

package/dist/orchestrator/templates/specs-report-path-sanitize-reporter.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Playwright reporter that rewrites the operator's machine paths out of the JSON result file.
+ *
+ * The JSON reporter records absolute paths — `config.configFile`, `rootDir`, `projects[]`, every
+ * `error.location.file`, attachment paths, and the paths quoted inside stack traces and messages.
+ * Teams commit that file next to the spec (sungen delivery reads it), so a username and a machine
+ * layout travel into the repository and the deliverable. Nothing downstream needs them absolute.
+ *
+ * Runs in `onExit()` — after every reporter, the JSON one included, has finished writing — reads the
+ * JSON reporter's `outputFile`, rewrites it in place, and stays silent otherwise. Paths under the
+ * project root (the directory of `playwright.config.ts`) become project-relative; outside it a path that
+ * names a machine (a home directory, a drive) keeps only its basename while any other absolute string
+ * — a URL route — is left alone; home directories quoted inside text become `~/`. `sungen results
+ * sanitize` applies the same rules to files that already exist.
+ *
+ * Wired in playwright.config.ts: reporter: [['html'], ['json', {…}], ['./specs/generated/report-path-sanitize-reporter.ts']].
+ * Regenerated by `sungen generate` / `sungen update` — DO NOT EDIT.
+ */
+import type { FullConfig, Reporter } from '@playwright/test/reporter';
+declare class ReportPathSanitizeReporter implements Reporter {
+    private config?;
+    onBegin(config: FullConfig): void;
+    printsToStdio(): boolean;
+    onExit(): Promise<void>;
+    private configDir;
+    /** The JSON reporter's output file: its `outputFile` option, else the env var the config reads. */
+    private jsonOutputFile;
+}
+export default ReportPathSanitizeReporter;
+export declare function sanitizeReportPaths<T>(doc: T, opts: {
+    root: string;
+}): {
+    doc: T;
+    rewritten: number;
+};
+//# sourceMappingURL=specs-report-path-sanitize-reporter.d.ts.map

package/dist/orchestrator/templates/specs-report-path-sanitize-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"specs-report-path-sanitize-reporter.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/templates/specs-report-path-sanitize-reporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAItE,cAAM,0BAA2B,YAAW,QAAQ;IAClD,OAAO,CAAC,MAAM,CAAC,CAAa;IAE5B,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAIjC,aAAa,IAAI,OAAO;IAIlB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB7B,OAAO,CAAC,SAAS;IAIjB,mGAAmG;IACnG,OAAO,CAAC,cAAc;CAWvB;AAED,eAAe,0BAA0B,CAAC;AAW1C,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,CAAC,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAmBpG"}