fix: only hold fully-loaded pages + reset all primary tokens on clear (#256)

Two conservative follow-ups to the displayedToken anti-flash work:

- fetchHasDisplayablePage now requires EVERY manifest depth to have page data
  before a fetch can be held as the displayed page. The depth-0-only check
  wrongly held a half-loaded nested page (shared parent loaded, child still
  loading) when clicking away, leaving the user on a parent + spinning child
  instead of the last fully-loaded page.
- clearPrimaryFetch resets fetchingToken and displayedToken too, not just
  successToken, so abandoning a primary fetch can't leave a stale displayed
  reference.

Adds a nested-child-then-home reproduction and a clearPrimaryFetch unit test.

Note: an OPEN rapid nested-navigation regression remains (new route's fetch
not superseding the in-flight one) — not reproducible headlessly, tracked in
CLAUDE.md #256 for follow-up.

Author: silverbackdan

CLAUDE.md

@@ -367,7 +367,14 @@ Consuming-app **unscoped** global element CSS (`h1/h2/h3`, `a`, `button`, …) r
 **[#157](https://github.com/components-web-app/cwa-nuxt-module/issues/157) — Clone a resource**
 Admin UI functionality to duplicate an existing resource (page, component, etc.).
 
-**[#256](https://github.com/components-web-app/cwa-nuxt-module/issues/256) — Bug (regression): navigation reverts to a stale (last *fully-loaded*) page instead of holding the page on screen** ✅ Fixed (dev)
+**[#256](https://github.com/components-web-app/cwa-nuxt-module/issues/256) — Bug (regression): navigation reverts to a stale (last *fully-loaded*) page instead of holding the page on screen** ⚠️ Partially fixed — OPEN nested-nav regression (see "Follow-up" below)
+
+> **⚠️ CURRENT STATE (2026-07-09, end of session — RESUME HERE):** The `displayedToken` fix below is **deployed to edge** (`@cwa/nuxt-edge`). After deploying, Daniel found a **cluster of rapid nested-navigation regressions** that are NOT yet fixed and could NOT be reproduced headlessly (timing/lag-dependent — prod only):
+> - Switching to a nested page, then clicking a **CWA static home page** before the nested loaded → **`fetchRoute('/_/routes//')` is never called** (no HTTP), the URL changes to home, but the in-flight nested fetch (still the fetching token, never superseded) **fully loads and keeps rendering** — home never shows.
+> - Switching between two **never-before-loaded nested siblings** (same data-page parent) before the first loads → **neither loads / no sub-page renders**.
+> - Confirmed by Daniel: the last fully-resolved success was a **sibling nested page, NOT home**, so this is NOT the same-path short-circuit. The new route's fetch simply isn't taking over the in-flight one.
+> **Leading theory:** rapid-nav supersession in the fetcher/middleware (`route-middleware.ts` fire-and-forget `fetchRoute(to).then(...)` + `startFetch` not aborting the previous in-flight primary for a *different* path, so it stays `fetchingToken`, completes, and wins). Possibly pre-existing / exposed by #250 manifest migration, possibly worsened by the `displayedToken` hold. **Decision pending (Daniel, tomorrow):** (a) revert the #256 `displayedToken` change on dev to isolate whether it caused the nested regression, (b) add dev/console logging to `fetchRoute`/`startFetch`/`finishFetch`/`displayFetchStatus` to capture the real prod sequence, or (c) build the #246 recorded-API replay harness (the only way to deterministically catch this class). I recommended (a) first to isolate.
+> **Pushed this session (the safe, tested fixes only):** `fetchHasDisplayablePage` now requires **ALL depths** to have page data before a fetch can be held (was depth-0-only, which wrongly held a half-loaded nested page — parent + spinning child — when clicking away); `clearPrimaryFetch` now resets **all three** primary tokens (was successToken-only). Repro/guards in `navigation-retention.spec.ts`. The risky nested-nav orchestration fix was NOT attempted — awaiting Daniel's decision.
 
 **Root cause (confirmed).** Not a data-drop — a headless store+gate audit (`src/runtime/resources/navigation-retention.spec.ts`) proved data is retained through `IN_PROGRESS` at every gate and the token machinery holds the old page. The real bug: the anti-flash **hold** (`displayFetchStatus` fallback) read `resolvedSuccessFetchStatus` = the **last fully-resolved success token**, which only advances in `finishFetch` when the fetch completes **before the user navigates again** (client nav is fire-and-forget — `route-middleware.ts:104`). So clicking faster than a page loads leaves the success token frozen several navs back; the hold then surfaces that stale page (home / a different conference / "a page from a few clicks ago") while the new page loads. Arriving via a redirect (SRNTE "Next Conference") is one way to strand it. Intermittent = timing-dependent.
 

src/runtime/api/fetcher/fetch-status-manager.spec.ts

@@ -236,6 +236,28 @@ describe('FetchStatusManager -> startFetch (Start a new fetch chain)', () => {
   })
 })
 
+describe('FetchStatusManager -> clearPrimaryFetch', () => {
+  let fetchStatusManager: FetchStatusManager
+
+  beforeEach(() => {
+    fetchStatusManager = createFetchStatusManager()
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  test('resets the fetching, success and displayed tokens', () => {
+    fetchStatusManager._fetcherStore = {
+      primaryFetch: { fetchingToken: 'f', successToken: 's', displayedToken: 'd' },
+    }
+    fetchStatusManager.clearPrimaryFetch()
+    expect(fetchStatusManager._fetcherStore.primaryFetch.fetchingToken).toBeUndefined()
+    expect(fetchStatusManager._fetcherStore.primaryFetch.successToken).toBeUndefined()
+    expect(fetchStatusManager._fetcherStore.primaryFetch.displayedToken).toBeUndefined()
+  })
+})
+
 describe('FetchStatusManager -> startFetchResource', () => {
   let fetchStatusManager: FetchStatusManager
 

src/runtime/api/fetcher/fetch-status-manager.ts

@@ -121,14 +121,19 @@ export default class FetchStatusManager {
     return startFetchStatus
   }
 
-  // Whether a fetch's depth-0 page resource has data in the store — i.e. it was actually rendered.
+  // Whether a fetch was fully rendered — EVERY depth's page resource has data in the store. A
+  // partially-loaded nested view (e.g. the shared parent at depth 0 loaded but the child at depth 1
+  // still loading) must NOT be held as the displayed page, or clicking away leaves the user stuck on
+  // a parent + spinning child instead of falling back to the last fully-loaded page. See #256.
   private fetchHasDisplayablePage(token: string): boolean {
-    const depth0 = this.fetcherStore.fetches[token]?.manifest?.irisByDepth?.[0]
-    if (!depth0) {
+    const irisByDepth = this.fetcherStore.fetches[token]?.manifest?.irisByDepth
+    if (!irisByDepth?.length) {
       return false
     }
-    const pageIri = depth0.find(iri => getResourceTypeFromIri(iri) === CwaResourceTypes.PAGE)
-    return !!(pageIri && this.resourcesStore.current.byId?.[pageIri]?.data)
+    return irisByDepth.every((depthGroup) => {
+      const pageIri = depthGroup.find(iri => getResourceTypeFromIri(iri) === CwaResourceTypes.PAGE)
+      return !!(pageIri && this.resourcesStore.current.byId?.[pageIri]?.data)
+    })
   }
 
   public startFetchResource(event: AddFetchResourceEvent): boolean {
@@ -316,7 +321,12 @@ export default class FetchStatusManager {
 
   // todo: test
   public clearPrimaryFetch() {
+    // Reset the whole primary-fetch state. Previously only successToken was cleared, leaving a stale
+    // fetchingToken/displayedToken pointing at an abandoned fetch (e.g. navigating to a cwa-disabled
+    // page while a CWA fetch was in flight), which could keep the CWA view stuck. See #256.
     this.fetcherStore.primaryFetch.successToken = undefined
+    this.fetcherStore.primaryFetch.fetchingToken = undefined
+    this.fetcherStore.primaryFetch.displayedToken = undefined
   }
 
   public get primaryFetchPath(): string | undefined {

src/runtime/resources/navigation-retention.spec.ts

@@ -116,6 +116,18 @@ function fullyLoad(page: ReturnType<typeof buildPage>): string {
   return token
 }
 
+// Fully load an arbitrary (possibly multi-depth) view from an explicit tree + resource list.
+function fullyLoadView(routeIri: string, tree: NestedJsonStructure[], resourceList: CwaResource[]): string {
+  const token = startPrimary(routeIri, `${routeIri}/manifest`)
+  deliverManifest(token, tree)
+  for (const resource of resourceList) {
+    beginResource(token, resource['@id'])
+    resolveResource(resource)
+  }
+  fetcherStore.finishFetch({ token })
+  return token
+}
+
 // ---- the invariant assertion ----------------------------------------------
 
 function displayFetchStatus() {
@@ -217,6 +229,53 @@ describe('#256 navigation retention', () => {
     expect(fetcherStore.primaryFetch.displayedToken).toBe(fetcherStore.primaryFetch.successToken)
   })
 
+  test('clicking away (to home) while a nested child is still loading does NOT get stuck holding the half-loaded nested page', () => {
+    const parent = buildPage('parent')
+    const overview = buildPage('overview')
+    const child2 = buildPage('child2')
+    const home = buildPage('home')
+
+    const overviewNested: NestedJsonStructure[] = [parent.tree[0], overview.tree[0]]
+    const child2Nested: NestedJsonStructure[] = [parent.tree[0], child2.tree[0]]
+
+    // 1. On the nested overview page, fully loaded (depth-0 parent + depth-1 overview).
+    fullyLoadView(overview.routeIri, overviewNested, [...parent.resourcesList, ...overview.resourcesList])
+    expect(resources.pageIriAtDepth(0).value).toBe(parent.pageIri)
+    expect(resources.pageIriAtDepth(1).value).toBe(overview.pageIri)
+
+    // 2. Navigate to sibling nested page child2 — parent early-switches back in, but child2's depth-1
+    //    page NEVER loads and the fetch is NOT finished (the user clicks away first).
+    const tokenChild2 = startPrimary(child2.routeIri, `${child2.routeIri}/manifest`)
+    deliverManifest(tokenChild2, child2Nested)
+    for (const resource of parent.resourcesList) {
+      beginResource(tokenChild2, resource['@id'])
+      resolveResource(resource)
+    }
+    // child2's own depth-1 resources are deliberately NOT loaded
+
+    // 3. Navigate to home before child2 finished.
+    const tokenHome = startPrimary(home.routeIri, `${home.routeIri}/manifest`)
+
+    // The held view must not be a half-loaded nested page whose depth-1 child has no data —
+    // that renders parent + a stuck child spinner. It should hold a fully-loaded page instead.
+    const heldDepth1 = resources.pageIriAtDepth(1).value
+    if (heldDepth1) {
+      expect(
+        resources.getResource(heldDepth1).value?.data,
+        'held view depth-1 must have data (not a half-loaded nested page)',
+      ).toBeTruthy()
+    }
+
+    // 4. Home finishes and must take over the display.
+    deliverManifest(tokenHome, home.tree)
+    for (const resource of home.resourcesList) {
+      beginResource(tokenHome, resource['@id'])
+      resolveResource(resource)
+    }
+    fetcherStore.finishFetch({ token: tokenHome })
+    expect(resources.pageIriAtDepth(0).value).toBe(home.pageIri)
+  })
+
   test('navigating to a nested child never blanks the shared parent (depth 0)', () => {
     // Parent page P, displayed at depth 0.
     const p = buildPage('parent')