Add error routes and history helpers

Adds `errorRoute` and `onError` router options, plus `replace()`, `back()`, and `forward()` navigation helpers. Updates tests to cover loader failures, unmatched routes, and History API behavior, and marks the Phase 4 TODO items complete.

Author: bradpotts

TODO.md

@@ -52,7 +52,7 @@ All Phase 2 items were delivered. The routing contract is stable and complete.
 ## Phase 3 — Ecosystem Integration: P0/P1/P3 Complete — Phase 4 Unblocked
 
 P0, P1, and P3 (API docs) delivered. P2 (nested routing) remains evaluation-only.
-Phase 4 (error routes, history helpers) can now begin.
+Phase 4 error routes and history helpers are now implemented — see Phase 4 below.
 
 ### P0: Signals Bridge
 
@@ -99,7 +99,7 @@ Phase 6 templates can scaffold these patterns using the documented examples.
 
 Unblocked:
 
-- This repo: Phase 4 can start (error routes, history helpers)
+- This repo: Phase 4 P0/P1 delivered (error routes, history helpers)
 - `spectre-init`: Phase 6 template modernization (lifecycle, title, loading, plugin)
 - `spectre-shell`: P2.5 release readiness (templates need stable examples first)
 
@@ -132,37 +132,37 @@ Unblocked:
 
 ---
 
-## Phase 4 — Production Readiness: Active
+## Phase 4 — Production Readiness: P0/P1 Complete — README/CHANGELOG Pending (Codex)
 
-Phase 3 core APIs are delivered. Phase 4 closes remaining production gaps: deterministic error
-handling, navigation history helpers, and nested outlet support when a concrete need is proven.
+Error routes and navigation history helpers are implemented and tested. Nested outlet
+support (P2) remains evaluation-only until a concrete need is proven.
 
 ### P0: Error Routes
 
-- [ ] **`errorRoute` option on `RouterOptions`**
-  - Files: `src/index.ts`, `tests/reliability.test.ts`, `README.md`
+- [x] **`errorRoute` option on `RouterOptions`**
+  - Files: `src/index.ts`, `tests/reliability.test.ts` — `README.md` still needed (Codex)
   - Acceptance: when a loader throws or no route matches, the router navigates to `errorRoute`
     rather than silently clearing the outlet; `errorRoute` path must exist in the route list
   - Why: silent root-clearing gives users a blank page with no feedback; named error routes
     make failure states explicit and testable
 
-- [ ] **`onError(error, context)` callback**
+- [x] **`onError(error, context)` callback**
   - Files: `src/index.ts`, `tests/reliability.test.ts`
   - Acceptance: optional callback on constructor options; fires when a loader throws;
     apps can log, report, or handle programmatically without requiring a redirect
   - Why: not all error handling is a redirect — apps need a seam for error telemetry
 
 ### P1: Navigation History Helpers
 
-- [ ] **`router.back()` and `router.forward()`**
+- [x] **`router.back()` and `router.forward()`**
   - Files: `src/index.ts`, `tests/router.test.ts`
   - Acceptance: thin wrappers around `history.back()` and `history.forward()`; consistent
     with the existing `navigate()` contract
   - Why: exposes common navigation actions as first-class router methods so callers do not
     reach around the router to the History API directly
 
-- [ ] **`router.replace(path)`**
-  - Files: `src/index.ts`, `tests/router.test.ts`, `README.md`
+- [x] **`router.replace(path)`**
+  - Files: `src/index.ts`, `tests/router.test.ts` — `README.md` still needed (Codex)
   - Acceptance: navigates to `path` without adding a new history entry (`replaceState`);
     race-condition guard applies as with `navigate()`
   - Why: redirect flows (post-login, form submission) need replace-not-push semantics
@@ -185,9 +185,10 @@ handling, navigation history helpers, and nested outlet support when a concrete
 3. ~~Per-route metadata~~ ✓
 4. ~~`afterNavigate` hook~~ ✓
 5. ~~Phase 3 P3 API docs~~ ✓
-6. **Error routes** ← current — Phase 4 P0
-7. Navigation history helpers — Phase 4 P1 (back/forward/replace)
-8. Nested routing — only when a concrete application need is proven
+6. ~~Error routes~~ ✓ — Phase 4 P0
+7. ~~Navigation history helpers~~ ✓ — Phase 4 P1 (back/forward/replace)
+8. **README/CHANGELOG updates for Phase 4 P0/P1** ← current (Codex)
+9. Nested routing — only when a concrete application need is proven
 
 ---
 
