Feat v0.9.0 multi surface packages (#73)

Co-authored-by: Jeffrey Smith <jasafpro@gmail.com>
Co-committed-by: Jeffrey Smith <jasafpro@gmail.com>

CHANGELOG.md

@@ -2,6 +2,78 @@
 
 All notable changes to Armature are documented here.
 
+## v0.9.0 — Multi-Surface Packages
+
+Packages can now declare multiple surfaces — each with its own path, access
+level, title, and layout. A single package can serve a public submission
+form, an authenticated dashboard, and an admin settings page. The kernel
+resolves incoming requests to the correct surface and enforces access
+server-side.
+
+**Manifest: `surfaces` array**
+
+- Packages declare a `surfaces` array with entries like
+  `{ "path": "/submit", "access": "public", "title": "Report a Bug" }`.
+- Each surface has independent `path`, `access`, `title`, `layout`, and
+  `nav` fields. Package-level `auth` and `layout` serve as defaults.
+- Supported access levels: `public`, `authenticated`, `admin`, `group:{name}`.
+- Packages without `surfaces` get auto-synthesis from legacy `auth`/`layout`
+  fields — no existing packages break.
+
+**Kernel: unified route tree**
+
+- Surface handler and ext API handler share a single `/s/:slug` route tree
+  via `RegisterExtensionRoutes`. The dispatcher checks the path prefix:
+  `/api/*` → ext API handler with JWT auth; everything else → surface
+  handler with per-surface access checks.
+- `matchSurface()` resolves request paths against surface patterns with
+  Gin-style `:param` support. Static segments preferred over params.
+- `evaluateAccess()` checks access requirements per-surface, with login
+  redirect for unauthenticated users and 403 for insufficient permissions.
+
+**Frontend: `__SURFACE_PATH__` + `sw.navigate()`**
+
+- `window.__SURFACE_PATH__` and `window.__SURFACE_PARAMS__` injected into
+  every extension surface page. Packages use these to decide which view to
+  render.
+- `sw.navigate(path, params)` for SPA-style intra-package routing via
+  `pushState`. Emits `surface.navigate` events. Handles back/forward via
+  `popstate`.
+- SDK version bumped to `0.9.0`.
+
+**Navigation**
+
+- `extensionNavItems` reads the `surfaces` array to find the nav entry
+  (first `nav: true`, or root `/`).
+- Fix: packages with `status: pending_review` no longer appear in the
+  sidebar navigation.
+
+**Validation**
+
+- `ValidateManifest` validates `surfaces` entries: path required, must
+  start with `/`, no duplicates, access level must be recognized.
+- Empty `surfaces` array rejected. Non-array `surfaces` rejected.
+
+**Tests: 22 new**
+
+- 11 manifest validation tests (surfaces valid/invalid, auto-synthesis,
+  group access, duplicate paths).
+- 11 route matching tests (static paths, param extraction, specificity
+  ordering, nav resolution).
+
+**Modified files:**
+
+- `server/handlers/package_validate.go` — surfaces validation + auto-synthesis
+- `server/handlers/package_validate_test.go` — 11 new tests
+- `server/main.go` — unified extension route registration
+- `server/pages/pages.go` — matchSurface, evaluateAccess, findNavSurface,
+  RegisterExtensionRoutes, nav status filter
+- `server/pages/pages_surface_match_test.go` — 11 new tests
+- `server/pages/templates/base.html` — surface path/params injection
+- `src/js/sw/sdk/index.js` — sw.navigate, popstate, version bump
+- `docs/PACKAGE-FORMAT.md` — surfaces field documentation
+- `docs/MULTI-SURFACE-GUIDE.md` — developer guide
+
 ## v0.8.5 — Extension Composability
 
 Extensions can now compose with each other through declared slots, UI