create-coralite 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-coralite",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Coralite scaffolding script",
   "bin": {
     "create-coralite": "bin/index.js",

package/templates/agent/AGENTS.md

@@ -181,6 +181,8 @@ Do NOT delete the `ref` attribute, and do NOT add an empty `client({ refs }) { r
 
 Top-level imports are reserved for `definePage` / `definePlugin` and modules used by isomorphic code (`getters`, `style`, `slots`). Modules used by `server()`, `client()`, or `paths()` must be loaded with dynamic `await import()` inside the block (`CORALITE-E301`).
 
+- **Lazy dependency stylesheets (`await import('*.css')`)**: Load dependency or local `.css` files lazily inside component and page `client()` blocks (or transitive client `.js` helpers) via `await import('pkg/styles.css', options)`, which bundles CSS at build time into hashed `assets/css/` assets, injects `<link rel="stylesheet">` into `<head>` in deterministic manifest order at runtime, and resolves to `{ default: link.sheet ?? null, link }`. Both flat options (`{ media, nonce, crossorigin, referrerPolicy, signal, force }`) and Import Attributes (`{ with: { type: 'css', ... }, signal, force }`) are supported. Static top-level `.css` imports or dynamic `.css` imports outside `client()` throw `CORALITE-E109`; unresolvable `.css` files throw `CORALITE-E403`.
+
 ## 4. Serialization boundary
 
 - `server()` runs in Node.js at build time and is stripped from the browser bundle. It returns an object to initialize/hydrate `state`.
@@ -212,3 +214,16 @@ Top-level imports are reserved for `definePage` / `definePlugin` and modules use
 - `tests/fixtures/` — component test fixtures (`.html`)
 - `public/` — static assets copied verbatim to output
 - `coralite.config.js` — project & plugin configuration
+
+## 8. SPA Router (opt-in)
+
+The opt-in router plugin (`coralite/plugins/router`) provides single-page application navigation. Register it in `coralite.config.js` under `plugins` (`plugins: [router({ ... })]`). Registration gates ALL SPA behavior — without it, every SPA navigation behavior (link interception, popstate, guards, head reconciliation) is inert: a `data-router-outlet` marker alone does nothing, and the page behaves as a standard multi-page app.
+
+- **Outlets**: Any element carrying the outlet attribute (default `data-router-outlet`) or the reserved `<router-outlet>` tag is an outlet. Every SPA-routed page MUST have an outlet or client navigation fails; outlet-less pages are auto-wrapped by default. Set `autoWrap: false` to disable automatic body wrapping; outlet-less pages then render as authored and still resolve tokens normally. Set `outletOnly: true` to skip link interception when the live document has no outlet, so those clicks use native browser navigation. `router.navigate()` is NOT affected by `outletOnly` and still updates history before failing if no outlet exists, so do not call it from outlet-less pages. Everything outside the outlet (navbar, background audio, open sockets) is never touched by the router — those component instances and their state persist across every route swap.
+- **Client API**: `client({ router })` injects the router: `navigate(path, { replace })`, `current()`, `beforeEach(guard)` (returns the unregister function), and the `viewTransitions` getter. Also available on `window.__coralite_router__`.
+- **Guards**: `beforeEach` guards may return `true`/`undefined` (allow), `false` (block), a relative or same-origin path (soft redirect; redirect chains are capped at depth 10), or an `http(s)` URL (hard redirect via `window.location.replace()`).
+- **Guard placement**: The guard list lives in the router's client-init scope and PERSISTS across the whole SPA session — an outlet swap does not reset it, and nothing auto-unregisters a guard when its route leaves. App-wide guards (auth, redirects) MUST be registered in a persistent shell component OUTSIDE the outlet (it connects once, so the guard registers exactly once). Route-scoped guards MUST capture the function returned by `beforeEach` and call it on their component `signal` abort. Registering guards inside a route component's `client()` without unregistering accumulates one extra guard per visit.
+- **State scoping**: Component `state` is route-scoped — on navigation the old outlet is disconnected (its `signal` aborts), and the new route hydrates from its pre-built HTML, so `state` mutations are lost when the route leaves. App-scoped state belongs in the global `store` (declared in `coralite.config.js`), which the router never touches and which survives every swap. Release imperative resources a component allocates (workers, canvas/WebGL contexts, external library handles) when the component is torn down — hook teardown to the `signal` `abort` event.
+- **Navigation events**: Cancelable `coralite:navigating` (fired before the swap) and post-swap `coralite:navigated` on `window`, both with `detail: { from, to }`.
+
+Full contract: https://coralite.dev/docs/reference/plugins/router.html — patterns guide: https://coralite.dev/docs/guide/spa-router.html

package/templates/agent/copilot-instructions.md

@@ -102,6 +102,7 @@ When generating or editing Coralite files (`src/components/*.html`, `src/pages/*
 - Top-level imports are reserved for `definePage` / `definePlugin` and modules used by isomorphic code (`getters`, `style`, `slots`).
 - `server()` runs in Node.js at build time and is stripped from the browser bundle. It returns an object to initialize/hydrate `state`.
 - `client()` is serialized to run in the browser and cannot reference module-scope variables or top-level imports. Modules used by `server()`, `client()`, or `paths()` must be loaded with dynamic `await import()` inside the block (`CORALITE-E301`).
+- **Lazy dependency stylesheets (`await import('*.css')`)**: Load dependency or local `.css` files lazily inside component and page `client()` blocks (or transitive client `.js` helpers) via `await import('pkg/styles.css', options)` (`{ default: link.sheet ?? null, link }`). Static top-level `.css` imports or dynamic `.css` imports outside `client()` throw `CORALITE-E109`; unresolvable `.css` files throw `CORALITE-E403`.
 
 ## 4. No defensive guards in deterministic blocks
 
@@ -121,3 +122,14 @@ When generating or editing Coralite files (`src/components/*.html`, `src/pages/*
 - `pnpm build` — build production output to `dist/`
 - `pnpm check` — validate components, pages, and plugins (`coralite check`)
 - `pnpm fix` — auto-fix safe validation diagnostics (`coralite fix`)
+
+## 7. SPA Router (opt-in)
+
+The opt-in router plugin (`coralite/plugins/router`) gates ALL SPA behavior: without registration in `coralite.config.js`, a `data-router-outlet` marker is inert and the app stays multi-page.
+
+- **Outlets**: The routed region is any element with the outlet attribute (default `data-router-outlet`) or the reserved `<router-outlet>` tag. Every SPA-routed page MUST have an outlet or client navigation fails. Set `autoWrap: false` to disable automatic body wrapping; outlet-less pages render as authored and still resolve tokens. Set `outletOnly: true` so links on outlet-less pages use native navigation instead of being intercepted. `router.navigate()` is NOT affected by `outletOnly` and still updates history before failing without an outlet — do not call it from outlet-less pages. Elements OUTSIDE the outlet are untouched by the router and persist across route swaps.
+- **Client API**: `client({ router })` injects `navigate(path, { replace })`, `current()`, `beforeEach(guard)` (returns the unregister function), and the `viewTransitions` getter.
+- **Guard placement**: The guard list persists for the whole SPA session — outlet swaps never reset it, and nothing auto-unregisters. App-wide guards MUST be registered in a persistent shell component OUTSIDE the outlet; route-scoped guards MUST unregister on component `signal` abort, or every visit accumulates another guard.
+- **State scoping**: Component `state` is route-scoped (lost when the route leaves; the new route re-hydrates from its pre-built HTML). App-scoped state MUST live in the global `store`, which survives every swap. Teardown imperative resources on `signal` abort.
+
+Full contract: https://coralite.dev/docs/reference/plugins/router.html — patterns guide: https://coralite.dev/docs/guide/spa-router.html

package/templates/agent/coralite.mdc

@@ -99,6 +99,7 @@ alwaysApply: false
 - Top-level imports are reserved for `definePage` / `definePlugin` and modules used by isomorphic code (`getters`, `style`, `slots`).
 - `server()` runs in Node.js at build time and is stripped from the browser bundle. It returns an object to initialize/hydrate `state`.
 - `client()` is serialized to run in the browser and cannot reference module-scope variables or top-level imports. Modules used by `server()`, `client()`, or `paths()` must be loaded with dynamic `await import()` inside the block (`CORALITE-E301`).
+- **Lazy dependency stylesheets (`await import('*.css')`)**: Load dependency or local `.css` files lazily inside component and page `client()` blocks (or transitive client `.js` helpers) via `await import('pkg/styles.css', options)` (`{ default: link.sheet ?? null, link }`). Static top-level `.css` imports or dynamic `.css` imports outside `client()` throw `CORALITE-E109`; unresolvable `.css` files throw `CORALITE-E403`.
 
 ## 3. No defensive guards in deterministic blocks
 
@@ -111,3 +112,14 @@ alwaysApply: false
 
 - **Factory functions over classes**: Default to factory functions (`createX`). No `this` outside class bodies; always use destructured context (`state`, `refs`, `emit`, `root`).
 - **Scoped CSS**: Use `:host` for the custom element root and `:host-context(.selector)` for ancestor themes. Write `.child` directly instead of `:host .child`.
+
+## 5. SPA Router (opt-in)
+
+The opt-in router plugin (`coralite/plugins/router`) gates ALL SPA behavior: without registration in `coralite.config.js`, a `data-router-outlet` marker is inert and the app stays multi-page.
+
+- **Outlets**: The routed region is any element with the outlet attribute (default `data-router-outlet`) or the reserved `<router-outlet>` tag. Every SPA-routed page MUST have an outlet or client navigation fails. Set `autoWrap: false` to disable automatic body wrapping; outlet-less pages render as authored and still resolve tokens. Set `outletOnly: true` so links on outlet-less pages use native navigation instead of being intercepted. `router.navigate()` is NOT affected by `outletOnly` and still updates history before failing without an outlet — do not call it from outlet-less pages. Elements OUTSIDE the outlet are untouched by the router and persist across route swaps.
+- **Client API**: `client({ router })` injects `navigate(path, { replace })`, `current()`, `beforeEach(guard)` (returns the unregister function), and the `viewTransitions` getter.
+- **Guard placement**: The guard list persists for the whole SPA session — outlet swaps never reset it, and nothing auto-unregisters. App-wide guards MUST be registered in a persistent shell component OUTSIDE the outlet; route-scoped guards MUST unregister on component `signal` abort, or every visit accumulates another guard.
+- **State scoping**: Component `state` is route-scoped (lost when the route leaves; the new route re-hydrates from its pre-built HTML). App-scoped state MUST live in the global `store`, which survives every swap. Teardown imperative resources on `signal` abort.
+
+Full contract: https://coralite.dev/docs/reference/plugins/router.html — patterns guide: https://coralite.dev/docs/guide/spa-router.html

package/templates/css/AGENTS.md

@@ -181,6 +181,8 @@ Do NOT delete the `ref` attribute, and do NOT add an empty `client({ refs }) { r
 
 Top-level imports are reserved for `definePage` / `definePlugin` and modules used by isomorphic code (`getters`, `style`, `slots`). Modules used by `server()`, `client()`, or `paths()` must be loaded with dynamic `await import()` inside the block (`CORALITE-E301`).
 
+- **Lazy dependency stylesheets (`await import('*.css')`)**: Load dependency or local `.css` files lazily inside component and page `client()` blocks (or transitive client `.js` helpers) via `await import('pkg/styles.css', options)`, which bundles CSS at build time into hashed `assets/css/` assets, injects `<link rel="stylesheet">` into `<head>` in deterministic manifest order at runtime, and resolves to `{ default: link.sheet ?? null, link }`. Both flat options (`{ media, nonce, crossorigin, referrerPolicy, signal, force }`) and Import Attributes (`{ with: { type: 'css', ... }, signal, force }`) are supported. Static top-level `.css` imports or dynamic `.css` imports outside `client()` throw `CORALITE-E109`; unresolvable `.css` files throw `CORALITE-E403`.
+
 ## 4. Serialization boundary
 
 - `server()` runs in Node.js at build time and is stripped from the browser bundle. It returns an object to initialize/hydrate `state`.
@@ -212,3 +214,16 @@ Top-level imports are reserved for `definePage` / `definePlugin` and modules use
 - `tests/fixtures/` — component test fixtures (`.html`)
 - `public/` — static assets copied verbatim to output
 - `coralite.config.js` — project & plugin configuration
+
+## 8. SPA Router (opt-in)
+
+The opt-in router plugin (`coralite/plugins/router`) provides single-page application navigation. Register it in `coralite.config.js` under `plugins` (`plugins: [router({ ... })]`). Registration gates ALL SPA behavior — without it, every SPA navigation behavior (link interception, popstate, guards, head reconciliation) is inert: a `data-router-outlet` marker alone does nothing, and the page behaves as a standard multi-page app.
+
+- **Outlets**: Any element carrying the outlet attribute (default `data-router-outlet`) or the reserved `<router-outlet>` tag is an outlet. Every SPA-routed page MUST have an outlet or client navigation fails; outlet-less pages are auto-wrapped by default. Set `autoWrap: false` to disable automatic body wrapping; outlet-less pages then render as authored and still resolve tokens normally. Set `outletOnly: true` to skip link interception when the live document has no outlet, so those clicks use native browser navigation. `router.navigate()` is NOT affected by `outletOnly` and still updates history before failing if no outlet exists, so do not call it from outlet-less pages. Everything outside the outlet (navbar, background audio, open sockets) is never touched by the router — those component instances and their state persist across every route swap.
+- **Client API**: `client({ router })` injects the router: `navigate(path, { replace })`, `current()`, `beforeEach(guard)` (returns the unregister function), and the `viewTransitions` getter. Also available on `window.__coralite_router__`.
+- **Guards**: `beforeEach` guards may return `true`/`undefined` (allow), `false` (block), a relative or same-origin path (soft redirect; redirect chains are capped at depth 10), or an `http(s)` URL (hard redirect via `window.location.replace()`).
+- **Guard placement**: The guard list lives in the router's client-init scope and PERSISTS across the whole SPA session — an outlet swap does not reset it, and nothing auto-unregisters a guard when its route leaves. App-wide guards (auth, redirects) MUST be registered in a persistent shell component OUTSIDE the outlet (it connects once, so the guard registers exactly once). Route-scoped guards MUST capture the function returned by `beforeEach` and call it on their component `signal` abort. Registering guards inside a route component's `client()` without unregistering accumulates one extra guard per visit.
+- **State scoping**: Component `state` is route-scoped — on navigation the old outlet is disconnected (its `signal` aborts), and the new route hydrates from its pre-built HTML, so `state` mutations are lost when the route leaves. App-scoped state belongs in the global `store` (declared in `coralite.config.js`), which the router never touches and which survives every swap. Release imperative resources a component allocates (workers, canvas/WebGL contexts, external library handles) when the component is torn down — hook teardown to the `signal` `abort` event.
+- **Navigation events**: Cancelable `coralite:navigating` (fired before the swap) and post-swap `coralite:navigated` on `window`, both with `detail: { from, to }`.
+
+Full contract: https://coralite.dev/docs/reference/plugins/router.html — patterns guide: https://coralite.dev/docs/guide/spa-router.html

package/templates/css/package.json

@@ -11,6 +11,6 @@
     "fix": "coralite fix"
   },
   "devDependencies": {
-    "coralite": "^1.0.0"
+    "coralite": "^1.1.0"
   }
 }

package/templates/plugin/AGENTS.md

@@ -181,6 +181,8 @@ Do NOT delete the `ref` attribute, and do NOT add an empty `client({ refs }) { r
 
 Top-level imports are reserved for `definePage` / `definePlugin` and modules used by isomorphic code (`getters`, `style`, `slots`). Modules used by `server()`, `client()`, or `paths()` must be loaded with dynamic `await import()` inside the block (`CORALITE-E301`).
 
+- **Lazy dependency stylesheets (`await import('*.css')`)**: Load dependency or local `.css` files lazily inside component and page `client()` blocks (or transitive client `.js` helpers) via `await import('pkg/styles.css', options)`, which bundles CSS at build time into hashed `assets/css/` assets, injects `<link rel="stylesheet">` into `<head>` in deterministic manifest order at runtime, and resolves to `{ default: link.sheet ?? null, link }`. Both flat options (`{ media, nonce, crossorigin, referrerPolicy, signal, force }`) and Import Attributes (`{ with: { type: 'css', ... }, signal, force }`) are supported. Static top-level `.css` imports or dynamic `.css` imports outside `client()` throw `CORALITE-E109`; unresolvable `.css` files throw `CORALITE-E403`.
+
 ## 4. Serialization boundary
 
 - `server()` runs in Node.js at build time and is stripped from the browser bundle. It returns an object to initialize/hydrate `state`.
@@ -212,3 +214,16 @@ Top-level imports are reserved for `definePage` / `definePlugin` and modules use
 - `tests/fixtures/` — component test fixtures (`.html`)
 - `public/` — static assets copied verbatim to output
 - `coralite.config.js` — project & plugin configuration
+
+## 8. SPA Router (opt-in)
+
+The opt-in router plugin (`coralite/plugins/router`) provides single-page application navigation. Register it in `coralite.config.js` under `plugins` (`plugins: [router({ ... })]`). Registration gates ALL SPA behavior — without it, every SPA navigation behavior (link interception, popstate, guards, head reconciliation) is inert: a `data-router-outlet` marker alone does nothing, and the page behaves as a standard multi-page app.
+
+- **Outlets**: Any element carrying the outlet attribute (default `data-router-outlet`) or the reserved `<router-outlet>` tag is an outlet. Every SPA-routed page MUST have an outlet or client navigation fails; outlet-less pages are auto-wrapped by default. Set `autoWrap: false` to disable automatic body wrapping; outlet-less pages then render as authored and still resolve tokens normally. Set `outletOnly: true` to skip link interception when the live document has no outlet, so those clicks use native browser navigation. `router.navigate()` is NOT affected by `outletOnly` and still updates history before failing if no outlet exists, so do not call it from outlet-less pages. Everything outside the outlet (navbar, background audio, open sockets) is never touched by the router — those component instances and their state persist across every route swap.
+- **Client API**: `client({ router })` injects the router: `navigate(path, { replace })`, `current()`, `beforeEach(guard)` (returns the unregister function), and the `viewTransitions` getter. Also available on `window.__coralite_router__`.
+- **Guards**: `beforeEach` guards may return `true`/`undefined` (allow), `false` (block), a relative or same-origin path (soft redirect; redirect chains are capped at depth 10), or an `http(s)` URL (hard redirect via `window.location.replace()`).
+- **Guard placement**: The guard list lives in the router's client-init scope and PERSISTS across the whole SPA session — an outlet swap does not reset it, and nothing auto-unregisters a guard when its route leaves. App-wide guards (auth, redirects) MUST be registered in a persistent shell component OUTSIDE the outlet (it connects once, so the guard registers exactly once). Route-scoped guards MUST capture the function returned by `beforeEach` and call it on their component `signal` abort. Registering guards inside a route component's `client()` without unregistering accumulates one extra guard per visit.
+- **State scoping**: Component `state` is route-scoped — on navigation the old outlet is disconnected (its `signal` aborts), and the new route hydrates from its pre-built HTML, so `state` mutations are lost when the route leaves. App-scoped state belongs in the global `store` (declared in `coralite.config.js`), which the router never touches and which survives every swap. Release imperative resources a component allocates (workers, canvas/WebGL contexts, external library handles) when the component is torn down — hook teardown to the `signal` `abort` event.
+- **Navigation events**: Cancelable `coralite:navigating` (fired before the swap) and post-swap `coralite:navigated` on `window`, both with `detail: { from, to }`.
+
+Full contract: https://coralite.dev/docs/reference/plugins/router.html — patterns guide: https://coralite.dev/docs/guide/spa-router.html

package/templates/plugin/package.json

@@ -18,6 +18,6 @@
     "node": ">=22.22.2"
   },
   "devDependencies": {
-    "coralite": "^1.0.0"
+    "coralite": "^1.1.0"
   }
 }

package/templates/scss/AGENTS.md

@@ -181,6 +181,8 @@ Do NOT delete the `ref` attribute, and do NOT add an empty `client({ refs }) { r
 
 Top-level imports are reserved for `definePage` / `definePlugin` and modules used by isomorphic code (`getters`, `style`, `slots`). Modules used by `server()`, `client()`, or `paths()` must be loaded with dynamic `await import()` inside the block (`CORALITE-E301`).
 
+- **Lazy dependency stylesheets (`await import('*.css')`)**: Load dependency or local `.css` files lazily inside component and page `client()` blocks (or transitive client `.js` helpers) via `await import('pkg/styles.css', options)`, which bundles CSS at build time into hashed `assets/css/` assets, injects `<link rel="stylesheet">` into `<head>` in deterministic manifest order at runtime, and resolves to `{ default: link.sheet ?? null, link }`. Both flat options (`{ media, nonce, crossorigin, referrerPolicy, signal, force }`) and Import Attributes (`{ with: { type: 'css', ... }, signal, force }`) are supported. Static top-level `.css` imports or dynamic `.css` imports outside `client()` throw `CORALITE-E109`; unresolvable `.css` files throw `CORALITE-E403`.
+
 ## 4. Serialization boundary
 
 - `server()` runs in Node.js at build time and is stripped from the browser bundle. It returns an object to initialize/hydrate `state`.
@@ -212,3 +214,16 @@ Top-level imports are reserved for `definePage` / `definePlugin` and modules use
 - `tests/fixtures/` — component test fixtures (`.html`)
 - `public/` — static assets copied verbatim to output
 - `coralite.config.js` — project & plugin configuration
+
+## 8. SPA Router (opt-in)
+
+The opt-in router plugin (`coralite/plugins/router`) provides single-page application navigation. Register it in `coralite.config.js` under `plugins` (`plugins: [router({ ... })]`). Registration gates ALL SPA behavior — without it, every SPA navigation behavior (link interception, popstate, guards, head reconciliation) is inert: a `data-router-outlet` marker alone does nothing, and the page behaves as a standard multi-page app.
+
+- **Outlets**: Any element carrying the outlet attribute (default `data-router-outlet`) or the reserved `<router-outlet>` tag is an outlet. Every SPA-routed page MUST have an outlet or client navigation fails; outlet-less pages are auto-wrapped by default. Set `autoWrap: false` to disable automatic body wrapping; outlet-less pages then render as authored and still resolve tokens normally. Set `outletOnly: true` to skip link interception when the live document has no outlet, so those clicks use native browser navigation. `router.navigate()` is NOT affected by `outletOnly` and still updates history before failing if no outlet exists, so do not call it from outlet-less pages. Everything outside the outlet (navbar, background audio, open sockets) is never touched by the router — those component instances and their state persist across every route swap.
+- **Client API**: `client({ router })` injects the router: `navigate(path, { replace })`, `current()`, `beforeEach(guard)` (returns the unregister function), and the `viewTransitions` getter. Also available on `window.__coralite_router__`.
+- **Guards**: `beforeEach` guards may return `true`/`undefined` (allow), `false` (block), a relative or same-origin path (soft redirect; redirect chains are capped at depth 10), or an `http(s)` URL (hard redirect via `window.location.replace()`).
+- **Guard placement**: The guard list lives in the router's client-init scope and PERSISTS across the whole SPA session — an outlet swap does not reset it, and nothing auto-unregisters a guard when its route leaves. App-wide guards (auth, redirects) MUST be registered in a persistent shell component OUTSIDE the outlet (it connects once, so the guard registers exactly once). Route-scoped guards MUST capture the function returned by `beforeEach` and call it on their component `signal` abort. Registering guards inside a route component's `client()` without unregistering accumulates one extra guard per visit.
+- **State scoping**: Component `state` is route-scoped — on navigation the old outlet is disconnected (its `signal` aborts), and the new route hydrates from its pre-built HTML, so `state` mutations are lost when the route leaves. App-scoped state belongs in the global `store` (declared in `coralite.config.js`), which the router never touches and which survives every swap. Release imperative resources a component allocates (workers, canvas/WebGL contexts, external library handles) when the component is torn down — hook teardown to the `signal` `abort` event.
+- **Navigation events**: Cancelable `coralite:navigating` (fired before the swap) and post-swap `coralite:navigated` on `window`, both with `detail: { from, to }`.
+
+Full contract: https://coralite.dev/docs/reference/plugins/router.html — patterns guide: https://coralite.dev/docs/guide/spa-router.html

package/templates/scss/package.json

@@ -11,6 +11,6 @@
     "fix": "coralite fix"
   },
   "devDependencies": {
-    "coralite": "^1.0.0"
+    "coralite": "^1.1.0"
   }
 }