Move fetch depth tracking into the store so it survives SSR hydration (#261)

A dynamic component position on a data-page parent lost its resolved
`component` moments after a server-side load of a nested child page,
collapsing the parent data page to a placeholder (admin) or nothing.

The depth-aware `path` request header requires a depth-0 resource to be
requested with the depth-0 route path, so the API can resolve the
position's `pageDataProperty` against the parent's page data. That lookup
was backed by in-memory Maps on FetchStatusManager, populated only by
`setManifestIrisByDepth`. On SSR the server built them and fetched
correctly, but the client hydrated the store while constructing a fresh
manager with empty maps — no manifest fetch runs client-side, so nothing
rebuilt them. Client-side re-fetches then fell back to `primaryFetchPath`
(the child route), whose static page has no page data, and the API
returned the position with `component: null`. Only depth-0 resources
broke: the fallback happens to be correct for depth 1.

Move the tracking into the fetcher store as `iriDepths`/`depthPaths`
(plain objects, so they serialise into the payload), derived by the
`setManifestIrisByDepth` action, with `registerIriDepth`/`resetIriDepths`
as store actions and the manager delegating. Single source of truth, so
the desync cannot recur. `registerIriDepth` is preserved intact —
deriving from `irisByDepth` alone would drop IRIs the manifest never
contained, and it was collateral here anyway (nested IRIs only register
when the parent's depth is known).

Reproduction: nested-page-hydration.spec.ts drives the real stores
through the SSR fetch, then simulates hydration with a new manager over
the same store, against a stub modelling the API's page-data resolution.
It asserts the outcome — the position still has its component — so it
fails whether the fallout is a placeholder or nothing.

Depth-tracking behaviour ported to the store's actions.spec.ts; the
manager spec now pins delegation.

Author: silverbackdan

CLAUDE.md

@@ -292,6 +292,7 @@ const { resource } = useCwaResource(pageDataIri)
 - **`resource_iris` is `NestedJsonStructure[]`** — outer array = rendering depth (root first); each depth a `{ iri, children }` tree. Flattened per-depth into `irisByDepth: string[][]` for existing consumers; raw tree retained as `resourceTree` for future placeholder rendering
 - **Manifest for both public and admin** — UUID-based manifest collapses 4+ serial round trips into one parallel batch
 - **`irisByDepth` set before batch starts** — decouples "we know depth structure" from "batch complete"
+- **Depth tracking lives in the fetcher store, never in memory** — `iriDepths` (IRI → depth) and `depthPaths` (depth → route path) are store state, derived by the `setManifestIrisByDepth` action (+ the `registerIriDepth` action for nested IRIs the manifest doesn't contain), reset per primary fetch via `resetIriDepths`. They drive the depth-aware `path` request header (`createRequestHeaders`), and **must survive the SSR→client payload**: the client builds a fresh `FetchStatusManager` and runs no manifest fetch, so in-memory Maps would start empty and every client-side re-fetch after a server-side load would fall back to `primaryFetchPath` — the *child* route. See "Bug: dynamic position loses its component after an SSR load of a nested page" below.
 - **Early-switch is depth-0 aware** — `displayFetchStatus` checks `irisByDepth[0]` root page against `currentIds`; covers first visits (wait), return visits (switch immediately), sibling nav (parent renders, child loads progressively)
 - **Route concatenation recommended, not required** — rendering never depends on URL structure
 - **Hierarchy on AbstractPage, not Route** — settable before publication (before any route exists)
@@ -451,6 +452,36 @@ Reached **71.0%** statement coverage (2026-06-28). See `### Coverage progress` a
 
 ---
 
+## Bug: dynamic position loses its `component` after an SSR load of a nested page ✅ Fixed ([#261](https://github.com/components-web-app/cwa-nuxt-module/issues/261))
+
+**Reported from:** SRNTE (a nested static page whose parent is a data page using the dynamic page template). Fixed 2026-07-16.
+
+### Symptom
+On a **server-side load/refresh** of the nested child page, the parent data page rendered correctly and then, moments later, its content vanished — leaving a component-position placeholder (admin) or nothing (logged out). Intermittent. Client-side *navigation* to the same page was unaffected.
+
+### Root cause
+The `path` request header is depth-aware (`createRequestHeaders`, `api/fetcher/fetcher.ts`): a depth-0 resource must be requested with the **depth-0 route path**, so the API resolves the position's `pageDataProperty` against the **parent's** page data (`ComponentPositionNormalizer::normalizeForPageData` → `PageDataProvider::getPageData()`, which reads the `path` header).
+
+That lookup was backed by `_iriToDepth` / `_depthPaths` — **in-memory Maps on `FetchStatusManager`**, populated only by `setManifestIrisByDepth` (a live manifest fetch, or the #257 route-cache prime). On SSR the *server* built them and fetched everything correctly; the Pinia store hydrated fine, but the **client constructed a fresh `FetchStatusManager` with empty maps and never rebuilt them** — no manifest fetch runs client-side. Any client-side re-fetch then fell back to `primaryFetchPath` = the **child** route, a static page with no page data → API returned `component: null` → the component disappeared.
+
+The client re-fetch comes from `ResourceLoader`'s `onMounted` paths: `isOutdated` (SSR data >5s old — ISR/CDN-cached), `ssrPositionHasPartialData` (admin; fires for *every* position because `usesPageTemplate` is a depth-0 global check, true whenever the parent is a data page), `refetchPublishedSsrResourceToResolveDraft` (admin), and `ssrNoDataWithSilentError`.
+
+**Not Mercure** (ruled out): Mercure only fires when a resource actually *changes*, and although `mercure.ts` does force-refetch `ComponentPosition` messages (it knows dynamic positions can't be resolved in a Mercure serialisation — the `'no_path'` branch — so it re-checks staleness itself), it saves with `isNew: true`, staging into the **temporary `new` store** awaiting merge rather than overwriting `current.byId`. It shares the same header path, so it was latent, but it is not the trigger.
+
+Only **depth-0** resources broke: the fallback path is the current route, which for a depth-1 resource is coincidentally correct — hence the *parent* data page vanishing while the nested child stayed.
+
+`registerIriDepth` was collateral: `fetcher.ts` only registers nested IRIs `if (parentDepth !== undefined)`, so with empty maps those registrations never happened either.
+
+### Fix (landed)
+Moved the depth tracking into the **fetcher store** (`iriDepths` / `depthPaths` — plain objects, so they serialise into the payload), derived by the `setManifestIrisByDepth` action; `registerIriDepth` / `resetIriDepths` are now store actions. `FetchStatusManager` delegates. Single source of truth, no SSR desync possible. `registerIriDepth` is preserved intact — deriving from `irisByDepth` alone would have dropped IRIs the manifest never contained.
+
+Reproduction + regression guard: `api/fetcher/nested-page-hydration.spec.ts` — drives the real stores through the SSR primary fetch, then simulates hydration by constructing a **new** `FetchStatusManager` over the same store, with a stubbed API that models the page-data resolution (resolves only for the `/conference` parent path). Asserts the **outcome** (the position still has its `component`), so it fails whether the fallout is a placeholder or nothing. Store behaviour moved to `storage/stores/fetcher/actions.spec.ts` ("depth tracking" describe); the manager spec's equivalent block now pins delegation.
+
+### Known related bug (NOT fixed here) — [#260](https://github.com/components-web-app/cwa-nuxt-module/issues/260)
+`ComponentPosition.vue` gates its admin-only placeholder on `v-else-if="$cwa.auth.isAdmin"` — a **nested** access to a getter returning `computed()`, which Vue does not auto-unwrap, so it's always truthy and logged-out users see the admin placeholder. (Same trap as `upload.bind` in #252; `.value` is needed.) The nameless placeholder is the tell: `pageDataProperty` is `ComponentPosition:read:role_admin`, so non-admins never receive it. A third instance of the same trap: `ResourceLoader.vue` uses bare `hasSilentError` (a `ComputedRef`) instead of `.value` inside `ssrNoDataWithSilentError`, collapsing it to `ssr && data === undefined`.
+
+---
+
 ## Bug: empty component-group `location` when adding a component to an unpublished draft ✅ Fixed
 
 **Reported from:** SRNTE (adding a component inside a static page nested in a data page). Fixed 2026-07-10.

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

@@ -226,6 +226,7 @@ describe('FetchStatusManager -> startFetch (Start a new fetch chain)', () => {
       primaryFetch: {},
       setDisplayedToken: vi.fn(),
       routeCache: new Map(),
+      resetIriDepths: vi.fn(),
     }
     const startFetchEvent: StartFetchEvent = {
       path: '/fetch-path',
@@ -770,112 +771,62 @@ describe('FetchStatusManager -> primaryFetchPath', () => {
   })
 })
 
-describe('FetchStatusManager -> depth tracking (setManifestIrisByDepth / getDepthForIri / getPathForDepth / registerIriDepth)', () => {
+describe('FetchStatusManager -> depth tracking (delegates to the fetcher store)', () => {
+  // The depth lookups themselves live in the fetcher store so they survive the SSR->client payload
+  // (see `storage/stores/fetcher/actions.spec.ts` for their behaviour, and
+  // `nested-page-hydration.spec.ts` for why). The manager's remaining job is to delegate.
   let fetchStatusManager: FetchStatusManager
 
-  // Build a depth tree node from a flat IRI list (first = root, rest = direct children); it flattens
-  // back to the same flat list the depth-tracking logic previously received directly.
   const depthNode = (iris: string[]) => ({ iri: iris[0], children: iris.slice(1).map(iri => ({ iri, children: [] })) })
 
   beforeEach(() => {
     fetchStatusManager = createFetchStatusManager()
-    fetchStatusManager._fetcherStore = { setManifestIrisByDepth: vi.fn() }
+    fetchStatusManager._fetcherStore = {
+      iriDepths: { '/_/pages/parent': 0 },
+      depthPaths: { 0: '/topic-1' },
+      setManifestIrisByDepth: vi.fn(),
+      registerIriDepth: vi.fn(),
+      resetIriDepths: vi.fn(),
+      startFetch: vi.fn(() => ({ continue: true, token: 'token', resources: [] })),
+      primaryFetch: {},
+      setDisplayedToken: vi.fn(),
+      routeCache: new Map(),
+    }
   })
 
   afterEach(() => {
     vi.clearAllMocks()
   })
 
-  test('getDepthForIri returns undefined before any manifest is set', () => {
-    expect(fetchStatusManager.getDepthForIri('/_/routes//topic-1')).toBeUndefined()
-  })
-
-  test('getPathForDepth returns undefined before any manifest is set', () => {
-    expect(fetchStatusManager.getPathForDepth(0)).toBeUndefined()
-  })
-
-  test('setManifestIrisByDepth maps every IRI in each depth group to its depth index', () => {
-    fetchStatusManager.setManifestIrisByDepth({
-      token: 'token',
-      resourceIris: [
-        depthNode(['/_/routes//topic-1', '/_/pages/parent-template', '/_/component_positions/parent-cp']),
-        depthNode(['/_/routes//topic-1/chapter-one', '/_/pages/child-template', '/_/component_positions/child-cp']),
-      ],
-    })
-    expect(fetchStatusManager.getDepthForIri('/_/routes//topic-1')).toBe(0)
-    expect(fetchStatusManager.getDepthForIri('/_/pages/parent-template')).toBe(0)
-    expect(fetchStatusManager.getDepthForIri('/_/component_positions/parent-cp')).toBe(0)
-    expect(fetchStatusManager.getDepthForIri('/_/routes//topic-1/chapter-one')).toBe(1)
-    expect(fetchStatusManager.getDepthForIri('/_/pages/child-template')).toBe(1)
-    expect(fetchStatusManager.getDepthForIri('/_/component_positions/child-cp')).toBe(1)
+  test('getDepthForIri reads the depth from the store', () => {
+    expect(fetchStatusManager.getDepthForIri('/_/pages/parent')).toBe(0)
     expect(fetchStatusManager.getDepthForIri('/unknown')).toBeUndefined()
   })
 
-  test('getPathForDepth returns the path derived from the ROUTE IRI in each depth group', () => {
-    fetchStatusManager.setManifestIrisByDepth({
-      token: 'token',
-      resourceIris: [
-        depthNode(['/_/pages/parent-template', '/_/routes//topic-1']),
-        depthNode(['/_/routes//topic-1/chapter-one', '/_/pages/child-template']),
-      ],
-    })
+  test('getPathForDepth reads the path from the store', () => {
     expect(fetchStatusManager.getPathForDepth(0)).toBe('/topic-1')
-    expect(fetchStatusManager.getPathForDepth(1)).toBe('/topic-1/chapter-one')
     expect(fetchStatusManager.getPathForDepth(2)).toBeUndefined()
   })
 
-  test('setManifestIrisByDepth replaces previous depth tracking data', () => {
-    fetchStatusManager.setManifestIrisByDepth({
-      token: 'token',
-      resourceIris: [depthNode(['/_/routes//old', '/_/pages/old-page'])],
-    })
-    fetchStatusManager.setManifestIrisByDepth({
-      token: 'token',
-      resourceIris: [depthNode(['/_/routes//new', '/_/pages/new-page'])],
-    })
-    expect(fetchStatusManager.getDepthForIri('/_/pages/old-page')).toBeUndefined()
-    expect(fetchStatusManager.getDepthForIri('/_/pages/new-page')).toBe(0)
-    expect(fetchStatusManager.getPathForDepth(0)).toBe('/new')
+  test('setManifestIrisByDepth passes the event to the store, which derives the depths', () => {
+    const event = { token: 'token', resourceIris: [depthNode(['/_/routes//topic-1', '/_/pages/parent'])] }
+    fetchStatusManager.setManifestIrisByDepth(event)
+    expect(fetchStatusManager._fetcherStore.setManifestIrisByDepth).toHaveBeenCalledWith(event)
   })
 
-  test('registerIriDepth adds an IRI to the depth map', () => {
+  test('registerIriDepth passes the IRI and depth to the store', () => {
     fetchStatusManager.registerIriDepth('/component/some-uuid', 0)
-    expect(fetchStatusManager.getDepthForIri('/component/some-uuid')).toBe(0)
+    expect(fetchStatusManager._fetcherStore.registerIriDepth).toHaveBeenCalledWith({ iri: '/component/some-uuid', depth: 0 })
   })
 
   test('startFetch with isPrimary clears depth tracking', () => {
-    fetchStatusManager._fetcherStore = {
-      setManifestIrisByDepth: vi.fn(),
-      startFetch: vi.fn(() => ({ continue: true, token: 'token', resources: [] })),
-      primaryFetch: {},
-      setDisplayedToken: vi.fn(),
-      routeCache: new Map(),
-    }
-    fetchStatusManager.setManifestIrisByDepth({
-      token: 'token',
-      resourceIris: [depthNode(['/_/routes//topic-1', '/_/pages/parent'])],
-    })
-    expect(fetchStatusManager.getDepthForIri('/_/pages/parent')).toBe(0)
-
     fetchStatusManager.startFetch({ path: '/new', isPrimary: true })
-
-    expect(fetchStatusManager.getDepthForIri('/_/pages/parent')).toBeUndefined()
-    expect(fetchStatusManager.getPathForDepth(0)).toBeUndefined()
+    expect(fetchStatusManager._fetcherStore.resetIriDepths).toHaveBeenCalled()
   })
 
   test('startFetch without isPrimary preserves depth tracking', () => {
-    fetchStatusManager._fetcherStore = {
-      setManifestIrisByDepth: vi.fn(),
-      startFetch: vi.fn(() => ({ continue: true, token: 'token', resources: [] })),
-    }
-    fetchStatusManager.setManifestIrisByDepth({
-      token: 'token',
-      resourceIris: [depthNode(['/_/routes//topic-1', '/_/pages/parent'])],
-    })
     fetchStatusManager.startFetch({ path: '/new', isPrimary: false })
-
-    expect(fetchStatusManager.getDepthForIri('/_/pages/parent')).toBe(0)
-    expect(fetchStatusManager.getPathForDepth(0)).toBe('/topic-1')
+    expect(fetchStatusManager._fetcherStore.resetIriDepths).not.toHaveBeenCalled()
   })
 })
 

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

@@ -16,12 +16,11 @@ import { FinishFetchManifestType } from '../../storage/stores/fetcher/actions'
 import type { CwaResourcesStoreInterface, ResourcesStore } from '../../storage/stores/resources/resources-store'
 import type { CwaResourceError } from '../../errors/cwa-resource-error'
 import { createCwaResourceError } from '../../errors/cwa-resource-error'
-import { CwaResourceTypes, getResourceTypeFromIri, isCwaResource, ResourceTypeFromIri } from '../../resources/resource-utils'
+import { CwaResourceTypes, getResourceTypeFromIri, isCwaResource } from '../../resources/resource-utils'
 import type { CwaResource } from '../../resources/resource-utils'
 import { CwaResourceApiStatuses } from '../../storage/stores/resources/state'
 import type { CwaFetchRequestHeaders, CwaFetchResponse } from './fetcher'
 import type { FetchAbortReason, FetchStatus, RouteCacheEntry } from '#cwa/storage/stores/fetcher/state'
-import { flattenManifestNode } from '#cwa/storage/stores/fetcher/manifest-utils'
 import { clearError, useError } from '#imports'
 
 export interface FinishFetchResourceEvent {
@@ -55,8 +54,6 @@ export default class FetchStatusManager {
   private readonly _fetcherStore: CwaFetcherStoreInterface
   private readonly _resourcesStore: CwaResourcesStoreInterface
 
-  private _iriToDepth = new Map<string, number>()
-  private _depthPaths = new Map<number, string>()
   // Max routes retained in the instant-revisit cache (#257). Overridable via the `cwa` nuxt config.
   private readonly routeCacheLimit: number
 
@@ -107,8 +104,7 @@ export default class FetchStatusManager {
     // capture the page currently being loaded before it is superseded by this new primary fetch
     const outgoingFetchingToken = event.isPrimary ? this.fetcherStore.primaryFetch.fetchingToken : undefined
     if (event.isPrimary) {
-      this._iriToDepth = new Map()
-      this._depthPaths = new Map()
+      this.fetcherStore.resetIriDepths()
     }
     const startFetchStatus = this.fetcherStore.startFetch({ ...event, isCurrentSuccessResourcesResolved: this.isCurrentSuccessResourcesResolved })
     if (event.isPrimary) {
@@ -380,32 +376,20 @@ export default class FetchStatusManager {
   }
 
   public setManifestIrisByDepth(event: SetManifestIrisByDepthEvent): void {
-    this._iriToDepth = new Map()
-    this._depthPaths = new Map()
-    const prefix = ResourceTypeFromIri.getPathPrefix() || ''
-    const routePathPrefix = `${prefix}/_/routes/`
-    const irisByDepth = event.resourceIris.map(flattenManifestNode)
-    for (let depth = 0; depth < irisByDepth.length; depth++) {
-      for (const iri of irisByDepth[depth]!) {
-        this._iriToDepth.set(iri, depth)
-        if (!this._depthPaths.has(depth) && iri.startsWith(routePathPrefix)) {
-          this._depthPaths.set(depth, iri.substring(routePathPrefix.length))
-        }
-      }
-    }
+    // the store derives the depth lookups from the manifest as it stores it
     this.fetcherStore.setManifestIrisByDepth(event)
   }
 
   public getDepthForIri(iri: string): number | undefined {
-    return this._iriToDepth.get(iri)
+    return this.fetcherStore.iriDepths[iri]
   }
 
   public getPathForDepth(depth: number): string | undefined {
-    return this._depthPaths.get(depth)
+    return this.fetcherStore.depthPaths[depth]
   }
 
   public registerIriDepth(iri: string, depth: number): void {
-    this._iriToDepth.set(iri, depth)
+    this.fetcherStore.registerIriDepth({ iri, depth })
   }
 
   public finishManifestFetch(event: ManifestSuccessFetchEvent | ManifestErrorFetchEvent): void {

src/runtime/api/fetcher/fetcher.ts

@@ -188,7 +188,7 @@ export default class Fetcher {
     }
     else if (resource && shallowFetch !== true) {
       // Wait for the manifest batch to complete before traversing associated resources.
-      // This ensures _iriToDepth and _depthPaths are populated so createRequestHeaders
+      // This ensures the store's depth tracking is populated so createRequestHeaders
       // sends the correct depth-aware path for every follow-up request. fetchAssociatedResources
       // still runs as a safety pass for anything the manifest did not include.
       if (manifestPromise) {