caspian-utils 0.1.25 → 0.2.0

package/dist/docs/pulsepoint.md

@@ -350,6 +350,10 @@ Important:
 - Component scripts are plain JavaScript executed with `new Function(...)`. Do not use `import`, `export`, or top-level `await` inside them.
 - The runtime auto-returns supported top-level bindings from the script. Do not rely on manual `return { ... }` objects.
 - `pp.props` contains the current prop bag for the component.
+- `pp.props` is computed from the **rendered root element's attributes**, not from any server-side signature. A prop that never lands on the root is `undefined` in the browser, with no server error and no console warning. In a Python component this means every prop the template references must be forwarded through `get_attributes({...}, props)`; see [components.md](./components.md#every-prop-a-template-reads-must-be-forwarded-to-the-root).
+- Prop value types depend on how the attribute reaches the root. An unevaluated brace expression such as `volume="{vol}"` is evaluated in the parent component's scope and keeps its real type (number, boolean, object, function). A literal attribute such as `volume="0"` arrives as the **string** `"0"`, so `volume === 0` is false. A valueless attribute arrives as boolean `true`. Coerce or compare loosely when the value may be a server-rendered literal.
+- Attribute names round-trip through kebab-case: `isFullscreen` renders as `is-fullscreen` and returns as `pp.props.isFullscreen`.
+- Attribute names that are JavaScript reserved words are dropped from the prop bag, so `pp.props.class` and `pp.props.for` never exist. Use a non-reserved prop name when the script must read the value.
 - `pp.props.children` contains the root's initial inner HTML before the owned script is removed from the render template.
 - Props are not auto-injected as standalone top-level template or handler variables. Read them through `pp.props` or explicitly destructure them in the component script.
 
@@ -402,6 +406,13 @@ Hooks exposed inside component scripts through `pp`:
 - `pp.reducer(reducer, initialState)` returns `[state, dispatch]`.
 - `pp.context(token)` resolves a provided context value from ancestor components.
 - `pp.portal(ref, target?)` registers a ref-managed element for portal rendering and returns an object that includes `sourceParent`.
+- `pp.id()` returns a stable, DOM-safe unique id for the life of that hook slot.
+- `pp.syncExternalStore(subscribe, getSnapshot)` subscribes to a mutable source outside PulsePoint and rerenders when its snapshot changes.
+- `pp.imperativeHandle(ref, createHandle, deps?)` publishes an imperative API on a parent-owned ref instead of the raw DOM node.
+- `pp.transition()` returns `[isPending, startTransition]`.
+- `pp.deferredValue(value, initialValue?)` returns a copy of `value` that catches up one commit later.
+- `pp.optimistic(passthrough, reducer?)` returns `[optimisticState, addOptimistic]`.
+- `pp.errorBoundary()` returns `[error, reset]` and marks the component as an error boundary.
 - `pp.props` exposes the current props.
 
 Global helpers exposed through the `pp` singleton and also merged into the component runtime:
@@ -425,6 +436,12 @@ Notes:
 - Older docs may call the RPC helper `pp.fetchFunction()`. In the current bundled runtime the implemented global API is `pp.rpc()`.
 - Keep template-facing bindings at the top level so the AST-based exporter can see them.
 - For predictable code generation, prefer passing an explicit dependency array to `pp.effect`, `pp.layoutEffect`, `pp.memo`, and `pp.callback`.
+- Top-level destructuring is exported to template scope for every form: array patterns, object patterns, nested patterns, defaults, rest elements, and holes. `const [isPending, startTransition] = pp.transition()` and `const [error, reset] = pp.errorBoundary()` reach the template the same way `pp.state` does.
+- `pp.id()` is derived from the component id plus the hook slot, so the same slot keeps its id across rerenders and two instances of the same component never collide. Use it for `id`/`for` pairing and `aria-*` references instead of hand-rolled counters.
+- `pp.syncExternalStore` requires a referentially stable `subscribe`. Wrap it in `pp.callback(..., [])`, otherwise the store is unsubscribed and resubscribed on every render. The runtime re-reads the snapshot immediately after subscribing so a change that lands between render and subscription is not lost.
+- `pp.transition` does not deprioritize rendering the way React's concurrent scheduler does, because PulsePoint renders synchronously. It does give a correct `isPending` flag for both synchronous and promise-returning scopes, which is the common use (disabling a submit button while `pp.rpc()` resolves). Overlapping scopes stay pending until the last one settles.
+- `pp.optimistic` drops its pending actions as soon as `passthrough` changes, which is the point at which the server has confirmed or rejected the guess. Without a reducer, each action replaces the value.
+- `pp.deferredValue` lags by one commit. Use it to keep an input responsive while an expensive derived subtree catches up.
 
 Effect with cleanup and dependencies:
 
@@ -513,6 +530,160 @@ Portal pattern for overlays that must escape clipping ancestors:
 
 `pp.portal(ref)` moves the ref-managed element to `document.body` by default, or to the element passed as the second argument. Portaled content keeps its logical component ancestry, so context, props, and events keep working.
 