@@ -217,8 +218,8 @@ they are stable and covered in README examples so spectre-init can reference the
 
 ### P2: Error Routes — Needed for Phase 6 template hardening
 
-- [ ] `errorRoute` option on `RouterOptions` (Phase 4 P0) — when shipped, spectre-init shell-app template should add an error route
-- [ ] `onError(error, context)` callback — when shipped, document the pattern for template consumers
+- [x] `errorRoute` option on `RouterOptions` (Phase 4 P0) — implemented; spectre-init shell-app template can now add an error route
+- [x] `onError(error, context)` callback — implemented; document the pattern for template consumers once README lands
 
 ## Explicitly Out of Scope
 

src/index.ts

@@ -26,13 +26,15 @@ export type NavigationContext = {
 export type RouterOptions = {
   mode?: 'history' | 'hash'
   scrollRestoration?: boolean
+  errorRoute?: string
   beforeNavigate?: (
     context: NavigationContext,
     next: (redirect?: string) => void,
   ) => void | Promise<void>
   onNavigationStart?: (context: NavigationContext) => void
   onNavigationEnd?: (context: NavigationContext) => void
   afterNavigate?: (context: RouteContext) => void
+  onError?: (error: unknown, context: NavigationContext) => void
 }
 
 export type Unsubscribe = () => void
@@ -62,6 +64,12 @@ export class Router {
     for (const route of routes) {
       if (route.name) this.nameIndex.set(route.name, route.path)
     }
+    if (
+      options.errorRoute !== undefined &&
+      !routes.some((route) => route.path === options.errorRoute)
+    ) {
+      throw new Error(`errorRoute "${options.errorRoute}" does not match any route path.`)
+    }
     this.handleNavigationBound = () => { void this.handleNavigation('pop') }
     this.handleHashChangeBound = this.handleHashChange.bind(this)
     this.handleLinkClickBound = this.handleLinkClick.bind(this)
@@ -86,6 +94,25 @@ export class Router {
     void this.handleNavigation('push')
   }
 
+  public replace(path: string) {
+    if (!this.rootEl) {
+      throw new Error('Router has been destroyed or not initialized.')
+    }
+    if (this.scrollRestoration) {
+      history.replaceState({ ...history.state, scrollY: window.scrollY }, '')
+    }
+    history.replaceState({}, '', this.mode === 'hash' ? `#${path}` : path)
+    void this.handleNavigation('push')
+  }
+
+  public back() {
+    history.back()
+  }
+
+  public forward() {
+    history.forward()
+  }
+
   public subscribe(callback: (context: RouteContext) => void): Unsubscribe {
     this.subscribers.add(callback)
     return () => {
@@ -246,9 +273,12 @@ export class Router {
       let page: PageModule
       try {
         page = await route.loader()
-      } catch {
-        // Loader failure: abandon this navigation and clear stale content.
-        if (navId === this.currentNavId && this.rootEl) {
+      } catch (error) {
+        if (navId !== this.currentNavId || !this.rootEl) return
+        this.options.onError?.(error, navContext)
+        if (this.options.errorRoute !== undefined && path !== this.options.errorRoute) {
+          this.replace(this.options.errorRoute)
+        } else {
           this.destroyCurrentPage()
           this.rootEl.innerHTML = ''
         }
@@ -286,6 +316,12 @@ export class Router {
       return
     }
 
+    if (this.options.errorRoute !== undefined && path !== this.options.errorRoute) {
+      this.options.onError?.(new Error(`No route matches "${path}".`), navContext)
+      this.replace(this.options.errorRoute)
+      return
+    }
+
     this.destroyCurrentPage()
     this.rootEl.innerHTML = ''
     this.currentPath = path

tests/reliability.test.ts

@@ -114,4 +114,97 @@ describe("Router Reliability Tests", () => {
     expect(renderCalls).toEqual(["3"])
     router.destroy()
   })
+
+  it("navigates to errorRoute when a loader throws", async () => {
+    const { Router } = await import("../src/index")
+    const onError = vi.fn()
+
+    const routes = [
+      {
+        path: "/fail",
+        loader: async (): Promise<never> => { throw new Error("Load failed") }
+      },
+      {
+        path: "/error",
+        loader: async () => ({ render: (ctx) => { ctx.root.innerHTML = "Error" } })
+      },
+      {
+        path: "/",
+        loader: async () => ({ render: (ctx) => { ctx.root.innerHTML = "Home" } })
+      }
+    ]
+
+    const root = document.createElement("div")
+    const router = new Router(routes, root, { errorRoute: "/error", onError })
+    await tick()
+
+    router.navigate("/fail")
+    await tick()
+
+    expect(root.innerHTML).toBe("Error")
+    expect(onError).toHaveBeenCalledTimes(1)
+    expect(onError.mock.calls[0][1]).toEqual({ from: "/", to: "/fail" })
+
+    router.destroy()
+  })
+
+  it("navigates to errorRoute when no route matches", async () => {
+    const { Router } = await import("../src/index")
+    const onError = vi.fn()
+
+    const routes = [
+      {
+        path: "/error",
+        loader: async () => ({ render: (ctx) => { ctx.root.innerHTML = "Error" } })
+      },
+      {
+        path: "/",
+        loader: async () => ({ render: (ctx) => { ctx.root.innerHTML = "Home" } })
+      }
+    ]
+
+    const root = document.createElement("div")
+    const router = new Router(routes, root, { errorRoute: "/error", onError })
+    await tick()
+
+    router.navigate("/does-not-exist")
+    await tick()
+
+    expect(root.innerHTML).toBe("Error")
+    expect(onError).toHaveBeenCalledTimes(1)
+
+    router.destroy()
+  })
+
+  it("clears the root instead of looping when the errorRoute itself has no match", async () => {
+    const { Router } = await import("../src/index")
+
+    const routes = [
+      { path: "/", loader: async () => ({ render: () => {} }) },
+      {
+        path: "/error",
+        loader: async (): Promise<never> => { throw new Error("Error route itself is broken") }
+      }
+    ]
+    const root = document.createElement("div")
+    const router = new Router(routes, root, { errorRoute: "/error" })
+    await tick()
+
+    router.navigate("/error")
+    await tick()
+
+    expect(root.innerHTML).toBe("")
+
+    router.destroy()
+  })
+
+  it("throws in the constructor when errorRoute does not match any route path", async () => {
+    const { Router } = await import("../src/index")
+    const routes = [{ path: "/", loader: async () => ({ render: () => {} }) }]
+    const root = document.createElement("div")
+
+    expect(() => new Router(routes, root, { errorRoute: "/missing" })).toThrow(
+      'errorRoute "/missing" does not match any route path.'
+    )
+  })
 })

tests/router.test.ts

@@ -811,4 +811,68 @@ describe("spectre-shell-router", () => {
       router.destroy()
     })
   })
+
+  describe("router.replace()", () => {
+    it("navigates without adding a new history entry", async () => {
+      const { Router } = await import("../src/index")
+      const render = vi.fn()
+      const routes = [
+        { path: "/", loader: async () => ({ render: vi.fn() }) },
+        { path: "/next", loader: async () => ({ render }) },
+      ]
+      const root = document.createElement("div")
+      window.history.replaceState({}, "", "/")
+
+      const router = new Router(routes, root)
+      await tick()
+      const lengthBefore = window.history.length
+
+      router.replace("/next")
+      await tick()
+
+      expect(render).toHaveBeenCalledOnce()
+      expect(window.location.pathname).toBe("/next")
+      expect(window.history.length).toBe(lengthBefore)
+      router.destroy()
+    })
+
+    it("uses a hash-prefixed URL in hash mode", async () => {
+      const { Router } = await import("../src/index")
+      const render = vi.fn()
+      const routes = [{ path: "/about", loader: async () => ({ render }) }]
+      const root = document.createElement("div")
+      window.history.replaceState({}, "", "/")
+
+      const router = new Router(routes, root, { mode: "hash" })
+      router.replace("/about")
+      await tick()
+
+      expect(render).toHaveBeenCalledOnce()
+      expect(window.location.hash).toBe("#/about")
+      router.destroy()
+    })
+  })
+
+  describe("router.back() and router.forward()", () => {
+    it("delegates to the History API", async () => {
+      const { Router } = await import("../src/index")
+      const routes = [{ path: "/", loader: async () => ({ render: vi.fn() }) }]
+      const root = document.createElement("div")
+      window.history.replaceState({}, "", "/")
+
+      const back = vi.spyOn(window.history, "back").mockImplementation(() => {})
+      const forward = vi.spyOn(window.history, "forward").mockImplementation(() => {})
+
+      const router = new Router(routes, root)
+      router.back()
+      router.forward()
+
+      expect(back).toHaveBeenCalledOnce()
+      expect(forward).toHaveBeenCalledOnce()
+
+      router.destroy()
+      back.mockRestore()
+      forward.mockRestore()
+    })
+  })
 })