@pyreon/router 0.14.0 → 0.16.0

package/src/tests/loader.test.ts

@@ -1,4 +1,4 @@
-import { hydrateLoaderData, prefetchLoaderData, serializeLoaderData } from '../loader'
+import { hydrateLoaderData, prefetchLoaderData, serializeLoaderData, stringifyLoaderData } from '../loader'
 import { createRouter, setActiveRouter, useIsActive, useSearchParams } from '../router'
 import { lazy } from '../types'
 import type { RouteRecord, RouterInstance } from '../types'
@@ -130,6 +130,81 @@ describe('loader data serialization — edge cases', () => {
   })
 })
 
+// ─── M2.2 — stringifyLoaderData ────────────────────────────────────────────
+
+describe('stringifyLoaderData (M2.2)', () => {
+  // Bisect-load-bearing: revert the replacer (use bare `JSON.stringify(d).replace(/<\//g, '<\\/')`)
+  // → the function-strip + circular-error specs fail. The bare-strings-only spec
+  // would still pass since JSON.stringify also drops function values for objects.
+
+  test('strips function values silently', () => {
+    const json = stringifyLoaderData({
+      '/home': { data: 1, fn: () => {} },
+    })
+    expect(json).not.toContain('fn')
+    expect(json).toContain('"data":1')
+  })
+
+  test('strips symbol values silently', () => {
+    const json = stringifyLoaderData({
+      '/home': { data: 1, sym: Symbol('x') as unknown as string },
+    })
+    expect(json).not.toContain('sym')
+    expect(json).toContain('"data":1')
+  })
+
+  test('throws Pyreon-prefixed error on circular reference naming the offending key', () => {
+    interface Cyclic {
+      data: number
+      self?: Cyclic
+    }
+    const cyclic: Cyclic = { data: 1 }
+    cyclic.self = cyclic
+    expect(() => stringifyLoaderData({ '/posts/1': cyclic })).toThrow(/\[Pyreon\] Loader returned circular reference/)
+    // The error names the path: `/posts/1.self` (or similar).
+    expect(() => stringifyLoaderData({ '/posts/1': cyclic })).toThrow(/\/posts\/1/)
+  })
+
+  test('escapes </script> to prevent script-tag escape', () => {
+    const json = stringifyLoaderData({
+      '/home': { html: '</script><script>alert(1)' },
+    })
+    expect(json).not.toContain('</script>')
+    expect(json).toContain('<\\/script>')
+  })
+
+  test('passes plain data through unchanged', () => {
+    const json = stringifyLoaderData({
+      '/posts': [{ id: 1, title: 'A' }],
+      '/about': { count: 42 },
+    })
+    expect(JSON.parse(json)).toEqual({
+      '/posts': [{ id: 1, title: 'A' }],
+      '/about': { count: 42 },
+    })
+  })
+
+  test('handles deeply-nested data without falsely flagging shared references as cycles', () => {
+    // A non-cyclic shared reference (two keys pointing at the same array)
+    // SHOULD throw — JSON serialization can't represent shared identity
+    // without `references`, and a runtime cycle-detector treating shared
+    // refs as cycles is the safe default for hydration semantics. Verify
+    // the throw shape — if this becomes too aggressive, relax with a
+    // post-visit drop instead of WeakSet.
+    const shared = [1, 2, 3]
+    expect(() =>
+      stringifyLoaderData({
+        '/a': shared,
+        '/b': shared,
+      }),
+    ).toThrow(/circular reference/)
+  })
+
+  test('empty record produces empty object JSON', () => {
+    expect(stringifyLoaderData({})).toBe('{}')
+  })
+})
+
 // ─── useIsActive — edge cases ────────────────────────────────────────────────
 
 describe('useIsActive — edge cases', () => {
@@ -580,4 +655,254 @@ describe('router.preload', () => {
     expect(lazyLoadCalls).toBe(1)
     expect(router._componentCache.get(routes[1] as RouteRecord)).toBe(Lazy)
   })
+
+  // ─── PR C — skipLoaders option for 404 build paths ──────────────────────
+  //
+  // The SSG plugin's `__renderNotFound` opts out of loader execution
+  // when generating a static 404 page — parent-layout loaders that hit
+  // auth resources / external APIs shouldn't fire when there's no real
+  // request context to drive them. `skipLoaders: true` skips the loader
+  // step entirely while keeping the lazy-component resolution intact
+  // (so the synthetic chain still renders cleanly).
+  test('skipLoaders: true skips loader execution', async () => {
+    let calls = 0
+    const routes: RouteRecord[] = [
+      { path: '/', component: Home },
+      {
+        path: '/u/:id',
+        component: User,
+        loader: async ({ params }) => {
+          calls++
+          return { id: params.id }
+        },
+      },
+    ]
+    const router = createRouter({ routes, url: '/' }) as RouterInstance
+
+    await router.preload('/u/7', undefined, { skipLoaders: true })
+
+    expect(calls).toBe(0)
+    expect(router._loaderData.get(routes[1] as RouteRecord)).toBeUndefined()
+  })
+
+  test('skipLoaders: false (default) still runs loaders', async () => {
+    let calls = 0
+    const routes: RouteRecord[] = [
+      { path: '/', component: Home },
+      {
+        path: '/u/:id',
+        component: User,
+        loader: async () => {
+          calls++
+          return null
+        },
+      },
+    ]
+    const router = createRouter({ routes, url: '/' }) as RouterInstance
+
+    // No options arg
+    await router.preload('/u/7')
+    expect(calls).toBe(1)
+
+    // Explicit false
+    await router.preload('/u/7', undefined, { skipLoaders: false })
+    expect(calls).toBe(2)
+  })
+
+  test('skipLoaders: true still loads lazy components (preserves render readiness)', async () => {
+    // The 404 build path needs the synthetic-chain components resolved
+    // so the render pass doesn't fall back to loadingComponent. Only
+    // the data-fetching `r.loader()` calls are skipped.
+    let lazyLoadCalls = 0
+    let loaderCalls = 0
+    const Lazy = () => null
+    const routes: RouteRecord[] = [
+      { path: '/', component: Home },
+      {
+        path: '/lazy',
+        component: lazy(async () => {
+          lazyLoadCalls++
+          return Lazy
+        }),
+        loader: async () => {
+          loaderCalls++
+          return null
+        },
+      },
+    ]
+    const router = createRouter({ routes, url: '/' }) as RouterInstance
+
+    await router.preload('/lazy', undefined, { skipLoaders: true })
+
+    // Lazy component IS resolved (needed for render readiness).
+    expect(lazyLoadCalls).toBe(1)
+    expect(router._componentCache.get(routes[1] as RouteRecord)).toBe(Lazy)
+    // Loader was NOT called.
+    expect(loaderCalls).toBe(0)
+  })
+
+  test('skipLoaders: true preserves currentRoute (preload is non-navigational)', async () => {
+    const routes: RouteRecord[] = [
+      { path: '/', component: Home },
+      {
+        path: '/u/:id',
+        component: User,
+        loader: async () => null,
+      },
+    ]
+    const router = createRouter({ routes, url: '/' }) as RouterInstance
+
+    await router.preload('/u/7', undefined, { skipLoaders: true })
+
+    expect(router.currentRoute().path).toBe('/')
+  })
+})
+
+// ─── _loaderCache LRU cap (regression for missing _maxCacheSize wiring) ────
+describe('router — _loaderCache LRU cap', () => {
+  // Pre-fix: `_maxCacheSize` was wired through from `RouterOptions.maxCacheSize`
+  // (default 100) but the loader cache write paths in router.ts never read it
+  // — only `_componentCache` enforced the cap. Long-running SPAs navigating
+  // dynamic-param routes (`/posts/:id` with hundreds of unique IDs) would
+  // accumulate `_loaderCache` entries until manual `invalidateLoader()`.
+  // Post-fix: the helper `loaderCacheSet` evicts oldest (insertion-order FIFO)
+  // when over the cap, mirroring `_componentCache`.
+  test('caps _loaderCache at maxCacheSize, evicts oldest first', async () => {
+    const Page = () => null
+    const routes: RouteRecord[] = [
+      {
+        path: '/posts/:id',
+        component: Page,
+        loader: async ({ params }) => `post-${params.id}`,
+        loaderKey: ({ params }) => `posts:${params.id}`,
+      },
+    ]
+    const router = createRouter({ routes, maxCacheSize: 3, url: '/' }) as RouterInstance
+
+    // Drive the loader through 4 distinct keys
+    await router.push('/posts/1')
+    await router.push('/posts/2')
+    await router.push('/posts/3')
+    await router.push('/posts/4')
+
+    // Cache must be capped at 3 (not 4).
+    expect(router._loaderCache.size).toBe(3)
+
+    // FIFO: the OLDEST insertion (posts:1) must have been evicted.
+    expect(router._loaderCache.has('posts:1')).toBe(false)
+    expect(router._loaderCache.has('posts:2')).toBe(true)
+    expect(router._loaderCache.has('posts:3')).toBe(true)
+    expect(router._loaderCache.has('posts:4')).toBe(true)
+  })
+
+  test('does not evict when cap is not exceeded', async () => {
+    const Page = () => null
+    const routes: RouteRecord[] = [
+      {
+        path: '/posts/:id',
+        component: Page,
+        loader: async ({ params }) => `post-${params.id}`,
+        loaderKey: ({ params }) => `posts:${params.id}`,
+      },
+    ]
+    const router = createRouter({ routes, maxCacheSize: 100, url: '/' }) as RouterInstance
+
+    await router.push('/posts/1')
+    await router.push('/posts/2')
+    await router.push('/posts/3')
+
+    expect(router._loaderCache.size).toBe(3)
+    expect(router._loaderCache.has('posts:1')).toBe(true)
+    expect(router._loaderCache.has('posts:2')).toBe(true)
+    expect(router._loaderCache.has('posts:3')).toBe(true)
+  })
+
+  test('default maxCacheSize (100) caps cache after 100 unique keys', async () => {
+    const Page = () => null
+    const routes: RouteRecord[] = [
+      {
+        path: '/posts/:id',
+        component: Page,
+        loader: async ({ params }) => `post-${params.id}`,
+        loaderKey: ({ params }) => `posts:${params.id}`,
+      },
+    ]
+    // No explicit maxCacheSize — uses default 100
+    const router = createRouter({ routes, url: '/' }) as RouterInstance
+
+    for (let i = 0; i < 105; i++) {
+      await router.push(`/posts/${i}`)
+    }
+
+    expect(router._loaderCache.size).toBe(100)
+    // Earliest 5 keys (0-4) evicted.
+    expect(router._loaderCache.has('posts:0')).toBe(false)
+    expect(router._loaderCache.has('posts:4')).toBe(false)
+    expect(router._loaderCache.has('posts:5')).toBe(true)
+    expect(router._loaderCache.has('posts:104')).toBe(true)
+  })
+})
+
+// ─── Regression: dedup must not return aborted in-flight promise ───────────
+//
+// Pre-fix: `router.push` aborts `_abortController` BEFORE starting the next
+// nav. If two pushes to the same path happen back-to-back, the in-flight
+// Map still holds nav-1's promise (its `.catch` hasn't run yet). The dedup
+// returned that promise to nav-2 — but its bound signal is already aborted,
+// so nav-2's data path is broken even though it has its own fresh signal.
+//
+// Post-fix: `_loaderInflight` stores `{ promise, signal }`. Dedup is gated
+// on `!signal.aborted`. Aborted entries fall through to a fresh execute
+// using nav-2's signal.
+describe('router — _loaderInflight aborted-signal dedup', () => {
+  test('back-to-back navigation re-executes loader with fresh signal when previous was aborted', async () => {
+    let invocations = 0
+    let resolveLoader1: ((data: unknown) => void) | null = null
+
+    const Page = () => null
+    const routes: RouteRecord[] = [
+      { path: '/', component: Page },
+      {
+        path: '/data',
+        component: Page,
+        loader: async ({ signal }) => {
+          invocations++
+          const myInvocation = invocations
+          // Wire signal-abort → reject so the nav actually fails on abort.
+          // The first invocation hangs until manually resolved; later
+          // invocations resolve immediately.
+          if (myInvocation === 1) {
+            return new Promise((_resolve, reject) => {
+              signal?.addEventListener('abort', () => reject(new Error('aborted')))
+              resolveLoader1 = _resolve
+            })
+          }
+          return `data-${myInvocation}`
+        },
+      },
+    ]
+    const router = createRouter({ routes, url: '/' }) as RouterInstance
+
+    // Nav 1 → /data. Loader invocation #1 starts, hangs.
+    const nav1 = router.push('/data').catch(() => {})
+    await new Promise<void>((r) => queueMicrotask(() => r()))
+
+    // Nav 2 → /data. router.push aborts ac1 first, then calls executeLoader.
+    // Pre-fix: dedup returns nav-1's promise (whose signal is now aborted).
+    // Post-fix: dedup skipped (signal.aborted=true), fresh loader runs.
+    const nav2 = router.push('/data')
+
+    // Resolve nav-1's hung promise (won't actually deliver — already aborted)
+    const r1 = resolveLoader1 as ((d: unknown) => void) | null
+    if (r1) r1('data-1')
+
+    await nav2
+    await nav1
+
+    // Post-fix: 2 invocations (nav-1 aborted, nav-2 ran fresh).
+    // Pre-fix: 1 invocation (nav-2 deduped to nav-1's aborted promise).
+    expect(invocations).toBe(2)
+    expect(router.currentRoute().path).toBe('/data')
+  })
+
 })

