Return router from bootstrapApp

Make `bootstrapApp()` return the `Router` instance so consumers can navigate programmatically through the shell. Update the public export, add test coverage, and sync the README, roadmap, todo, and changelog notes.

Author: bradpotts

CHANGELOG.md

@@ -6,8 +6,8 @@ All notable changes to this project will be documented here. The format follows
 
 ### Changed
 
-- Bumped `@phcdevworks/spectre-tokens` to `^3.2.0` and `@phcdevworks/spectre-ui`
-  to `^2.5.0`, closing dependency drift against the current published
+- Bumped `@phcdevworks/spectre-tokens` to `^3.3.1` and `@phcdevworks/spectre-ui`
+  to `^2.7.1`, closing dependency drift against the current published
   `project-design` packages. Both upstream releases were additive only — no
   source changes required here.
 
@@ -20,6 +20,12 @@ All notable changes to this project will be documented here. The format follows
 
 ### Added
 
+- **`bootstrapApp()` returns the `Router` instance** (previously `void`),
+  giving consumers direct access to `router.navigate()`, `router.back()`/
+  `forward()`, and `router.subscribe()` without a separate router reference.
+  Additive change — existing call sites that ignore the return value are
+  unaffected. Unblocks `spectre-init` Phase 6 template modernization and
+  closes `spectre-shell` Phase 2 (P2.5).
 - Added a plugin system: `BootstrapOptions` accepts an optional
   `plugins?: ShellPlugin[]` array. Each plugin's `install(context)` runs after
   `beforeMount` and before `routes()`, in declaration order, receiving a

README.md

