@pyreon/router 0.12.14 → 0.13.0

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

@@ -0,0 +1,97 @@
+import {
+  renderApiReferenceEntries,
+  renderLlmsFullSection,
+  renderLlmsTxtLine,
+} from '@pyreon/manifest'
+import routerManifest from '../manifest'
+
+describe('gen-docs — router snapshot', () => {
+  it('renders @pyreon/router to its expected llms.txt bullet', () => {
+    expect(renderLlmsTxtLine(routerManifest)).toMatchInlineSnapshot(`"- @pyreon/router — hash+history+SSR, context-based, prefetching, guards, loaders, useIsActive, View Transitions, middleware, typed search params. \`await router.push()\` resolves after \`updateCallbackDone\` (DOM commit), NOT after animation finishes. It does NOT wait for \`.finished\` (~200-300ms). \`.ready\` and \`.finished\` get empty \`.catch()\` handlers so \`AbortError: Transition was skipped\` rejections (from interrupted transitions) do not leak as unhandled promise rejections."`)
+  })
+
+  it('renders @pyreon/router to its expected llms-full.txt section — full body snapshot', () => {
+    expect(renderLlmsFullSection(routerManifest)).toMatchInlineSnapshot(`
+      "## @pyreon/router — Router
+
+      Type-safe client-side router for Pyreon with nested routes, per-route and global navigation guards, data loaders, middleware chain, View Transitions API integration, and typed search params. Context-based (\`RouterContext\`) with hash and history mode support. Route params are inferred from path strings (\`"/user/:id"\` yields \`{ id: string }\`). Named routes enable typed programmatic navigation. SSR-compatible with server-side route resolution. Hash mode uses \`history.pushState\` (not \`window.location.hash\`) to avoid double-update. \`await router.push()\` resolves after the View Transition \`updateCallbackDone\` (DOM commit), not after animation completion.
+
+      \`\`\`typescript
+      import { createRouter, RouterProvider, RouterView, RouterLink, useRouter, useRoute, useIsActive, useTypedSearchParams, useTransition, useLoaderData, useMiddlewareData } from "@pyreon/router"
+      import { mount } from "@pyreon/runtime-dom"
+
+      // Define routes with typed params, guards, loaders, and middleware
+      const router = createRouter({
+        routes: [
+          { path: "/", component: Home, name: "home" },
+          { path: "/user/:id", component: User, name: "user",
+            loader: ({ params }) => fetchUser(params.id),
+            meta: { title: "User Profile" } },
+          { path: "/admin", component: AdminLayout,
+            beforeEnter: (to, from) => isAdmin() || "/login",
+            children: [
+              { path: "users", component: AdminUsers },
+              { path: "settings", component: AdminSettings },
+            ] },
+          { path: "/settings", redirect: "/admin/settings" },
+          { path: "(.*)", component: NotFound },
+        ],
+        middleware: [authMiddleware, loggerMiddleware],
+      })
+
+      // Mount with RouterProvider
+      mount(
+        <RouterProvider router={router}>
+          <nav>
+            <RouterLink to="/" activeClass="nav-active">Home</RouterLink>
+            <RouterLink to={{ name: "user", params: { id: "42" } }}>Profile</RouterLink>
+          </nav>
+          <RouterView />
+        </RouterProvider>,
+        document.getElementById("app")!
+      )
+
+      // Inside a component — hooks
+      const User = () => {
+        const route = useRoute<"/user/:id">()
+        const data = useLoaderData<UserData>()
+        const router = useRouter()
+        const isAdmin = useIsActive("/admin")
+        const { isTransitioning } = useTransition()
+        const params = useTypedSearchParams({ tab: "string", page: "number" })
+
+        return (
+          <div>
+            <h1>{data.name} (ID: {route().params.id})</h1>
+            <Show when={isTransitioning()}>
+              <ProgressBar />
+            </Show>
+            <button onClick={() => router.push("/")}>Go Home</button>
+          </div>
+        )
+      }
+      \`\`\`
+
+      > **View Transitions — what push() awaits**: \`await router.push()\` resolves after \`updateCallbackDone\` (DOM commit), NOT after animation finishes. It does NOT wait for \`.finished\` (~200-300ms). \`.ready\` and \`.finished\` get empty \`.catch()\` handlers so \`AbortError: Transition was skipped\` rejections (from interrupted transitions) do not leak as unhandled promise rejections.
+      >
+      > **Hash mode uses pushState**: Hash mode uses \`history.pushState\` — NOT \`window.location.hash\` assignment — to avoid double-update from the hashchange event. Reading \`location.hash\` directly will not reflect router state; use \`useRoute()\` instead.
+      >
+      > **Imperative navigation in render body**: \`router.push()\` or \`navigate()\` called synchronously in the component function body causes an infinite render loop. Wrap in \`onMount\`, event handlers, \`effect\`, or any deferred execution context. The \`pyreon/no-imperative-navigate-in-render\` lint rule catches this.
+      >
+      > **Hook ordering with View Transitions**: \`afterEach\` hooks and scroll restoration fire AFTER the View Transition callback completes — not before. This means hooks see the NEW route state, which is the correct per-spec behavior but a subtle change from pre-VT versions.
+      >
+      > **For uses by, not key**: \`<For>\` in route lists uses \`by\` not \`key\`. \`<For each={routes()} key={r => r.path}>\` silently passes the key to VNode reconciliation instead of the list reconciler. Use \`by={r => r.path}\`.
+      "
+    `)
+  })
+
+  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)).toContain('router/createRouter')
+    // Spot-check the flagship API — createRouter is the factory
+    const createRouter = record['router/createRouter']!
+    expect(createRouter.notes).toContain('routes')
+    expect(createRouter.mistakes?.split('\n').length).toBeGreaterThan(2)
+  })
+})

package/src/tests/scroll.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, test } from 'vitest'
+import { ScrollManager } from '../scroll'
+
+describe('ScrollManager — LRU bound', () => {
+  test('evicts oldest entry when cap (100) is exceeded', () => {
+    const mgr = new ScrollManager('top')
+    // Fake window.scrollY for each save — happy-dom provides window.
+    Object.defineProperty(window, 'scrollY', { value: 42, configurable: true })
+    // Save 150 distinct paths.
+    for (let i = 0; i < 150; i++) mgr.save(`/path-${i}`)
+    // Oldest 50 evicted; newest 100 remain.
+    expect(mgr.getSavedPosition('/path-0')).toBeNull()
+    expect(mgr.getSavedPosition('/path-49')).toBeNull()
+    expect(mgr.getSavedPosition('/path-50')).toBe(42)
+    expect(mgr.getSavedPosition('/path-149')).toBe(42)
+  })
+
+  test('re-saving an existing path bumps it to newest (LRU, not FIFO)', () => {
+    const mgr = new ScrollManager('top')
+    Object.defineProperty(window, 'scrollY', { value: 42, configurable: true })
+    for (let i = 0; i < 100; i++) mgr.save(`/path-${i}`)
+    // Touch the oldest entry — should move to newest.
+    Object.defineProperty(window, 'scrollY', { value: 99, configurable: true })
+    mgr.save('/path-0')
+    // Now add one more to push out the new-oldest (/path-1).
+    mgr.save('/new-path')
+    expect(mgr.getSavedPosition('/path-1')).toBeNull()
+    expect(mgr.getSavedPosition('/path-0')).toBe(99)
+    expect(mgr.getSavedPosition('/new-path')).toBe(99)
+  })
+})