package/src/tests/manifest-snapshot.test.ts

@@ -87,8 +87,12 @@ describe('gen-docs — router snapshot', () => {
 
   it('renders @pyreon/router to MCP api-reference entries — one per api[] item', () => {
     const record = renderApiReferenceEntries(routerManifest)
-    expect(Object.keys(record).length).toBe(15)
+    expect(Object.keys(record).length).toBe(18)
     expect(Object.keys(record)).toContain('router/createRouter')
+    // PR-B added redirect/isRedirectError/getRedirectInfo entries.
+    expect(Object.keys(record)).toContain('router/redirect')
+    expect(Object.keys(record)).toContain('router/isRedirectError')
+    expect(Object.keys(record)).toContain('router/getRedirectInfo')
     // Spot-check the flagship API — createRouter is the factory
     const createRouter = record['router/createRouter']!
     expect(createRouter.notes).toContain('routes')

package/src/tests/match.test.ts

@@ -8,6 +8,12 @@ import {
   resolveRoute,
   stringifyQuery,
 } from '../match'
+// Importing from components.tsx triggers the module-load side-effect that
+// registers DefaultChromeLayout with match.ts (via _setDefaultChromeLayout).
+// Without this import, the layout-less fallback in findNotFoundFallback
+// returns null because no chrome layout is registered. Tests below verify
+// the registered layout is used as the synthetic chain's first entry.
+import { DefaultChromeLayout } from '../components'
 import type { RouteRecord } from '../types'
 
 const Home = () => null
@@ -496,3 +502,281 @@ describe('parseQueryMulti — + as space', () => {
     })
   })
 })
