Feat v0.9.0 multi surface packages (#73)

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

docs/PACKAGE-FORMAT.md

@@ -60,9 +60,10 @@ Only `manifest.json` is required. All other directories are optional and include
 | `description` | Short description |
 | `icon` | Emoji for sidebar/menu display |
 | `author` | Package author |
-| `route` | URL path for surfaces (e.g., `/s/my-package`) |
-| `auth` | `authenticated` or `public` |
-| `layout` | Surface layout mode (e.g., `single`) |
+| `surfaces` | Array of surface entries with per-path access, title, layout (see below) |
+| `route` | *(deprecated — use `surfaces`)* URL path for surfaces |
+| `auth` | Default access level for all surfaces: `authenticated`, `public`, `admin` |
+| `layout` | Default layout for all surfaces: `single`, `editor` |
 | `permissions` | Array of required capabilities (`db.write`, `http`, `notifications`, `secrets`, `realtime.publish`) |
 | `api_routes` | Array of `{"method": "GET", "path": "/items"}` |
 | `db_tables` | Table definitions with columns and indexes |
@@ -75,6 +76,71 @@ Only `manifest.json` is required. All other directories are optional and include
 | `capabilities` | Environment requirements: `{"required": [...], "optional": [...]}` |
 | `schema_version` | Integer for additive schema migrations |
 
+## Multi-Surface Packages
+
+A package can serve multiple pages, each with its own path, access level,
+title, and layout. Declare a `surfaces` array in the manifest:
+
+```json
+{
+  "id": "bug-tracker",
+  "title": "Bug Tracker",
+  "type": "full",
+  "auth": "authenticated",
+  "layout": "single",
+  "surfaces": [
+    { "path": "/",       "title": "Dashboard" },
+    { "path": "/submit", "access": "public", "title": "Report a Bug" },
+    { "path": "/:id",    "title": "Bug Detail", "nav": false },
+    { "path": "/admin",  "access": "admin",  "title": "Settings", "nav": false }
+  ]
+}
+```
+
+### Surface Entry Fields
+
+| Field    | Type   | Default        | Description |
+|----------|--------|----------------|-------------|
+| `path`   | string | **required**   | Relative to `/s/{pkg-id}`. Supports `:param` segments. |
+| `access` | string | package `auth` | `public`, `authenticated`, `admin`, `group:{name}`. |
+| `title`  | string | package `title`| Human label. Used in nav if `nav: true`. |
+| `layout` | string | package `layout`| `single`, `editor`, or future layouts. |
+| `nav`    | bool   | see rules      | Show in sidebar navigation. |
+
+### Nav Visibility Rules
+
+- `path: "/"` defaults to `nav: true` (primary entry point)
+- All others default to `nav: false` (sub-pages)
+- Explicit `"nav": true` overrides — a package can put multiple entries in nav
+- The sidebar links to the first surface with `nav: true`
+
+### Backward Compatibility
+
+If `surfaces` is absent, the kernel synthesizes one entry from the legacy
+`auth` and `layout` fields. No existing packages break.
+
+### Client-Side Navigation
+
+Within a multi-surface package, use `sw.navigate()` for SPA-style routing:
+
+```js
+const path = window.__SURFACE_PATH__ || '/';
+const params = window.__SURFACE_PARAMS__ || {};
+
+if (path === '/')           renderDashboard();
+if (path === '/submit')     renderSubmitForm();
+if (path === '/:id')        renderDetail(params.id);
+
+// Navigate to another surface within the package
+sw.navigate('/submit');
+sw.navigate('/:id', { id: 'bug-42' });
+
+// Listen for navigation events (including back/forward)
+sw.on('surface.navigate', ({ path, params }) => {
+    renderView(path, params);
+});
+```
+
 ## Composability: Slots and Contributions
 
 Packages compose with each other through named UI injection points (**slots**) and **contributions**.