+Stable ids for accessible field pairing:
+
+```html
+<div>
+  <label for="{emailId}">Email</label>
+  <input id="{emailId}" type="email" aria-describedby="{hintId}" />
+  <p id="{hintId}">We never share this.</p>
+
+  <script>
+    const emailId = pp.id();
+    const hintId = pp.id();
+  </script>
+</div>
+```
+
+Never derive ids from an index or a module-level counter. `pp.id()` is the only form that stays stable across rerenders and unique across instances of the same component.
+
+External store subscription:
+
+```html
+<section>
+  <p>{isNarrow ? "Compact layout" : "Wide layout"}</p>
+
+  <script>
+    const subscribe = pp.callback((onStoreChange) => {
+      const query = window.matchMedia("(max-width: 640px)");
+      query.addEventListener("change", onStoreChange);
+      return () => query.removeEventListener("change", onStoreChange);
+    }, []);
+
+    const isNarrow = pp.syncExternalStore(
+      subscribe,
+      () => window.matchMedia("(max-width: 640px)").matches
+    );
+  </script>
+</section>
+```
+
+Prefer this over `pp.state` plus `pp.effect` for anything the component does not own. It reads the snapshot during render and closes the gap between render and subscription, which a hand-rolled effect silently drops.
+
+Imperative handle for a child-owned API. The parent passes its own ref down as an ordinary prop:
+
+```html
+<!-- parent -->
+<div>
+  <button onclick="{dialogControl.current.open()}">Open</button>
+  <x-confirm-dialog control-ref="{dialogControl}" />
+
+  <script>
+    const dialogControl = pp.ref(null);
+  </script>
+</div>
+```
+
+```html
+<!-- ConfirmDialog component -->
+<section>
+  <script>
+    const [open, setOpen] = pp.state(false);
+
+    pp.imperativeHandle(
+      pp.props.controlRef,
+      () => ({
+        open: () => setOpen(true),
+        close: () => setOpen(false),
+      }),
+      []
+    );
+  </script>
+
+  <div hidden="{!open}">
+    <button onclick="{setOpen(false)}">Close</button>
+  </div>
+</section>
+```
+
+Notes:
+
+- A prop whose bound expression evaluates to an object is passed through by reference, so `control-ref="{dialogControl}"` arrives as the real ref object on `pp.props.controlRef`.
+- Do **not** author `pp-ref-forward` to make this work. That attribute is runtime-managed, and `pp-ref` on an `x-*` tag binds the child's root DOM node, which is a different feature. Use a normal prop when the parent needs a child-defined API rather than an element.
+- The handle is published in the layout-effect phase and cleared on unmount, so parents should call into it from event handlers or effects, not during their own render.
+
+Optimistic update around an RPC call:
+
+```html
+<section>
+  <button onclick="{addLike()}">Like ({likes})</button>
+
+  <script>
+    const [confirmedLikes, setConfirmedLikes] = pp.state(pp.props.likes ?? 0);
+    const [likes, addOptimisticLike] = pp.optimistic(
+      confirmedLikes,
+      (state, delta) => state + delta
+    );
+
+    async function addLike() {
+      addOptimisticLike(1);
+      const result = await pp.rpc("like_post", { postId: pp.props.postId });
+      setConfirmedLikes(result.likes);
+    }
+  </script>
+</section>
+```
+
+The optimistic `+1` is discarded the moment `confirmedLikes` changes, so the server value never double-counts the guess.
+
+Transition for pending async work:
+
+```html
+<section>
+  <button onclick="{save()}" disabled="{isSaving}">
+    {isSaving ? "Saving..." : "Save"}
+  </button>
+
+  <script>
+    const [isSaving, startSaving] = pp.transition();
+
+    function save() {
+      startSaving(() => pp.rpc("save_profile", { name: pp.props.name }));
+    }
+  </script>
+</section>
+```
+
+### Error boundaries
+
+`pp.errorBoundary()` marks a component as the recovery point for render and effect failures. Without one, a throwing render is logged to the console and leaves the subtree in whatever state it reached.
+
+```html
+<section>
+  <script>
+    const [error, reset] = pp.errorBoundary();
+  </script>
+
+  <div hidden="{!error}">
+    <p>Something went wrong: {error?.message}</p>
+    <button onclick="{reset()}">Try again</button>
+  </div>
+
+  <div hidden="{!!error}">
+    <x-report-chart />
+  </div>
+</section>
+```
+
+Behavior to rely on:
+
+- Errors thrown during a child's render or effects bubble up the logical component ancestry to the nearest boundary. If nothing catches, the runtime logs `[PP-ERROR] Render Cycle Failed` as before.
+- Unlike React, a boundary also catches throws from its **own** render and effects, because in Caspian the boundary and its fallback markup live in the same single-root component.
+- Effect callbacks and effect cleanups take the same path as render failures, so a throwing subscription teardown is not silently swallowed.
+- The boundary **latches**: it keeps holding the error until `reset()` is called.
+- A boundary absorbs at most five errors without an intervening `reset()`, then logs and stops catching. This stops a fallback that itself throws from spinning the render loop. `reset()` re-arms it.
+- Event handler errors are not routed to boundaries. Handle those with `try`/`catch` inside the handler, which matches React.
+
 ## Context
 
 Context is implemented in the current runtime with a React-style provider pattern rather than a legacy `pp.provideContext(...)` helper. Because Caspian templates are HTML-first, authored provider tags should be written in lowercase HTML form, for example `<themecontext.provider>`, even when the JavaScript token is named `ThemeContext`.