@@ -110,10 +110,19 @@ Steps 1–4 are wrapped in an error boundary. Failures throw `[spectre-shell] Bo
 
 ## API
 
-- `bootstrapApp(options)` runs the shell bootstrap flow.
+- `bootstrapApp(options)` runs the shell bootstrap flow and returns the
+  `Router` instance created from `options.routes()`, giving consumers direct
+  access to `router.navigate()`, `router.back()`/`forward()`, and
+  `router.subscribe()`.
 - `bootReady` is a signal that becomes `true` after the router starts.
 - `BootstrapOptions` defines `root`, `routes`, `beforeMount`, and `afterMount`.
 
+```ts
+const router = bootstrapApp({ root, routes: () => [...] })
+
+router.navigate('/about')
+```
+
 ## Ecosystem
 
 `spectre-shell` is the SPA entry point of the Spectre stack. Each package owns

ROADMAP.md

@@ -4,9 +4,8 @@
 system. It wires a root DOM element to route definitions, starts the router,
 loads shared shell styles, and exposes a `bootReady` readiness signal.
 
-The foundation is complete at v1.1.0. Phase 2 core (P2.1–P2.3) is done and
-queued for the next release. P2.4 Router Signal Bridge is under evaluation.
-Phase 3 (broader adoption) opens once Phase 2 is fully closed.
+The foundation is complete at v1.1.1. Phase 2 (P2.1–P2.5) is fully done and
+queued for the next release. Phase 3 (broader adoption) is now open.
 
 ## Phase 1: Foundation — Complete (v0.0.1 – v1.1.0)
 
@@ -81,24 +80,21 @@ apps repeat the same wiring pattern.
 
 ### P2.5 Programmatic Navigation
 
-Status: CURRENT PRIORITY — blocking spectre-init Phase 6
+Status: Done, in `[Unreleased]`, queued for next minor release.
 
-`bootstrapApp` currently returns `void`. Consumers have no first-class way to
-call `router.navigate()` programmatically. Decision: **Option A** — return the
-`Router` instance from `bootstrapApp`. This is additive; no existing call sites
-break; gives consumers full router access (navigate, replace, back, forward).
+`bootstrapApp` now returns the `Router` instance created from `options.routes()`
+instead of `void` (Option A). Additive change — no existing call sites break;
+gives consumers full router access (`navigate`, `replace`, `back`, `forward`,
+`subscribe`). Covered in `tests/bootstrap.test.ts`; documented in `README.md`.
 
-Implement before the next release so `spectre-init` templates can demonstrate
-programmatic navigation.
-
-**Unblocks when shipped:**
+**Unblocked by this shipping:**
 
 - `spectre-init` Phase 6 template modernization (navigate() in templates)
-- `spectre-shell` Phase 3 (Phase 2 fully closed once this ships)
+- `spectre-shell` Phase 3 (Phase 2 is now fully closed)
 
 ## Phase 3: Broader Adoption
 
-Prerequisite: Phase 2 is fully closed (P2.4 decided ✓, P2.5 implemented — pending).
+Phase 2 is fully closed (P2.4 decided ✓, P2.5 implemented ✓). Phase 3 is open.
 
 ### P3.1 Starter Template
 

TODO.md

@@ -1,8 +1,8 @@
 # Spectre Shell Execution Todo
 
 Tracks forward work from the v1.1.1 baseline. Phase 1 is complete. Phase 2
-core (P0/P1/P2) is complete and queued for the next release. P3 Router Signal
-Bridge is the current evaluation item. Phase 3 (broader adoption) is next.
+(P0–P2.5) is fully complete and queued for the next release. Phase 3
+(broader adoption) is now open.
 
 ## Phase 1: Foundation — Complete
 
@@ -103,15 +103,27 @@ or deferred explicitly.
 
 ---
 
-## Phase 2: Ecosystem Integration — P2.4 closed; P2.5 is the remaining item
+## Phase 2: Ecosystem Integration — Complete (P0–P2.5)
 
-Phase 2 is fully closed once P2.5 ships. Phase 3 opens after that.
+Phase 2 is fully closed. Phase 3 is now open.
+
+### P2.5: Programmatic Navigation — Done
+
+`bootstrapApp` creates the `Router` internally and now returns it instead of
+`void` (Option A). Additive change; no existing callers break; gives consumers
+full router access.
+
+- [x] Change `bootstrapApp` return type from `void` to `Router`
+  - Files: `src/bootstrap.ts`, `src/index.ts`, `tests/bootstrap.test.ts`, `README.md`
+  - Acceptance: `bootstrapApp(options)` returns the `Router` instance; existing call
+    sites that ignore the return value continue to work; tests confirm the instance
+    is the same Router used internally; CHANGELOG entry added under `[Unreleased]`
 
 ---
 
 ## Phase 3: Broader Adoption
 
-Prerequisite: P2.5 implemented (Phase 2 fully closed).
+Prerequisite met: P2.5 implemented, Phase 2 fully closed.
 
 - [ ] Starter template or `create-spectre-app` scaffolding — depends on Phase 2 closed and stable
 - [ ] Framework adapter evaluation — only if a downstream app requires it
@@ -122,24 +134,9 @@ Prerequisite: P2.5 implemented (Phase 2 fully closed).
 
 `@phcdevworks/spectre-init` scaffolds templates against this package. These items
 are needed for templates to work correctly and demonstrate the full API surface.
+P0 (programmatic navigation) is done; P1 items remain before spectre-init Phase 6 ships.
 
-### P0: Programmatic Navigation — CURRENT PRIORITY — Blocking spectre-init Phase 6
-
-`bootstrapApp` creates the `Router` internally and returns `void`. Templates have
-no way to call `router.navigate()` programmatically.
-
-**Decision: Option A** — `bootstrapApp` returns the `Router` instance.
-Additive change; no existing callers break; gives consumers full router access.
-
-- [ ] Change `bootstrapApp` return type from `void` to `Router`
-  - Files: `src/bootstrap.ts`, `src/index.ts`, `tests/bootstrap.test.ts`, `README.md`
-  - Acceptance: `bootstrapApp(options)` returns the `Router` instance; existing call
-    sites that ignore the return value continue to work; tests confirm the instance
-    is the same Router used internally; CHANGELOG entry added under `[Unreleased]`
-
-Do not use `history.pushState` as a workaround — it bypasses the Router's race-condition guard.
-
-### P1: Template Showcase Items — Needed before spectre-init Phase 6 ships
+### P1: Template Showcase Items — Needed before spectre-init Phase 6 ships (P0 done)
 
 These APIs are shipped in v1.1.1 but not yet in scaffolded output. Confirm they
 are stable and documented so spectre-init templates can reference them.

src/bootstrap.ts

@@ -21,16 +21,17 @@ export type BootstrapOptions = {
   plugins?: ShellPlugin[]
 }
 
-export function bootstrapApp(options: BootstrapOptions): void {
+export function bootstrapApp(options: BootstrapOptions): Router {
   const { root, routes, beforeMount, afterMount, plugins } = options
+  let router: Router
   try {
     beforeMount?.()
     const context: ShellPluginContext = { bootReady }
     for (const plugin of plugins ?? []) {
       plugin.install(context)
     }
     const registeredRoutes = routes()
-    new Router(registeredRoutes, root)
+    router = new Router(registeredRoutes, root)
     bootReady.value = true
   } catch (err) {
     throw new Error(
@@ -39,4 +40,5 @@ export function bootstrapApp(options: BootstrapOptions): void {
     )
   }
   afterMount?.()
+  return router
 }

src/index.ts

@@ -5,3 +5,4 @@ export {
   type ShellPlugin,
   type ShellPluginContext
 } from './bootstrap.js'
+export type { Router } from '@phcdevworks/spectre-shell-router'

tests/bootstrap.test.ts

@@ -24,6 +24,16 @@ describe('bootstrapApp', () => {
     expect(Object.keys(shell).sort()).toEqual(['bootReady', 'bootstrapApp'])
   })
 
+  it('returns the Router instance created during bootstrap', async () => {
+    const root = document.createElement('div')
+    const { bootstrapApp } = await import('../src/index.js')
+
+    const result = bootstrapApp({ root, routes: () => [] })
+
+    expect(result).toBeInstanceOf(Object)
+    expect(routerConstructor).toHaveBeenCalledTimes(1)
+  })
+
   it('runs plugin install after beforeMount and before route registration', async () => {
     const order: string[] = []
     const root = document.createElement('div')
@@ -124,7 +134,7 @@ describe('bootstrapApp', () => {
 
     const result = bootstrapApp({ root, routes })
 
-    expect(result).toBeUndefined()
+    expect(result).toBeDefined()
     expect(root.innerHTML).toBe('<p>existing</p>')
     expect(routes).toHaveBeenCalledTimes(1)
     expect(routerConstructor).toHaveBeenCalledTimes(1)