+
+// ─── resolveRoute — notFoundComponent fallback (PR L5) ───────────────────────
+//
+// When a URL doesn't match any route AND a parent record has a
+// `notFoundComponent`, resolveRoute builds a synthetic matched chain
+// `[...ancestors, parentLayout, syntheticLeaf]` so the not-found
+// component renders INSIDE its ancestor layouts' chrome.
+
+describe('resolveRoute — notFoundComponent fallback', () => {
+  const Layout = () => null
+  const NotFoundPage = () => null
+
+  it('synthesises chain through root layout when URL is unmatched', () => {
+    const routes: RouteRecord[] = [
+      {
+        path: '/',
+        component: Layout,
+        notFoundComponent: NotFoundPage,
+        children: [
+          { path: '/', component: Home },
+          { path: '/about', component: About },
+        ],
+      },
+    ]
+
+    const r = resolveRoute('/this-does-not-exist', routes)
+    expect(r.isNotFound).toBe(true)
+    // Chain: [rootLayout, syntheticLeaf]. The synthetic leaf carries
+    // NotFoundPage as its component so the deepest RouterView resolves it.
+    expect(r.matched.length).toBe(2)
+    expect(r.matched[0]?.component).toBe(Layout)
+    expect(r.matched[1]?.component).toBe(NotFoundPage)
+    expect(r.matched[1]?.path).toBe('__pyreon_not_found_leaf__')
+  })
+
+  it('returns empty matched when no notFoundComponent anywhere', () => {
+    const routes: RouteRecord[] = [
+      { path: '/', component: Home },
+      { path: '/about', component: About },
+    ]
+
+    const r = resolveRoute('/unknown', routes)
+    expect(r.isNotFound).toBeUndefined()
+    expect(r.matched.length).toBe(0)
+  })
+
+  it('does not trigger fallback for matched routes', () => {
+    const routes: RouteRecord[] = [
+      {
+        path: '/',
+        component: Layout,
+        notFoundComponent: NotFoundPage,
+        children: [{ path: '/about', component: About }],
+      },
+    ]
+
+    const r = resolveRoute('/about', routes)
+    expect(r.isNotFound).toBeUndefined()
+    expect(r.matched).not.toContain(NotFoundPage)
+  })
+
+  it('picks the DEEPEST matching parent when nested layouts have notFoundComponent', () => {
+    const DeNotFound = () => null
+    const RootNotFound = () => null
+    const DeLayout = () => null
+    const routes: RouteRecord[] = [
+      {
+        path: '/',
+        component: Layout,
+        notFoundComponent: RootNotFound,
+        children: [
+          {
+            path: '/de',
+            component: DeLayout,
+            notFoundComponent: DeNotFound,
+            children: [{ path: '/de/about', component: About }],
+          },
+        ],
+      },
+    ]
+
+    // URL under /de prefix — should pick the DEEPER /de layout's notFound,
+    // not the root's
+    const r = resolveRoute('/de/unknown', routes)
+    expect(r.isNotFound).toBe(true)
+    expect(r.matched[r.matched.length - 1]?.component).toBe(DeNotFound)
+    // URL under root only — should fall back to root layout's notFound
+    const r2 = resolveRoute('/about-typo', routes)
+    expect(r2.isNotFound).toBe(true)
+    expect(r2.matched[r2.matched.length - 1]?.component).toBe(RootNotFound)
+  })
+
+  it('respects segment boundary in path-prefix match (no substring confusion)', () => {
+    const EnNotFound = () => null
+    const routes: RouteRecord[] = [
+      {
+        path: '/en',
+        component: Layout,
+        notFoundComponent: EnNotFound,
+        children: [],
+      },
+    ]
+
+    // `/encyclopedia` MUST NOT match `/en` as a prefix — full segment boundary required.
+    const r = resolveRoute('/encyclopedia', routes)
+    expect(r.isNotFound).toBeUndefined()
+    expect(r.matched.length).toBe(0)
+  })
+
+  it('non-matching URL under a layout prefix triggers fallback (deeper than root)', () => {
+    const routes: RouteRecord[] = [
+      {
+        path: '/admin',
+        component: Layout,
+        notFoundComponent: NotFoundPage,
+        children: [{ path: '/admin/users', component: User }],
+      },
+    ]
+
+    // `/admin/missing` doesn't match `/admin` (layout itself) OR `/admin/users`
+    // → notFoundComponent fallback applies, chain wraps the admin layout
+    const r = resolveRoute('/admin/missing', routes)
+    expect(r.isNotFound).toBe(true)
+    expect(r.matched[0]?.component).toBe(Layout)
+    expect(r.matched[r.matched.length - 1]?.component).toBe(NotFoundPage)
+  })
+
+  it('synthetic leaf has the right path marker (for runtime identification)', () => {
+    const routes: RouteRecord[] = [
+      {
+        path: '/',
+        component: Layout,
+        notFoundComponent: NotFoundPage,
+        children: [{ path: '/', component: Home }],
+      },
+    ]
+    const r = resolveRoute('/unknown', routes)
+    expect(r.matched[r.matched.length - 1]?.path).toBe('__pyreon_not_found_leaf__')
+  })
+
+  it('preserves query string on the synthetic 404 resolution', () => {
+    const routes: RouteRecord[] = [
+      {
+        path: '/',
+        component: Layout,
+        notFoundComponent: NotFoundPage,
+        children: [{ path: '/', component: Home }],
+      },
+    ]
+    const r = resolveRoute('/unknown?foo=bar', routes)
+    expect(r.isNotFound).toBe(true)
+    expect(r.query).toEqual({ foo: 'bar' })
+    expect(r.path).toBe('/unknown')
+  })
+
+  it('fires fallback via DefaultChromeLayout when the only notFoundComponent is on a page record without children', () => {
+    // PR B (layout-less app fallback): page-level `notFoundComponent` now
+    // gets wrapped in a synthetic `DefaultChromeLayout` (`<main data-
+    // pyreon-default-chrome>`) so the render pipeline produces semantic-
+    // HTML output instead of bare component markup. Pre-PR-B the resolver
+    // returned an empty chain here — the standalone-render path in the
+    // SSG plugin / runtime handler would render the component bare with
+    // no wrapping (the documented "no chrome" limitation).
+    //
+    // Tests in the `layout-less app fallback (PR B)` describe block
+    // below cover the synthetic chain shape in detail.
+    const PageOnly = () => null
+    const routes: RouteRecord[] = [
+      { path: '/', component: PageOnly, notFoundComponent: NotFoundPage },
+    ]
+    const r = resolveRoute('/unknown', routes)
+    expect(r.isNotFound).toBe(true)
+    // Synthetic chain: [DefaultChromeLayout, syntheticLeaf]
+    expect(r.matched).toHaveLength(2)
+    expect(r.matched[0]?.component).toBe(DefaultChromeLayout)
+    expect(r.matched[1]?.component).toBe(NotFoundPage)
+  })
+
+  it('does NOT fire when wildcard catch-all is configured', () => {
+    const Catchall = () => null
+    const routes: RouteRecord[] = [
+      { path: '/', component: Home, notFoundComponent: NotFoundPage },
+      { path: '(.*)', component: Catchall },
+    ]
+
+    // Wildcard catches everything first — notFoundComponent fallback never runs.
+    const r = resolveRoute('/unknown', routes)
+    expect(r.isNotFound).toBeUndefined()
+    expect(r.matched[0]?.component).toBe(Catchall)
+  })
+
+  // ─── Layout-less app fallback (PR B) ───────────────────────────────────────
+  //
+  // When the user has a page-level `notFoundComponent` (`_404.tsx` at the
+  // route root without a wrapping `_layout.tsx`), the resolver synthesizes
+  // a chain `[DefaultChromeLayout, syntheticLeaf]` so the render pipeline
+  // produces 404 HTML wrapped in `<main data-pyreon-default-chrome>`.
+  //
+  // These tests import `./components` so the setter call at the bottom of
+  // components.tsx runs and registers `DefaultChromeLayout` with match.ts.
+  // Without that import, `_defaultChromeLayout` would be null and the
+  // fallback returns null (graceful degradation to the standalone-render
+  // path). The import happens at the top of the test file via the
+  // top-level `import` chain — describe block doesn't need to do anything.
+  describe('layout-less app fallback (PR B)', () => {
+    it('synthesizes a [DefaultChromeLayout, syntheticLeaf] chain when only a page record has notFoundComponent', () => {
+      const Index = () => null
+      const NotFound = () => null
+      const routes: RouteRecord[] = [
+        { path: '/', component: Index, notFoundComponent: NotFound },
+      ]
+      const r = resolveRoute('/missing', routes)
+      expect(r.isNotFound).toBe(true)
+      // Chain shape: [synthetic chrome layout, synthetic leaf]
+      expect(r.matched).toHaveLength(2)
+      // First entry is the synthetic chrome layout (with the
+      // page's `fullPath` carried for downstream identification).
+      expect(r.matched[0]?.path).toBe('/')
+      expect(typeof r.matched[0]?.component).toBe('function')
+      // Second entry is the synthetic leaf with the user's notFoundComponent.
+      expect(r.matched[1]?.component).toBe(NotFound)
+    })
+
+    it('the synthetic chrome layout wraps the leaf in <main data-pyreon-default-chrome>', () => {
+      // Render the chain through the actual default chrome component to
+      // confirm the `<main>` wrapper materializes. The component reads
+      // RouterContext to render its inner RouterView, so we need a
+      // minimal harness — easiest path is to verify it's the DefaultChromeLayout
+      // we exported from components.tsx (identity check).
+      const NotFound = () => null
+      const routes: RouteRecord[] = [
+        { path: '/', component: () => null, notFoundComponent: NotFound },
+      ]
+      const r = resolveRoute('/missing', routes)
+      // Identity-check: the synthetic layout's component IS the registered
+      // DefaultChromeLayout. Avoids re-rendering — the runtime render path
+      // is covered by the verify-modes / e2e cells.
+      expect(r.matched[0]?.component).toBe(DefaultChromeLayout)
+    })
+
+    it('layout-with-notFoundComponent still wins over a page-level one (same urlPath)', () => {
+      // Both layout AND page have notFoundComponent. The layout-first
+      // logic from PR L5 still applies — page-level is ONLY the fallback.
+      const PageNotFound = () => null
+      const LayoutNotFound = () => null
+      const routes: RouteRecord[] = [
+        {
+          path: '/',
+          component: () => null,
+          notFoundComponent: LayoutNotFound,
+          children: [
+            { path: '/page', component: () => null, notFoundComponent: PageNotFound },
+          ],
+        },
+      ]
+      const r = resolveRoute('/missing', routes)
+      expect(r.isNotFound).toBe(true)
+      // Should pick the layout, not the page — layout has children so
+      // the layout pass matches and wins.
+      const leaf = r.matched[r.matched.length - 1]
+      expect(leaf?.component).toBe(LayoutNotFound)
+    })
+
+    it('does NOT wrap when there is a wildcard catch-all (wildcard always wins)', () => {
+      // The wildcard route matches the URL directly, so the fallback never
+      // fires. Same precedence as the existing wildcard test above.
+      const Catchall = () => null
+      const NotFound = () => null
+      const routes: RouteRecord[] = [
+        { path: '/', component: () => null, notFoundComponent: NotFound },
+        { path: '(.*)', component: Catchall },
+      ]
+      const r = resolveRoute('/missing', routes)
+      expect(r.isNotFound).toBeUndefined()
+      expect(r.matched[0]?.component).toBe(Catchall)
+    })
+  })
+})

package/src/tests/native-markers.test.ts

@@ -0,0 +1,18 @@
+import { isNativeCompat } from '@pyreon/core'
+import { describe, expect, it } from 'vitest'
+import { RouterLink, RouterProvider, RouterView } from '../components'
+
+// Marker-presence assertion (PR 3 lock-in). Bisect-verified: removing
+// any of the `nativeCompat(...)` calls in components.tsx fails the
+// corresponding test.
+describe('native-compat markers — @pyreon/router', () => {
+  it('RouterProvider is marked native', () => {
+    expect(isNativeCompat(RouterProvider)).toBe(true)
+  })
+  it('RouterView is marked native', () => {
+    expect(isNativeCompat(RouterView)).toBe(true)
+  })
+  it('RouterLink is marked native', () => {
+    expect(isNativeCompat(RouterLink)).toBe(true)
+  })
+})