@@ -567,11 +738,11 @@ Consumer example for a child component that receives the token through props:
 
 When a child component needs the same token object, pass it from the provider scope as a prop such as `theme-token="{ThemeContext}"`.
 
-## Props and nested components
-
-In Caspian single-file Python components, the root element's attributes must be authored via `get_attributes(...)` and `{{ attributes }}`; see [components.md](./components.md#receiving-props-in-a-python-component). Attributes accepted from an `x-*` tag but not forwarded to the rendered root are dropped and never reach `pp.props`.
-
-- Child component props are derived from DOM attributes.
+## Props and nested components
+
+In Caspian single-file Python components, the root element's attributes must be authored via `get_attributes(...)` and `{{ attributes }}`; see [components.md](./components.md#receiving-props-in-a-python-component). Attributes accepted from an `x-*` tag but not forwarded to the rendered root are dropped and never reach `pp.props`.
+
+- Child component props are derived from DOM attributes.
 - Attribute names are converted from kebab-case to camelCase for the prop bag.
 - Native `on*` attributes and `pp-component` are not included in props.
 - Empty attributes become boolean `true` props.
@@ -606,6 +777,7 @@ Nested components:
 - Use `pp-spread="{...attrs}"` to spread an object expression into attributes.
 - `pp-spread` omits nullish values, omits known HTML boolean attributes when their value is `false`, emits them bare when `true`, preserves string-valued `aria-*`/`data-*` booleans, and escapes `&`, `"`, and `<` in emitted attribute values.
 - Use plain `key` for keyed diffing. `pp-key` is not implemented.
+- Only top-level declarations in the component script reach template scope, but every destructuring shape is supported there: `const [a, b] = anyTuple()`, `const [, only] = pair`, `const [first = 1, ...rest] = list`, `const [{ id }] = rows`, and the object-pattern forms. A binding declared inside a block or function is not exported.
 
 Example:
 
@@ -889,6 +1061,12 @@ These are current runtime caveats that matter for authors and AI tools:
 - `pp.context()` resolves through ancestor components, not the current component's own pending providers.
 - `pp.provideContext` is not part of the current runtime API. Use an HTML-first lowercase provider tag such as `<themecontext.provider>`.
 - `pp.portal()` preserves logical ancestry through the registry, so context and prop refresh behavior continue to work through portaled descendants.
+- Top-level array destructuring is exported to template scope for any initializer, not only `pp.state` and `pp.reducer`. A binding declared inside a block or function is still not exported.
+- `pp.transition()` does not deprioritize work. PulsePoint renders synchronously; the hook provides an accurate `isPending` flag, not a concurrent scheduler.
+- `pp.syncExternalStore(...)` resubscribes whenever `subscribe` changes identity, so pass a `pp.callback(..., [])`-wrapped function.
+- `pp.optimistic(...)` clears its pending actions on the render where `passthrough` changes, using a render-phase update rather than an effect, so there is no frame showing stale optimistic output.
+- `pp.errorBoundary()` catches render, effect, and effect-cleanup throws, including the boundary component's own. It does not catch event-handler errors. It latches until `reset()` and stops catching after five captures without a reset.
+- `pp.imperativeHandle(...)` needs the parent's ref passed down as an ordinary prop. `pp-ref` on an `x-*` tag is a different feature that binds the child's root DOM node, and `pp-ref-forward` is runtime-managed and must not be authored.
 
 ## Final reminder
 

package/dist/docs/routing.md

@@ -29,9 +29,9 @@ Start with these rules:
 - Put application routes in `src/app/`.
 - For any route that renders a page, put the markup in `index.html`.
 - If a route is UI-only, `index.html` by itself is enough.
