@sun-asterisk/sungen 3.2.29 → 3.2.30

package/src/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/src/orchestrator/templates/specs-report-path-sanitize-reporter.ts

@@ -0,0 +1,142 @@
+/**
+ * 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';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+class ReportPathSanitizeReporter implements Reporter {
+  private config?: FullConfig;
+
+  onBegin(config: FullConfig): void {
+    this.config = config;
+  }
+
+  printsToStdio(): boolean {
+    return false;
+  }
+
+  async onExit(): Promise<void> {
+    const file = this.jsonOutputFile();
+    if (!file || !fs.existsSync(file)) return;
+    const root = this.configDir();
+    let doc: unknown;
+    try {
+      doc = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    } catch {
+      return; // not ours to repair — leave whatever the JSON reporter wrote
+    }
+    const { doc: clean, rewritten } = sanitizeReportPaths(doc, { root });
+    if (rewritten === 0) return;
+    const tmp = `${file}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(clean, null, 2));
+    fs.renameSync(tmp, file);
+  }
+
+  private configDir(): string {
+    return this.config?.configFile ? path.dirname(this.config.configFile) : process.cwd();
+  }
+
+  /** The JSON reporter's output file: its `outputFile` option, else the env var the config reads. */
+  private jsonOutputFile(): string | undefined {
+    const entry = (this.config?.reporter ?? []).find(([name]) => name === 'json');
+    const opt = (entry?.[1] as { outputFile?: string } | undefined)?.outputFile
+      ?? process.env.PLAYWRIGHT_JSON_OUTPUT_FILE   // Playwright's own override
+      ?? process.env.PLAYWRIGHT_JSON_OUTPUT_NAME;  // the name sungen's config template reads
+    if (!opt) return undefined;
+    if (path.isAbsolute(opt)) return opt;
+    // Playwright resolves a relative outputFile against the config directory; the env var against cwd.
+    const candidates = [path.resolve(this.configDir(), opt), path.resolve(process.cwd(), opt)];
+    return candidates.find((c) => fs.existsSync(c)) ?? candidates[0];
+  }
+}
+
+export default ReportPathSanitizeReporter;
+
+// ── sanitizer — the same rules as sungen's `report-path-sanitizer.ts`, embedded so this file needs no
+//    import from the compiler package (a parity test in sungen keeps the two in step) ──────────────
+
+const ABSOLUTE = /^(?:file:\/\/\/?|[A-Za-z]:[\\/]|\/)/;
+const WINDOWS_DRIVE = /^[A-Za-z]:/;
+const HOME_DIR = /(?<![\w.:/\\-])(?:file:\/\/\/?)?(?:\/(?:Users|home)\/[^/\\\s"'`)\]]+[/\\]|[A-Za-z]:[\\/]Users[\\/][^/\\\s"'`)\]]+[\\/])/g;
+
+interface Root { posix: string; caseInsensitive: boolean; pattern: RegExp }
+
+export function sanitizeReportPaths<T>(doc: T, opts: { root: string }): { doc: T; rewritten: number } {
+  const root = normalizeRoot(opts.root);
+  if (root.posix.length < 2) return { doc, rewritten: 0 }; // a `/` root would shred the document
+  let rewritten = 0;
+  const walk = (v: unknown): unknown => {
+    if (typeof v === 'string') {
+      const next = sanitizeString(v, root);
+      if (next !== v) rewritten++;
+      return next;
+    }
+    if (Array.isArray(v)) return v.map(walk);
+    if (v && typeof v === 'object') {
+      const out: Record<string, unknown> = {};
+      for (const [k, x] of Object.entries(v as Record<string, unknown>)) out[k] = walk(x);
+      return out;
+    }
+    return v;
+  };
+  return { doc: walk(doc) as T, rewritten };
+}
+
+function normalizeRoot(raw: string): Root {
+  const posix = toPosix(stripFileScheme(raw)).replace(/\/+$/, '');
+  const caseInsensitive = WINDOWS_DRIVE.test(posix);
+  const body = posix.split('/').map(escapeRegExp).join('[\\\\/]');
+  return { posix, caseInsensitive, pattern: new RegExp(`(?:file:\\/\\/\\/?)?${body}(?:[\\\\/](?![\\\\/])|(?=$|[\\s"'\`):,]))`, caseInsensitive ? 'gi' : 'g') };
+}
+
+function sanitizeString(value: string, root: Root): string {
+  const trimmed = value.trim();
+  if (ABSOLUTE.test(trimmed) && !/\s/.test(trimmed)) {
+    const p = toPosix(stripFileScheme(trimmed)).replace(/\/+$/, '');
+    const a = root.caseInsensitive ? p.toLowerCase() : p;
+    const b = root.caseInsensitive ? root.posix.toLowerCase() : root.posix;
+    if (a === b) return '.';
+    if (a.startsWith(b + '/')) return p.slice(root.posix.length + 1);
+    // outside the root: only a machine path (home dir, drive) is cut to its basename — `/products` is a route
+    if (WINDOWS_DRIVE.test(p) || /\/(?:Users|home)\/[^/]+\/./.test(p)) {
+      // another machine's checkout of this project → relative from the project directory; else basename
+      const marker = '/' + root.posix.slice(root.posix.lastIndexOf('/') + 1) + '/';
+      const i = marker.length > 2 ? (root.caseInsensitive ? p.toLowerCase().indexOf(marker.toLowerCase()) : p.indexOf(marker)) : -1;
+      if (i >= 0) return p.slice(i + marker.length);
+      return p.slice(p.lastIndexOf('/') + 1) || p;
+    }
+    return value;
+  }
+  const out = value.replace(root.pattern, (m: string) => (/[\\/]$/.test(m) ? '' : '.'));
+  return out.replace(HOME_DIR, '~/');
+}
+
+function stripFileScheme(p: string): string {
+  if (!p.startsWith('file://')) return p;
+  const rest = p.slice('file://'.length);
+  return /^\/[A-Za-z]:/.test(rest) ? rest.slice(1) : rest;
+}
+
+function toPosix(p: string): string {
+  return p.replace(/\\/g, '/');
+}
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/orchestrator/templates/specs-url-assert.ts

@@ -2,7 +2,8 @@
 /**
  * Sungen URL assertion helper — auto-generated into specs/url-assert.ts. DO NOT EDIT.
  *
- * Every Then-side URL assertion (`see [X] page`, `is on [X] page`) compiles to one call here.
+ * Every URL step compiles to one call here: the Then-side assertions (`see [X] page`,
+ * `is on [X] page`) to `expectPage`, and `wait for [X] page` to `waitForPage`.
  *
  * Why a helper and not an inline predicate. The predicate used to be emitted inline into every
  * spec, so each correction to what "the URL matches" MEANS was a breaking change for every
@@ -28,6 +29,16 @@ export interface UrlExpectation {
    * against a full URL.
    */
   pathname: RegExp;
+  /**
+   * Anchored hostname pattern, emitted ONLY when the page selector's `value` is an ABSOLUTE URL
+   * (`https://app.example.com/reception/:id`) — a destination on a different host from the suite's
+   * baseURL. Absent means "whatever host we are on", which is what a relative page value says.
+   *
+   * It is a SEPARATE field rather than part of `pathname` because the two are read off different
+   * properties of the parsed URL: `u.hostname` never appears in `u.pathname`. One concatenated
+   * regex only worked while the match ran unanchored over the whole URL string (#677).
+   */
+  hostname?: RegExp;
   /**
    * The `with {{v}}` value, raw from test-data: '?q=1' · '/vi/search?q=1' · '#tab' · ''.
    * `undefined` means the step declared nothing, which is itself an assertion — see below.
@@ -83,6 +94,15 @@ function decodedPath(pathname: string): string {
   }
 }
 
+/**
+ * Is the URL at the expected LOCATION — right host, right path? The half every URL step shares.
+ * The Then-side assertion goes on to judge the query; the wait stops here (see `waitForPage`).
+ */
+function locationMatches(pathname: RegExp, hostname: RegExp | undefined, u: URL): boolean {
+  if (hostname && !hostname.test(u.hostname)) return false;
+  return pathname.test(u.pathname) || pathname.test(decodedPath(u.pathname));
+}
+
 /**
  * Build the predicate for `expect(page).toHaveURL(...)`.
  *
@@ -94,9 +114,9 @@ function decodedPath(pathname: string): string {
  *                      A declared fragment is asserted too; a declared value carrying no query
  *                      at all constrains the path only (the compiler warns: SG-W014).
  */
-export function urlMatches({ pathname, declared, dataRef }: UrlExpectation): (u: URL) => boolean {
+export function urlMatches({ pathname, hostname, declared, dataRef }: UrlExpectation): (u: URL) => boolean {
   return (u: URL): boolean => {
-    if (!pathname.test(u.pathname) && !pathname.test(decodedPath(u.pathname))) return false;
+    if (!locationMatches(pathname, hostname, u)) return false;
 
     // `dataRef`, not `declared`, decides which rule applies. Both "the step declared nothing" and
     // "the step declared {{v}} but the key resolved to nothing at runtime" arrive here as
@@ -135,38 +155,43 @@ export function urlMatches({ pathname, declared, dataRef }: UrlExpectation): (u:
   };
 }
 
+/** What `settleAndHold` needs of a page — Playwright's `Page` satisfies it; so does a test fake. */
+type SettleablePage = {
+  url(): string;
+  waitForLoadState(state: 'networkidle', opts?: { timeout?: number }): Promise<void>;
+};
+
+/** The two runtime knobs, shared by both URL steps. */
+interface SettleOpts { settleMs?: number; networkIdleMs?: number }
+
 /**
- * `toHaveURL` is a polling assertion: it passes on the FIRST sample that matches. A client-side
- * router pushes the destination URL before the route guard or the API has answered, so a user
- * with no permission is "on" `/items/detail` for a few hundred milliseconds — long enough for
- * the assertion to sample it, pass, and end the test green — and is then bounced to `/forbidden`
- * with no assertion left to see it. A real project shipped a permission matrix on that oracle;
- * the 403s were found by hand (#662).
+ * A URL that MATCHES is not a page the user is still on. A client-side router pushes the
+ * destination URL before the route guard or the API has answered, so a user with no permission is
+ * "on" `/items/detail` for a few hundred milliseconds — long enough for a polling assertion to
+ * sample it and pass, or for a `waitForURL` to resolve — and is then bounced to `/forbidden` with
+ * nothing left watching. A real project shipped a permission matrix on that oracle; the 403s were
+ * found by hand (#662).
  *
- * `expectPage` is the page oracle `see [X] page` compiles to now. Arriving is not enough: the URL
- * has to be STILL matching once the page has settled.
- *   1. arrive   — the same predicate `toHaveURL` always used;
- *   2. settle   — wait for network to go quiet (bounded: an app that polls forever must not hang
- *                 the test, so a timeout here is not a failure);
- *   3. hold     — sample the URL over a settle window; the moment it stops matching, fail and
- *                 NAME where it went, because that destination is the finding;
- *   4. re-assert — the arrival predicate, once more, on the settled page.
+ * So both URL steps go through this: having arrived,
+ *   1. settle    — wait for network to go quiet (bounded: an app that polls forever must not hang
+ *                  the test, so a timeout here is not a failure);
+ *   2. hold      — sample the URL over a settle window; the moment it stops matching, fail and
+ *                  NAME where it went, because that destination is the finding.
+ * The caller decides what arriving meant and what to do afterwards.
  *
  * `SUNGEN_URL_SETTLE_MS` (default 1000) is the hold window; `SUNGEN_URL_NETWORKIDLE_MS` (default
- * 3000) bounds step 2. Both are runtime knobs, so a slow environment is a config change, not a
+ * 3000) bounds step 1. Both are runtime knobs, so a slow environment is a config change, not a
  * regenerate.
  */
-export async function expectPage(
-  page: { url(): string; waitForLoadState(state: 'networkidle', opts?: { timeout?: number }): Promise<void> },
-  expectation: UrlExpectation,
-  opts: { settleMs?: number; networkIdleMs?: number; assertUrl?: (matches: (u: URL) => boolean) => Promise<void> } = {},
+async function settleAndHold(
+  page: SettleablePage,
+  matches: (u: URL) => boolean,
+  opts: SettleOpts,
+  label: string,
+  consequence: string,
 ): Promise<void> {
   const settleMs = opts.settleMs ?? Number(process.env.SUNGEN_URL_SETTLE_MS ?? 1000);
   const networkIdleMs = opts.networkIdleMs ?? Number(process.env.SUNGEN_URL_NETWORKIDLE_MS ?? 3000);
-  const matches = urlMatches(expectation);
-  const assertUrl = opts.assertUrl ?? (async (m: (u: URL) => boolean) => { await expect(page as unknown as Page).toHaveURL(m); });
-
-  await assertUrl(matches);
   const arrivedAt = page.url();
 
   await page.waitForLoadState('networkidle', { timeout: networkIdleMs }).catch(() => undefined);
@@ -176,13 +201,61 @@ export async function expectPage(
     const now = page.url();
     if (!matches(new URL(now))) {
       throw new Error(
-        `page assertion: reached ${arrivedAt} and then left for ${now} after ${Date.now() - started}ms — `
+        `${label}: reached ${arrivedAt} and then left for ${now} after ${Date.now() - started}ms — `
         + 'a route guard, an error boundary or a redirect moved the user away after the URL had already '
-        + 'matched. The page the test asserted is not the page the user ended on.',
+        + `matched. ${consequence}`,
       );
     }
     await new Promise((r) => setTimeout(r, 50));
   }
+}
+
+/**
+ * `expectPage` is the page oracle `see [X] page` / `is on [X] page` compile to. Arriving is not
+ * enough: the URL has to be STILL matching once the page has settled.
+ *   1. arrive    — the same predicate `toHaveURL` always used;
+ *   2. settle + hold — see `settleAndHold`;
+ *   3. re-assert — the arrival predicate, once more, on the settled page.
+ */
+export async function expectPage(
+  page: SettleablePage,
+  expectation: UrlExpectation,
+  opts: SettleOpts & { assertUrl?: (matches: (u: URL) => boolean) => Promise<void> } = {},
+): Promise<void> {
+  const matches = urlMatches(expectation);
+  const assertUrl = opts.assertUrl ?? (async (m: (u: URL) => boolean) => { await expect(page as unknown as Page).toHaveURL(m); });
 
   await assertUrl(matches);
+  await settleAndHold(page, matches, opts, 'page assertion',
+    'The page the test asserted is not the page the user ended on.');
+  await assertUrl(matches);
+}
+
+/**
+ * `waitForPage` is what `When User wait for [X] page` compiles to (#677).
+ *
+ * A bare `page.waitForURL(/…/)` resolves on the first URL sample that matches — the transient URL
+ * the router pushed before its guard decided. The wait then returned, and every step AFTER it ran
+ * against a page mid-redirect, so their failures pointed at the wrong thing. It was also the third
+ * hand-rolled copy of "does this URL match", drifting from the pair #662 consolidated here.
+ *
+ * Where this deliberately DIFFERS from `expectPage`: the query is not constrained. A Then-side page
+ * assertion is an oracle, so a bare page must be bare — `/vi/search` fails on `/vi/search?x=1`. A
+ * wait is not an oracle: `wait for [Results] page` after submitting a search legitimately lands on
+ * `/results?q=abc`, and reddening there would assert something the step never said. Prove the query
+ * with the `Then User see [Results] page with {{v}}` that follows.
+ */
+export async function waitForPage(
+  page: SettleablePage & { waitForURL(url: (u: URL) => boolean, opts?: { timeout?: number }): Promise<void> },
+  expectation: UrlExpectation,
+  opts: SettleOpts & { timeout?: number; waitUrl?: (matches: (u: URL) => boolean) => Promise<void> } = {},
+): Promise<void> {
+  const { pathname, hostname } = expectation;
+  const matches = (u: URL): boolean => locationMatches(pathname, hostname, u);
+  // Playwright's own navigation timeout governs the arrival; only the hold is sungen's.
+  const arrive = opts.waitUrl ?? (async (m: (u: URL) => boolean) => { await page.waitForURL(m, { timeout: opts.timeout }); });
+
+  await arrive(matches);
+  await settleAndHold(page, matches, opts, 'page wait',
+    'The steps after this wait would have run against a page the user is already being moved off.');
 }