@sun-asterisk/sungen 3.2.27 → 3.2.28

package/dist/orchestrator/templates/specs-url-assert.js

@@ -21,6 +21,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.joinPath = joinPath;
 exports.urlMatches = urlMatches;
+exports.expectPage = expectPage;
+const test_1 = require("@playwright/test");
 /**
  * Join a page's URL with the `with {{v}}` value for a NAVIGATION step
  * (`Given User is on [X] page with {{v}}`).
@@ -118,4 +120,45 @@ function urlMatches({ pathname, declared, dataRef }) {
         return queryOk && hashOk;
     };
 }
+/**
+ * `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).
+ *
+ * `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.
+ *
+ * `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
+ * regenerate.
+ */
+async function expectPage(page, expectation, opts = {}) {
+    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) => { await (0, test_1.expect)(page).toHaveURL(m); });
+    await assertUrl(matches);
+    const arrivedAt = page.url();
+    await page.waitForLoadState('networkidle', { timeout: networkIdleMs }).catch(() => undefined);
+    const started = Date.now();
+    while (Date.now() - started < settleMs) {
+        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 — `
+                + '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.');
+        }
+        await new Promise((r) => setTimeout(r, 50));
+    }
+    await assertUrl(matches);
+}
 //# sourceMappingURL=specs-url-assert.js.map

package/dist/orchestrator/templates/specs-url-assert.js.map

@@ -1 +1 @@
-{"version":3,"file":"specs-url-assert.js","sourceRoot":"","sources":["../../../src/orchestrator/templates/specs-url-assert.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"specs-url-assert.js","sourceRoot":"","sources":["../../../src/orchestrator/templates/specs-url-assert.ts"],"names":[],"mappings":"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"}

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

@@ -18,6 +18,8 @@
  * URL, and needs no regex escaping of runtime values, which is what forced the split.
  */
 
+import { expect, type Page } from '@playwright/test';
+
 export interface UrlExpectation {
   /**
    * Anchored pathname pattern, compiled by the generator from the page selector's `value`
@@ -132,3 +134,55 @@ export function urlMatches({ pathname, declared, dataRef }: UrlExpectation): (u:
     return queryOk && hashOk;
   };
 }
+
+/**
+ * `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).
+ *
+ * `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.
+ *
+ * `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
+ * 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> } = {},
+): 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);
+
+  const started = Date.now();
+  while (Date.now() - started < settleMs) {
+    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 — `
+        + '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.',
+      );
+    }
+    await new Promise((r) => setTimeout(r, 50));
+  }
+
+  await assertUrl(matches);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.27",
+  "version": "3.2.28",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -40,8 +40,8 @@
     "@babel/types": "^7.28.5",
     "@cucumber/gherkin": "^37.0.0",
     "@cucumber/messages": "^31.0.0",
-    "@sungen/driver-data-factory": "3.2.27",
-    "@sungen/driver-ui": "3.2.27",
+    "@sungen/driver-data-factory": "3.2.28",
+    "@sungen/driver-ui": "3.2.28",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",

package/src/generators/test-generator/adapters/appium/templates/steps/assertions/page-assertion.hbs

@@ -1 +1,7 @@
+{{#if anchor~}}
+{{!-- A native app has no URL; the page's declared `anchor:` (a screen marker) IS the page oracle
+      here — the same rendered-content proof the web side adds after its URL check (#662). --}}
+await __assertVisible({{#with anchor}}{{> appium-selector-expr}}{{/with}});
+{{~else~}}
 // page/URL assertion is not applicable on mobile (no URL) — [{{value}}]
+{{~/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/page-assertion.hbs

@@ -1 +1,2 @@
-{{> url-assertion}}
+{{> url-assertion}}{{#if anchor}}
+await expect({{#with anchor}}{{> locator}}{{/with}}).toBeVisible();{{/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/partials/url-assertion.hbs

@@ -11,5 +11,9 @@
       Only `pathRegex` is the generator's business: it alone knows the page selector's value and
       its `:id` wildcards, and it is pre-escaped by pathToRegexSource. `\/?$` normalises a
       trailing slash so `/vi/search/` does not read as a different page. The declared value stays
-      a plain string literal so the runtime-data marker pass can rewrite it to testData.get(…). --}}
-await expect(page).toHaveURL(urlMatches({ pathname: /^{{pathRegex}}\/?$/{{#if query}}, dataRef: '{{escapeQuotes dataRef}}', declared: '{{escapeQuotes query}}'{{/if}} }));
+      a plain string literal so the runtime-data marker pass can rewrite it to testData.get(…).
+
+      `expectPage`, not a bare `toHaveURL`: a polling URL assertion passes on the first transient
+      match, before a route guard has bounced the user away (#662). The helper arrives, lets the
+      page settle, holds, and re-asserts — read specs/url-assert.ts. --}}
+await expectPage(page, { pathname: /^{{pathRegex}}\/?$/{{#if query}}, dataRef: '{{escapeQuotes dataRef}}', declared: '{{escapeQuotes query}}'{{/if}} });

package/src/generators/test-generator/code-generator.ts

@@ -346,7 +346,7 @@ export class CodeGenerator {
     // helper into every UI spec — including the many that touch no URL at all. Hence the body is
     // rendered BEFORE the imports. Importing exactly the names used keeps the import honest; the
     // helper file itself is synced only when something needs it (an api-only unit carries none).
-    const urlAssertImports = ['urlMatches', 'joinPath'].filter((n) => testCode.includes(`${n}(`)).join(', ');
+    const urlAssertImports = ['urlMatches', 'joinPath', 'expectPage'].filter((n) => testCode.includes(`${n}(`)).join(', ');
     if (urlAssertImports) this.syncGeneratedHelper(outputDir, 'url-assert.ts', 'specs-url-assert.ts');
 
     // Same body-first rule for the runtime regex-escape helper: only a spec whose

package/src/generators/test-generator/step-mapper.ts

@@ -490,7 +490,7 @@ export class StepMapper {
    */
   private checkPageAssertionFallback(step: ParsedStep, mapped: MappedStep): void {
     if (!this.diagnostics || !step.selectorRef || step.elementType !== 'page') return;
-    if (!(mapped.code || '').includes('urlMatches(')) return;
+    if (!/\b(?:urlMatches|expectPage)\(/.test(mapped.code || '')) return;   // both URL-assertion shapes (#662)
     let resolvedAsPage = false;
     try {
       const resolved = this.selectorResolver.resolveSelector(
@@ -518,7 +518,7 @@ export class StepMapper {
    */
   private checkDeclaredUrlHasNoQuery(step: ParsedStep, mapped: MappedStep): void {
     if (!this.diagnostics || !step.dataRef || step.elementType !== 'page') return;
-    if (!(mapped.code || '').includes('urlMatches(')) return;
+    if (!/\b(?:urlMatches|expectPage)\(/.test(mapped.code || '')) return;   // both URL-assertion shapes (#662)
     // The base value, never resolveData(): in runtime mode that returns the marker, which carries
     // no query by construction — the diagnostic would then fire on every single step.
     const value = this.dataResolver.peekBaseValue(step.dataRef, this.featureName);

package/src/generators/test-generator/utils/selector-resolver.ts

@@ -23,6 +23,12 @@ interface SelectorEntry {
   scope?: string;         // Parent landmark aria-label to scope within (e.g., 'desktop navigation')
   match?: 'exact' | 'partial';  // For getByText matching (default: partial)
 
+  // === Page anchor (#662) ===
+  // For a `type: page` entry: the element that proves the page has RENDERED — a heading, a
+  // landmark, a title. `see [X] page` asserts the URL and then this element, so a route guard
+  // that bounces the user after the URL has already matched turns the step red instead of green.
+  anchor?: SelectorEntry;
+
   // === Mobile per-platform variant (issue #392) ===
   // `android:`/`ios:` sub-selectors for one logical element whose locator differs per OS (composite
   // content-desc, partial/dynamic text, native predicate). Each is a full SelectorEntry.
@@ -127,6 +133,7 @@ export interface ResolvedSelector {
   attribute?: string;   // Attribute to check
   pattern?: string;     // Regex for attribute value
   expanded?: { class?: string; attribute?: string; state?: 'none' };  // Expand/collapse state signal
+  anchor?: ResolvedSelector;  // page entries only — the rendered-content proof behind `see [X] page` (#662)
 }
 
 /**
@@ -580,6 +587,9 @@ export class SelectorResolver {
     if (entry.attribute) v2Fields.attribute = entry.attribute;
     if (entry.pattern) v2Fields.pattern = entry.pattern;
     if (entry.expanded) v2Fields.expanded = entry.expanded;
+    // The anchor is a selector in its own right; it must not inherit the PAGE's label as its
+    // accessible name, so it resolves against its own name (or nothing).
+    if (entry.anchor) v2Fields.anchor = this.resolveFromEntry(entry.anchor, entry.anchor.name ?? '');
 
     // Helper to attach v2 fields and inputMethod
     const withExtras = (resolved: ResolvedSelector): ResolvedSelector => {

package/src/harness/audit.ts

@@ -591,7 +591,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     findings.push(`FLOW-DEPTH: this stateful flow (${what}) exercises ${dims - flowDepth.missing.length}/${dims} applicable regression dimensions — missing [${flowDepth.missing.join(', ')}] → ${flowDepth.missing.map((m) => how[m]).join('; ')}. (businessDepth is capped until covered.)`);
   }
   for (const w of oracle.weak) {
-    findings.push(`ORACLE-WEAK: "${w.name}" — ${w.hint}`);
+    findings.push(`${w.code ?? 'ORACLE-WEAK'}: "${w.name}" — ${w.hint}`);
   }
   for (const u of claim.unproven) {
     const tag = u.severity === 'fail' ? 'CLAIM-UNPROVEN' : 'CLAIM-WEAK';

package/src/harness/next-step.ts

@@ -166,6 +166,7 @@ export function readUnitState(
 const REPAIRABLE = [
   'FLOW-CONTRACT-MISSING', 'FLOW-INVENTORY-MISSING', 'FLOW-UNCOVERED', 'FLOW-UNDECLARED',
   'FLOW-PHASE-MISFILED', 'FLOW-GUARANTEE-MISSING', 'FLOW-OUTCOME-UNPROVEN', 'CONTINUITY-ONE-SIDED',
+  'ORACLE-URL-ONLY',
   'SPEC-RESTATED-UNVERIFIED', 'VIEWPOINT-GESTURE-SUBSTITUTED', 'SPEC-UNCOVERED', 'TRIGGER-UNCOVERED',
   'VIEWPOINT-ITEM-MISSING', 'MANUAL-CODE-MISSING', 'MANUAL-AUTOMATABLE', 'DEPTH-DEFERRED',
 ];

package/src/harness/sensors.ts

@@ -386,7 +386,7 @@ export function flowRegressionDepth(scenarios: ScenarioInfo[]): FlowDepthResult
 // ---------- Sensor: Oracle strength (H4) ----------
 
 export interface OracleStrengthResult {
-  weak: { name: string; hint: string }[];   // scenarios proving facet membership by a name-substring
+  weak: { name: string; hint: string; code?: string }[];   // facet-by-name-substring, or URL-only (code ORACLE-URL-ONLY)
   facetClaims: number;                       // scenarios that touch a category/brand facet (denominator)
   ratio: number;                             // 1 - weak/facetClaims (1 when none) — caps businessDepth
 }
@@ -395,11 +395,34 @@ export interface OracleStrengthResult {
 // a category/brand term does NOT prove the item BELONGS to that facet (a "Dress" item need not contain
 // "Dress" in its name). The strong oracle is the results-page title/header, a detail-page facet field,
 // an API/DB query, or an explicit @manual:M2 deferral.
+/** A `Then` that only asserts where the browser IS: `see [X] page`, `is on [X] page`, `should see route`. */
+const URL_ONLY_THEN = /\]\s*page\b|\bis on \[|\bshould (?:see route|remain on)\b/i;
+/** The scenarios where a transient URL lies most expensively: permission, auth, guards, redirects. */
+const GUARD_LIKE = /\b(?:auth\w*|role|permission|access|guard|redirect\w*|forbidden|403|unauthori[sz]\w*|logged[- ]?(?:in|out)|session)\b|権限|quyền|đăng nhập/i;
+
 const WEAK_FACET_ORACLE = /\bsee all\b\s*\[[^\]]*\b(name|title|label)\b[^\]]*\][^{[]*\bcontains?\b[^{]*\{\{[^}]*\b(categ|brand|facet|filter|term)/i;
 const FACET_REF = /\{\{[^}]*\b(categ|brand|facet|filter)\b[^}]*\}\}|\b(category|brand)\b/i;
 
 export function oracleStrength(scenarios: ScenarioInfo[]): OracleStrengthResult {
-  const weak: { name: string; hint: string }[] = [];
+  const weak: { name: string; hint: string; code?: string }[] = [];
+  // A scenario whose EVERY `Then` is a URL assertion has a URL-only oracle. `toHaveURL` passes on
+  // the first transient match, and a client-side router pushes the destination before the guard or
+  // the API has answered — so "role X can open screen Y" stayed green while the server returned 403
+  // and the app bounced to its error page (#662). The runtime now settles and re-asserts, which
+  // catches the bounce; this names the scenarios that still prove nothing about the page having
+  // RENDERED, and the one-line-per-screen fix.
+  for (const s of scenarios) {
+    if (s.manual) continue;
+    const thens = (s.steps ?? []).filter((st) => st.bucket === 'then');
+    if (thens.length === 0) continue;
+    if (!thens.every((st) => URL_ONLY_THEN.test(st.text))) continue;
+    const guardLike = GUARD_LIKE.test(s.haystack);
+    weak.push({
+      name: s.name.slice(0, 80),
+      code: 'ORACLE-URL-ONLY',
+      hint: `every \`Then\` is a URL assertion${guardLike ? ' on a permission / guard scenario' : ''} — it proves the router pushed a path, not that the page rendered for this user${guardLike ? ', and this is exactly the scenario a late 403 redirect turns falsely green' : ''}. Give the page selector an \`anchor:\` (a heading/landmark only the rendered page has) — one line per screen, and every \`see [X] page\` on it becomes a content oracle — or add a content assertion after it.`,
+    });
+  }
   for (const s of scenarios) {
     if (s.manual) continue; // a @manual facet check is a deliberate deferral, not a weak automated oracle
     if (WEAK_FACET_ORACLE.test(s.stepsText)) {

package/src/orchestrator/templates/ai-src/skills/sungen-gherkin-syntax/SKILL.md

@@ -121,10 +121,28 @@ two content-filtered queries can hit different rows if the table re-renders in b
 > assert the page you expect (`Then User see [Other] page`); to say "this went away", assert a marker
 > element (`Then User see [Some Element] is hidden`).
 
+**Pattern 8 is a URL oracle, and a URL is not a rendered page.** `see [T] page` proves the router
+pushed a path — it does NOT prove the page rendered for this user. A client-side router pushes the
+destination BEFORE the route guard or the permission API has answered, so a user with no permission
+is "on" `/items/detail` for a few hundred milliseconds before being bounced to the 403 page. Since
+3.2.28 the step compiles to `expectPage(page, {…})` — arrive, let the page settle, HOLD the URL, and
+re-assert — so a late redirect fails and names where the user ended up. But the page having
+rendered is still unproven: **for permission / auth-guard / "role X can open screen Y" scenarios,
+give the page selector an `anchor:`** (a heading or landmark only the rendered page has) — every
+`see [T] page` on that screen then asserts the anchor too — or follow the page step with a content
+assertion. A scenario whose every `Then` is a page assertion is reported as `ORACLE-URL-ONLY`.
+
+```yaml
+detail:
+  type: 'page'
+  value: '/items/detail'
+  anchor: { type: 'role', value: 'heading', name: 'Item Detail' }   # the rendered-content proof
+```
+
 **Pattern 8 — the page assertion judges pathname AND query together.** Both `see [T] page` and
-`is on [T] page` (Then-side) compile to ONE web-first predicate — `toHaveURL(urlMatches({…}))`,
-which retries like any other assertion — comparing the **exact** pathname (anchored, trailing slash
-normalised) plus the query:
+`is on [T] page` (Then-side) compile to ONE web-first check — `expectPage(page, {…})`, built on
+`toHaveURL(urlMatches({…}))` and retrying like any other assertion — comparing the **exact** pathname
+(anchored, trailing slash normalised) plus the query:
 
 | step | asserts |
 |---|---|

package/src/orchestrator/templates/ai-src/skills/sungen-harness-audit/SKILL.md

@@ -34,6 +34,7 @@ user-invocable: false
 | **DEPTH** | business-critical scenarios assert only visibility/navigation | Replace `Then User see [X] page/section` with **observable data assertions**: `Then User see [X] with {{value}}`, `Then User see [T] table match data:`. Capture real expected values into `test-data.yaml`. |
 | **BALANCE** | secondary viewpoints (UI/validation/security) outweigh business-core | **Stop expanding** secondary viewpoints; generate the missing business-core scenarios first. Do not add more subscription/UI variants while core is thin. |
 | **TRACE** | scenarios use ad-hoc `VP-<CAT>-NNN` codes not linked to the viewpoint-overview | Make each scenario map to a viewpoint-overview id (align category codes, or add a mapping comment). |
+| **ORACLE-URL-ONLY** | every `Then` in the scenario is a page/URL assertion — it proves a path was pushed, not that the page rendered; on a permission/guard scenario a late 403 redirect turns it falsely green | Add `anchor:` to the page selector (one line per screen; every `see [X] page` on it becomes a content oracle) or a content assertion after the page step. Never delete the page step to silence it. |
 | **UNIVERSAL** | a universal theme (error/empty-state, accessibility) is absent | Low priority — add if in scope; otherwise note as out-of-scope with reason. |
 
 ## P5 steps for deep cross-screen / list coverage

package/src/orchestrator/templates/ai-src/skills/sungen-selector-keys/SKILL.md

@@ -63,6 +63,10 @@ login:
 awards:
   type: 'page'
   value: '/awards'
+  anchor:                      # optional — the element that proves the page RENDERED (#662).
+    type: 'role'               # `see [Awards] page` asserts the URL, then this; without it the step is
+    value: 'heading'           # a URL-only oracle a late 403 redirect can satisfy. One line per screen.
+    name: 'Awards'
 
 "awards:submit":
   type: 'role'

package/src/orchestrator/templates/ai-src/skills/sungen-tc-generation/SKILL.md

@@ -375,7 +375,7 @@ Security:         [S1 – admin only]
 | Validation rule | 1 exact-message TC per rule | `@high` |
 | Business rule | 1 behavioral TC per rule | `@high` |
 | **Secondary behavior / tiebreaker** | **1 TC per tiebreaker or fallback rule in `Secondary behaviors`** | **`@high`** |
-| Auth / OAuth / permissions | 1 VP-SEC TC | `@high` |
+| Auth / OAuth / permissions | 1 VP-SEC TC — **with a rendered-content oracle**: `see [X] page` alone is a URL check a late 403 redirect passes; give the page selector an `anchor:` or add a content assertion (`ORACLE-URL-ONLY`) | `@high` |
 | Free-text input | 1 XSS TC **and** 1 SQL injection TC (separate) | `@high` |
 | **Free-text LIKE / partial-match field** | **1 field-level SQL TC + 1 API-level SQL `@manual` TC** | **`@high`** |
 | Lifecycle states | 1 key state transition TC | `@high` |

package/src/orchestrator/templates/ai-src/skills/sungen-viewpoint/group-d-display.md

@@ -147,6 +147,7 @@ See `SKILL.md` for the 4 Viewpoints, Shared Checks, and Security Tag Rules.
 
 - A menu item for a restricted page is shown but the user has no permission → click → a 403 page; or the item is hidden from the menu (verify the DOM has no link and the API returns no data)
 - Direct URL access to a restricted page while not logged in → redirect to Login, the URL is preserved so post-login redirects correctly
+- **The oracle for "role X can open screen Y" is rendered content, not the URL.** A client-side router shows the destination URL before the permission check answers; assert a heading/landmark of the screen (or give its page selector an `anchor:`) so a late 403 bounce fails the case
 
 ---
 

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

@@ -18,6 +18,8 @@
  * URL, and needs no regex escaping of runtime values, which is what forced the split.
  */
 
+import { expect, type Page } from '@playwright/test';
+
 export interface UrlExpectation {
   /**
    * Anchored pathname pattern, compiled by the generator from the page selector's `value`
@@ -132,3 +134,55 @@ export function urlMatches({ pathname, declared, dataRef }: UrlExpectation): (u:
     return queryOk && hashOk;
   };
 }
+
+/**
+ * `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).
+ *
+ * `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.
+ *
+ * `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
+ * 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> } = {},
+): 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);
+
+  const started = Date.now();
+  while (Date.now() - started < settleMs) {
+    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 — `
+        + '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.',
+      );
+    }
+    await new Promise((r) => setTimeout(r, 50));
+  }
+
+  await assertUrl(matches);
+}