-- Add `index.py` only when the same route needs metadata, `page()`, `@rpc()` actions, auth checks, caching, redirects, or other server-side logic.
-- Keep route-specific server logic in that route's `index.py`. Move logic into `src/lib/**` only when it is shared across routes, components, integrations, or features.
-- Use a standalone `index.py` only for non-visual routes such as redirects or action-only handlers.
+- Add `index.py` only when the same route needs metadata, `page()`, `@rpc()` actions, auth checks, caching, redirects, or other server-side logic.
+- Keep route-specific server logic in that route's `index.py`. Move logic into `src/lib/**` only when it is shared across routes, components, integrations, or features.
+- Use a standalone `index.py` only for non-visual routes such as redirects or action-only handlers.
 - When a folder owns child routes, use `layout.html` to wrap them. This is the default pattern for dashboards, admin sections, account areas, settings trees, and route groups.
 - In grouped shells with separate shell and content scrolling, put `pp-reset-scroll="true"` on the content pane in `layout.html` when that pane should reset on child-route navigation while the shell sidebar or rail keeps its own scroll.
 - Use `layout.py` when a layout needs shared props or metadata before rendering. The `layout()` function may be synchronous or async.
@@ -177,17 +177,17 @@ Examples:
 
 Use `index.html` for the route template. This is the route's view layer.
 
-If a route renders visible page content, that content belongs here even when the route also has an `index.py` companion.
-
-Route templates can import reusable Python components with `<!-- @import ... -->` comments and render them with HTML-first `x-*` tags such as `<x-button />`. Use [components.md](./components.md) for the component authoring rules.
-
-Place those import comments at the top of the file, above the authored root element. They are file-level directives, not children of the route root.
-
-Keep route templates as composition, not as the place where all section markup accumulates. A route with tabs, dashboard panels, forms, tables, or repeated cards should import focused components for those responsibilities and assemble them with `x-*` tags. For example, a dashboard route can import `<x-dashboard-header />`, `<x-metric-strip />`, `<x-activity-tab />`, and `<x-settings-tab />` rather than placing every tab panel's full markup in `index.html` or one giant Python component.
+If a route renders visible page content, that content belongs here even when the route also has an `index.py` companion.
+
+Route templates can import reusable Python components with `<!-- @import ... -->` comments and render them with HTML-first `x-*` tags such as `<x-button />`. Use [components.md](./components.md) for the component authoring rules.
+
+Place those import comments at the top of the file, above the authored root element. They are file-level directives, not children of the route root.
+
+Keep route templates as composition, not as the place where all section markup accumulates. A route with tabs, dashboard panels, forms, tables, or repeated cards should import focused components for those responsibilities and assemble them with `x-*` tags. For example, a dashboard route can import `<x-dashboard-header />`, `<x-metric-strip />`, `<x-activity-tab />`, and `<x-settings-tab />` rather than placing every tab panel's full markup in `index.html` or one giant Python component.
 
 Route templates follow the same authored-vs-runtime contract documented in [pulsepoint.md](./pulsepoint.md) and the same single-root discipline documented in [components.md](./components.md): keep one authored parent node, keep any `<!-- @import ... -->` directives above that root, use a plain `<script>` inside that root when needed, and do not handwrite `pp-component` or `type="text/pp"`. That root may be a native HTML element or a single imported `x-*` component tag, but after expansion it must resolve to one final HTML root.
 
-When a route needs button clicks, form submits, input changes, filters, tabs, menus, uploads, polling, or reactive list updates, author those interactions as PulsePoint behavior in `index.html`. Use `onclick`, `oninput`, `onchange`, `onsubmit`, `pp.state(...)`, `pp-for`, refs, effects, and `pp.rpc(...)` instead of starting with `id` attributes plus `document.querySelector(...)` or `addEventListener(...)`. For simple form submits, prefer `onsubmit="{submitForm(event)}"` and `Object.fromEntries(new FormData(event.currentTarget).entries())` over per-input `pp-ref` payload collection.
+When a route needs button clicks, form submits, input changes, filters, tabs, menus, uploads, polling, or reactive list updates, author those interactions as PulsePoint behavior in `index.html`. Use `onclick`, `oninput`, `onchange`, `onsubmit`, `pp.state(...)`, `pp-for`, refs, effects, and `pp.rpc(...)` instead of starting with `id` attributes plus `document.querySelector(...)` or `addEventListener(...)`. For simple form submits, prefer `onsubmit="{submitForm(event)}"` and `Object.fromEntries(new FormData(event.currentTarget).entries())` over per-input `pp-ref` payload collection.
 
 For AI-generated route templates, treat `src/app/**/index.html` the same way you would a React component body: return one parent node that contains the entire route markup. This includes any owned script.
 
