Add route meta and afterNavigate hook

Expose per-route meta by adding meta to Route and RouteContext, and add an afterNavigate option to Router. Router now passes route.meta into the render context and invokes options.afterNavigate after render completes and subscribers are notified. Included tests for meta presence/absence and for afterNavigate behavior (including that it does not fire on no-match or loader errors). Updated TODO.md to mark these items complete.

Author: bradpotts

TODO.md

@@ -73,15 +73,15 @@ on top of it. Focus is on exposing router state reactively and supporting real a
 
 ### P1: Application Primitives
 
-- [ ] **Per-route metadata support**
+- [x] **Per-route metadata support**
   - Files: `src/index.ts`, `tests/router.test.ts`, `README.md`
   - Acceptance: optional `meta` object on route definitions (typed but open-ended);
     `RouteContext` exposes `meta` so page modules and app code can read title, guard data,
     analytics keys, etc.
   - Why: real apps need document title management, analytics tagging, and route-level
     data that does not belong in the page module itself
 
-- [ ] **`afterNavigate` hook**
+- [x] **`afterNavigate` hook**
   - Files: `src/index.ts`, `tests/router.test.ts`, `README.md`
   - Acceptance: optional `afterNavigate(context)` on constructor options; fires after
     render completes; complements `beforeNavigate` for analytics, focus management, etc.

src/index.ts

@@ -8,11 +8,13 @@ export type RouteContext = {
   params: Record<string, string>
   query: URLSearchParams
   root: HTMLElement
+  meta?: Record<string, unknown>
 }
 
 export type Route = {
   path: string
   name?: string
+  meta?: Record<string, unknown>
   loader: () => Promise<PageModule>
 }
 
@@ -30,6 +32,7 @@ export type RouterOptions = {
   ) => void | Promise<void>
   onNavigationStart?: (context: NavigationContext) => void
   onNavigationEnd?: (context: NavigationContext) => void
+  afterNavigate?: (context: RouteContext) => void
 }
 
 export type Unsubscribe = () => void
@@ -264,10 +267,12 @@ export class Router {
         params,
         query,
         root: this.rootEl,
+        meta: route.meta,
       }
 
       page.render(context)
       this.notifySubscribers(context)
+      this.options.afterNavigate?.(context)
 
       if (this.scrollRestoration) {
         if (source === 'pop') {

tests/router.test.ts

@@ -717,4 +717,98 @@ describe("spectre-shell-router", () => {
       router.destroy()
     })
   })
+
+  describe("route meta", () => {
+    it("exposes a route's meta object on the route context", async () => {
+      const { Router } = await import("../src/index")
+      const render = vi.fn()
+      const routes = [
+        { path: "/", meta: { title: "Home" }, loader: async () => ({ render: vi.fn() }) },
+        { path: "/users/:id", meta: { title: "User", requiresAuth: true }, loader: async () => ({ render }) },
+      ]
+      const root = document.createElement("div")
+      window.history.replaceState({}, "", "/")
+
+      const router = new Router(routes, root)
+      await tick()
+
+      router.navigate("/users/42")
+      await tick()
+
+      const ctx = render.mock.calls.at(-1)?.[0]
+      expect(ctx?.meta).toEqual({ title: "User", requiresAuth: true })
+      router.destroy()
+    })
+
+    it("leaves meta undefined for routes without a meta object", async () => {
+      const { Router } = await import("../src/index")
+      const render = vi.fn()
+      const routes = [{ path: "/", loader: async () => ({ render }) }]
+      const root = document.createElement("div")
+      window.history.replaceState({}, "", "/")
+
+      const router = new Router(routes, root)
+      await tick()
+
+      const ctx = render.mock.calls.at(-1)?.[0]
+      expect(ctx?.meta).toBeUndefined()
+      router.destroy()
+    })
+  })
+
+  describe("afterNavigate hook", () => {
+    it("fires with the route context after render completes", async () => {
+      const { Router } = await import("../src/index")
+      const afterNavigate = vi.fn()
+      const routes = [
+        { path: "/", meta: { title: "Home" }, loader: async () => ({ render: vi.fn() }) },
+        { path: "/users/:id", loader: async () => ({ render: vi.fn() }) },
+      ]
+      const root = document.createElement("div")
+      window.history.replaceState({}, "", "/")
+
+      const router = new Router(routes, root, { afterNavigate })
+      await tick()
+
+      expect(afterNavigate).toHaveBeenCalledOnce()
+      let ctx = afterNavigate.mock.calls.at(-1)?.[0]
+      expect(ctx?.path).toBe("/")
+      expect(ctx?.meta).toEqual({ title: "Home" })
+
+      afterNavigate.mockClear()
+      router.navigate("/users/42?tab=info")
+      await tick()
+
+      expect(afterNavigate).toHaveBeenCalledOnce()
+      ctx = afterNavigate.mock.calls.at(-1)?.[0]
+      expect(ctx?.path).toBe("/users/42")
+      expect(ctx?.params.id).toBe("42")
+      expect(ctx?.query.get("tab")).toBe("info")
+      router.destroy()
+    })
+
+    it("does not fire when no route matches or the loader throws", async () => {
+      const { Router } = await import("../src/index")
+      const afterNavigate = vi.fn()
+      const routes = [
+        { path: "/", loader: async () => ({ render: vi.fn() }) },
+        { path: "/broken", loader: async () => { throw new Error("boom") } },
+      ]
+      const root = document.createElement("div")
+      window.history.replaceState({}, "", "/")
+
+      const router = new Router(routes, root, { afterNavigate })
+      await tick()
+      afterNavigate.mockClear()
+
+      router.navigate("/missing")
+      await tick()
+      expect(afterNavigate).not.toHaveBeenCalled()
+
+      router.navigate("/broken")
+      await tick()
+      expect(afterNavigate).not.toHaveBeenCalled()
+      router.destroy()
+    })
+  })
 })