@@ -225,32 +225,32 @@ Also bad:
 <aside class="dashboard-help">Tips</aside>
 ```
 
-Also bad:
-
-```html
-<section class="dashboard-shell">
-  <!-- @import StatsCard from "../components" -->
-  <x-stats-card title="Users" value="42" />
-</section>
-```
-
-Correct:
-
-```html
-<!-- @import StatsCard from "../components" -->
-
-<section class="dashboard-shell">
-  <x-stats-card title="Users" value="42" />
-</section>
-```
+Also bad:
+
+```html
+<section class="dashboard-shell">
+  <!-- @import StatsCard from "../components" -->
+  <x-stats-card title="Users" value="42" />
+</section>
+```
+
+Correct:
+
+```html
+<!-- @import StatsCard from "../components" -->
+
+<section class="dashboard-shell">
+  <x-stats-card title="Users" value="42" />
+</section>
+```
 
 Use [pulsepoint.md](./pulsepoint.md) when you need the full authored-vs-rendered example instead of this routing-focused reminder. Use [pulsepoint-runtime-map.md](./pulsepoint-runtime-map.md) when a route task names a specific PulsePoint directive or SPA behavior and you need the owning runtime file quickly.
 
 ### `index.py`
 
-Use `index.py` as the backend companion when a route needs metadata or async server-side logic. For routes that render UI, keep the markup in the sibling `index.html` and let `page()` call `render_page(__file__, ...)`. Do not inline route HTML inside `index.py`.
-
-If the logic belongs only to this route, keep it here. Examples include this page's first-render query, route-owned RPC actions, redirect decisions, route-specific validation, route-specific filters, and route-specific response shaping. Move code into `src/lib/**` when the same logic is reused or intentionally shared; do not extract one-route orchestration into a library just because it is Python code.
+Use `index.py` as the backend companion when a route needs metadata or async server-side logic. For routes that render UI, keep the markup in the sibling `index.html` and let `page()` call `render_page(__file__, ...)`. Do not inline route HTML inside `index.py`.
+
+If the logic belongs only to this route, keep it here. Examples include this page's first-render query, route-owned RPC actions, redirect decisions, route-specific validation, route-specific filters, and route-specific response shaping. Move code into `src/lib/**` when the same logic is reused or intentionally shared; do not extract one-route orchestration into a library just because it is Python code.
 
 Use `index.py` by itself only for non-visual routes such as redirects or action-only handlers. Because Caspian runs on FastAPI, the page entry should be async when it performs async work.
 
@@ -282,9 +282,9 @@ Use that tuple form when one route needs to influence a wrapper without turning
 Example root layout:
 
 ```html
-<body class="{{ layout.dashboard_body_class | default('') }}">
-  <slot />
-</body>
+<body class="{{ layout.dashboard_body_class | default('') }}">
+  <slot />
+</body>
 ```
 
 Example route:
@@ -303,7 +303,7 @@ The key name is arbitrary, but it must match exactly between the dict returned f
 
 Use distinct names for those layout props. In the current router, the second dict is merged into the full layout context after path params and `request`, so a key such as `slug` or `request` can shadow an existing value.
 
-When a route owns a file manager or upload UI, keep the owning upload and delete `@rpc()` actions in that same `index.py` and move reusable filesystem or Prisma helpers into `src/lib/`. Do not move ordinary upload behavior into `main.py`. See [file-uploads.md](./file-uploads.md). When Prisma is enabled, database reads and writes in this route logic or its shared helpers should use the generated Prisma Python ORM.
+When a route owns a file manager or upload UI, keep the owning upload and delete `@rpc()` actions in that same `index.py` and move reusable filesystem or Prisma helpers into `src/lib/`. Do not move ordinary upload behavior into `main.py`. See [file-uploads.md](./file-uploads.md). When Prisma is enabled, database reads and writes in this route logic or its shared helpers should use the generated Prisma Python ORM.
 
 For static and dynamic metadata rules, inheritance order, and social card fields, see [metadata.md](./metadata.md).
 
@@ -349,6 +349,8 @@ Use catch-all routes when the number of path segments is not fixed ahead of time
 
 Add a sibling `index.py` when that catch-all route also needs backend logic or metadata.
 
+If the project uses static export (SSG) and you want a dynamic or catch-all route pre-rendered into the static build, export a `static_paths` provider from that route's `index.py` (Caspian's `getStaticPaths` equivalent). Without it, the static exporter skips the route by design. See [static-export.md](./static-export.md).
+
 ## Route Groups
 
 Wrap a folder name in parentheses to organize code without adding that segment to the URL.
@@ -387,11 +389,11 @@ Resolved SEO fields are exposed to layouts as `{{ metadata.* }}`, while values r
 
 Use `layout.html` for the shared wrapper markup of a subtree. Keep the visible shell here, not in `layout.py`.
 
-Follow the same authoring contract used by route templates: one authored parent node, top-of-file `<!-- @import ... -->` directives above that root, plain `<script>` inside the root when needed, and no handwritten `pp-component` or `type="text/pp"`. See [pulsepoint.md](./pulsepoint.md) for the canonical authored-vs-runtime explanation.
-
-Place child routes with a plain HTML `<slot />` tag. Caspian replaces that layout slot with the current child route or nested layout while rendering.
-
-For example, a page inside `/dashboard/settings` is wrapped by the root layout first and then by the dashboard layout.
+Follow the same authoring contract used by route templates: one authored parent node, top-of-file `<!-- @import ... -->` directives above that root, plain `<script>` inside the root when needed, and no handwritten `pp-component` or `type="text/pp"`. See [pulsepoint.md](./pulsepoint.md) for the canonical authored-vs-runtime explanation.
+
+Place child routes with a plain HTML `<slot />` tag. Caspian replaces that layout slot with the current child route or nested layout while rendering.
+
+For example, a page inside `/dashboard/settings` is wrapped by the root layout first and then by the dashboard layout.
 
 Example root layout:
 
@@ -402,16 +404,16 @@ Example root layout:
     <title>{{ metadata.title }}</title>
     <meta name="description" content="{{ metadata.description }}" />
   </head>
-  <body>
-    <NavBar />
-    <slot />
-  </body>
-</html>
+  <body>
+    <NavBar />
+    <slot />
+  </body>
+</html>
 ```
 
 ### `layout.py`
 
-If a layout needs shared props or metadata, add a `layout.py` file next to the HTML layout. Treat it as the backend companion for the layout, not as the place to author visible wrapper markup.
+If a layout needs shared props or metadata, add a `layout.py` file next to the HTML layout. Treat it as the backend companion for the layout, not as the place to author visible wrapper markup.
 
 When `layout()` calls `render_layout(__file__, ...)`, root-validation errors are attributed to the sibling `layout.html` because that file is the authored template. If `layout()` returns a raw HTML string directly, Caspian treats that value as a runtime fragment instead of an authored template and wraps it in a runtime host root when needed.
 
@@ -441,7 +443,7 @@ In the common case, return a dict and let the sibling `layout.html` read those v
 - `(layout_html, props_dict)`: use the first item as the layout content and expose the second dict as `{{ layout.* }}`
 - `None`: fall back to the sibling `layout.html` with no extra layout props
 
-If you intentionally want to render `layout.html` immediately with direct local variables instead of the `layout.*` namespace, call `render_layout(__file__, {...})` and reference those keys directly in the template. `render_layout(...)` does not create a hidden child outlet; the layout template must still author the real `<slot />` element where child routes should render.
+If you intentionally want to render `layout.html` immediately with direct local variables instead of the `layout.*` namespace, call `render_layout(__file__, {...})` and reference those keys directly in the template. `render_layout(...)` does not create a hidden child outlet; the layout template must still author the real `<slot />` element where child routes should render.
 
 Example:
 
@@ -466,7 +468,7 @@ def layout():
   )
 ```
 
-`layout()` may be synchronous or async in the installed runtime. Keep async layout work focused on shared subtree props or metadata; use `page()` or `@rpc()` when the work belongs to one route or a browser-triggered user action.
+`layout()` may be synchronous or async in the installed runtime. Keep async layout work focused on shared subtree props or metadata; use `page()` or `@rpc()` when the work belongs to one route or a browser-triggered user action.
 
 Use [metadata.md](./metadata.md) when a layout also needs SEO defaults. Return dictionaries from `layout()` for visual or template props, and use `Metadata(...)` for title, description, and social tags.
 
@@ -520,15 +522,15 @@ If an AI agent is choosing where to add or update route code, apply these rules
 - Treat `src/app/` as the routing source of truth.
 - Use folder names to model URL segments.
 - If a route renders UI, create or update `index.html` for the markup.
-- Add `index.py` only when the same route needs metadata or server behavior; do not place route HTML in `index.py`.
-- Keep route-specific backend logic in the route's own `index.py`; extract to `src/lib/**` only for genuinely shared logic.
-- Keep visible page markup in `index.html` and shared subtree shells in `layout.html`; do not place route HTML in `index.py` or layout HTML in `layout.py`.
-- Keep `index.html` as a short assembly of focused `x-*` components. When a route area has its own responsibility, such as a tab panel, settings form, data table, toolbar, or metric section, create a component for that area and pass route data into it as props.
-- Use PulsePoint as the first-party interaction model for route and layout HTML. Avoid custom DOM wiring for normal events and reactivity.
+- Add `index.py` only when the same route needs metadata or server behavior; do not place route HTML in `index.py`.
+- Keep route-specific backend logic in the route's own `index.py`; extract to `src/lib/**` only for genuinely shared logic.
+- Keep visible page markup in `index.html` and shared subtree shells in `layout.html`; do not place route HTML in `index.py` or layout HTML in `layout.py`.
+- Keep `index.html` as a short assembly of focused `x-*` components. When a route area has its own responsibility, such as a tab panel, settings form, data table, toolbar, or metric section, create a component for that area and pass route data into it as props.
+- Use PulsePoint as the first-party interaction model for route and layout HTML. Avoid custom DOM wiring for normal events and reactivity.
 - When the user asks for a dashboard, admin area, account section, or any grouped subtree of child routes, create a parent folder with `layout.html` and place the child routes beneath it. Follow the same mental model as the Next.js App Router.
 - Use a normal folder such as `dashboard/` when the segment should appear in the URL. Use `(group)/` only when the folder should organize or wrap child routes without adding a path segment.
 - Use [cache.md](./cache.md) when an `index.py` route should opt into page-level HTML caching.
-- Use `layout.html` for shared wrappers and `layout.py` for layout-level props or metadata.
+- Use `layout.html` for shared wrappers and `layout.py` for layout-level props or metadata.
 - For grouped shells with separate shell and content scrolling, put `pp-reset-scroll="true"` on the content pane instead of the whole shell when only the page content should reset between child routes.
 - When one route needs to change a parent layout, return `(render_page(__file__, ...), {"dashboard_body_class": ...})` from `page()` and read that value as `{{ layout.dashboard_body_class }}` in the wrapping `layout.html`.
 - Use `layout.py` for layout props that should apply across an entire subtree. Use `render_layout(__file__, {...})` only when the layout should consume direct local variables such as `{{ my_class }}` instead of the standard `{{ layout.* }}` namespace.

package/dist/docs/static-export.md

@@ -0,0 +1,120 @@
+---
+title: Static Export
+description: Use this guide when a Caspian app is exported to static HTML (SSG, like Next.js `output: export`) and previewed over HTTP. Use when the task mentions `npm run static`, `npm run static:serve`, `settings/build-static.py`, `settings/serve-static.py`, static-site generation, `static_paths`, a static preview server, or "the default port is already in use".
+related:
+  title: Related docs
+  description: Static export walks the route/component index and boots the app, so pair it with routing, components, commands, and the metadata guides.
+  links:
+    - /docs/commands
+    - /docs/routing
+    - /docs/components
+    - /docs/metadata
+    - /docs/project-structure
+    - /docs/testing
+    - /docs/index
+---
+
+This page covers exporting a Caspian app to a folder of static HTML (SSG, the equivalent of Next.js `output: export`) and previewing that folder over HTTP with a robust, port-aware local server.
+
+## When This Doc Applies
+
+Read this doc when the task is about:
+
+- exporting the app to static HTML for a static host (Netlify, Vercel, GitHub Pages, nginx, S3, any CDN),
+- previewing the exported `static/` folder over HTTP locally,
+- pre-rendering dynamic routes for a static build,
+- troubleshooting a failing static build or a preview server whose port is already in use.
+
+## Feature Status And Gate
+
+Static export is an **app-owned build convention layered on top of Caspian**, the same category as the `npm run check` quality gate in [testing.md](./testing.md). The framework itself ships no static exporter and no preview server. There is **no `caspian.config.json` flag** for it.
+
+Because it is not a shipped feature, do not assume it exists in every Caspian project. Confirm it in the project first:
+
+- `package.json` defines the `static` and `static:serve` scripts, and
+- `settings/build-static.py` (the exporter) and `settings/serve-static.py` (the preview server) are present.
+
+If those are absent, the project has not adopted static export; do not invent the scripts unless the user asks you to add them.
+
+When `caspian.config.json` has `tailwindcss: true`, the export compiles Tailwind as part of the build (see the build order below). In `backendOnly` projects a static HTML export is usually not meaningful.
+
+## The Two Commands
+
+```bash
+# 1. Export the app to static/  (build metadata + Tailwind, then render every static route)
+npm run static
+
+# 2. Preview the exported static/ folder over HTTP (robust, auto-selects a free port)
+npm run static:serve
+```
+
+### `npm run static` — the exporter
+
+The script is composed so the export always runs against a **fresh route/component index**:
+
+```
+"static": "npm run build && uv run python settings/build-static.py"
+```
+
+`npm run build` is `tailwind:build` **plus** `projectName`. The `projectName` step (`settings/project-name.ts`) regenerates `settings/files-list.json` and `settings/component-map.json` and clears stale `.casp/` and `caches/`. This matters: `settings/build-static.py` boots the app and iterates `get_files_index()`, which reads `settings/files-list.json` — **the route index that decides what gets exported**. If the export ran after only `tailwind:build` (skipping `projectName`), a newly added route or component could be missing from the index and silently never exported, and a removed one could error. Always regenerate metadata before exporting; reuse `npm run build` rather than duplicating just the Tailwind half.
+
+`settings/build-static.py` then:
+
+- boots the real ASGI app in-process and requests every route through Starlette's `TestClient`, so exported HTML is byte-identical to what the dev server serves (layouts, components, PulsePoint deferral, security headers — the whole pipeline),
+- writes each page to `static/<route>/index.html` (`/` → `static/index.html`),
+- mirrors public asset trees (`css`, `js`, `assets`, `uploads`, `favicon.ico`) into `static/`,
+- runs in `APP_ENV=development` so the build does not require production secrets.
+
+**Scope policy is "warn & skip"** — anything that cannot be fully static is reported and NOT written, so nothing broken ships silently:
+
+- **Dynamic routes** (`[id]` / `[...slug]`) are skipped unless their `index.py` exports `static_paths` — Caspian's `getStaticPaths` equivalent. It may be a list of dicts (`[{"id": 1}]`), a list of scalars (`[1, 2]`, mapped onto the route's single param), or a sync/async callable returning either.
+- **Auth-gated routes** redirect instead of returning a page, so they are skipped.
+- **Non-200 or non-HTML** responses are skipped.
+
+**Caveats that hold for ANY static build of a Caspian app** (state them when a user exports an interactive app): `pp.rpc()` server actions, auth/sessions, WebSockets, streaming, and per-request server data do NOT work without the Python backend. Pages that depend on them still render, but those interactions are dead in the output; the exporter flags pages that appear to use `pp.rpc()`. Asset URLs are root-absolute (`/css/...`, `/js/...`), so serve `static/` at a domain root or rewrite the base path for a subdirectory deploy.
+
+### `npm run static:serve` — the preview server
+
+```
+"static:serve": "uv run python settings/serve-static.py"
+```
+
+`settings/serve-static.py` is a hardened local preview server for the exported folder. It exists specifically so an occupied port never aborts the preview — it replaces the fragile `python -m http.server ... 8000` one-liner, which crashes with `address already in use` the moment the port is taken. Its behavior:
+
+- **Auto-selects a free port.** It tries a preferred start port (default `8000`) and walks upward until one binds, then prints the actual URL it landed on. Detection is by genuine bind (no probe race), and it disables `SO_REUSEADDR` so that on Windows a port another process is actively listening on truly fails to bind instead of silently colliding.
+- **Serves only `static/`** — no traversal outside the exported folder — and adds `X-Content-Type-Options: nosniff` and `Cache-Control: no-store`.
+- **Binds loopback `127.0.0.1` by default**, so the preview is not exposed to the local network. Exposing is opt-in via `HOST=0.0.0.0` (only then does it print the LAN URL).
+- **Fails fast** with a clear "build it first" message if `static/` was never exported.
+- **Shuts down cleanly** on Ctrl+C.
+
+Environment overrides (all optional): `HOST` (bind address), `PORT` (preferred start port), `PORT_TRIES` (how many ports to try, default 50). Invalid values fall back to the defaults with a warning instead of crashing.
+
+Preview over HTTP — do **not** double-click `static/index.html` (`file://`): root-absolute asset paths break and browsers block ES module scripts from `file://` origins.
+
+> The preview server's port has nothing to do with the dev BrowserSync ports in `./settings/bs-config.json`. `bs-config.json` is the source of truth for the running **dev** stack; the static preview is a separate process on its own auto-selected port. Read the port the serve command actually prints, not `bs-config.json`.
+
+## Files AI Usually Inspects
+
+- `package.json` — confirm the `static` / `static:serve` scripts and their composition (the export must run `npm run build`, not just `tailwind:build`).
+- `settings/build-static.py` — the exporter: route walking, `static_paths` resolution, skip policy, asset copy.
+- `settings/serve-static.py` — the preview server: port-walk, loopback binding, headers, env overrides.
+- `settings/project-name.ts` — regenerates `settings/files-list.json` and `settings/component-map.json` that the exporter walks.
+- `src/app/**/index.py` — add `static_paths` here to pre-render a dynamic route.
+- `main.py` and the installed `casp` runtime — own the actual render pipeline the exporter drives via `TestClient`; see [core-runtime-map.md](./core-runtime-map.md).
+
+## Verify Before Editing Or Explaining
+
+- Confirm the scripts and both `settings/*.py` files exist before describing static export as available in the project.
+- Confirm the `static` script runs `npm run build` (metadata + Tailwind) before `settings/build-static.py`; a build that only runs `tailwind:build` exports from a stale route index.
+- For any dynamic route the user expects in the output, confirm its `index.py` exports `static_paths`; otherwise it is skipped by design.
+- Read the port the serve command prints; do not assume `8000` or read `settings/bs-config.json` for it.
+- Treat `static/`, `settings/files-list.json`, and `settings/component-map.json` as generated outputs — do not hand-edit them.
+
+## AI Retrieval Notes
+
+- Use this doc when the task names static export, SSG, `output: export`, `npm run static`, `npm run static:serve`, `static_paths`, a static preview server, or a "port already in use" preview problem.
+- Static export is app-owned tooling, not a shipped, config-gated Caspian feature — verify the scripts exist rather than assuming them.
+- To pre-render dynamic routes, add `static_paths` to the route's `index.py` (the `getStaticPaths` equivalent); read [routing.md](./routing.md) for route/segment shape.
+- Warn users that `pp.rpc()`, auth, WebSockets, streaming, and per-request data are inert in a static export; those need the Python backend.
+- The preview server auto-selects a free port and binds loopback by default; exposing on the network (`HOST=0.0.0.0`) is opt-in.
+- See [commands.md](./commands.md) for how `static` relates to `npm run build`, and [testing.md](./testing.md) for the sibling app-owned-convention pattern.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caspian-utils",
-  "version": "0.1.25",
+  "version": "0.2.0",
   "description": "Caspian tooling",
   "main": "index.js",
   "scripts": {