caspian-utils 0.1.24 → 0.1.26

package/dist/docs/commands.md

@@ -10,6 +10,7 @@ related:
     - /docs/mcp
     - /docs/file-uploads
     - /docs/routing
+    - /docs/static-export
     - /docs/project-structure
     - /docs/index
 ---
@@ -98,29 +99,51 @@ Only use this when the current project's `package.json` actually defines `npm ru
 
 Do not use `npm run build` as the default validation step for routine route, feature, or documentation edits.
 
+### Export the app to static HTML and preview it
+
+```bash
+# Export to static/ (SSG, like Next.js `output: export`)
+npm run static
+
+# Serve the exported static/ folder over HTTP on an auto-selected free port
+npm run static:serve
+```
+
+Use `npm run static` when the user wants a folder of static HTML for a static host, and `npm run static:serve` to preview that folder locally.
+
+This is an **app-owned build convention**, not a shipped Caspian feature and not gated by a `caspian.config.json` flag. Only use these when the current project's `package.json` actually defines them and `settings/build-static.py` (exporter) and `settings/serve-static.py` (preview server) exist.
+
+Two things AI must keep correct:
+
+- The `static` script must run `npm run build` (Tailwind **and** `projectName`) before `settings/build-static.py`, because the exporter walks the route index in `settings/files-list.json` that `projectName` regenerates. A build that only runs `tailwind:build` can export from a stale route index.
+- `settings/serve-static.py` auto-selects a free port starting at a preferred default (8000) and binds loopback `127.0.0.1` by default; read the port it prints rather than assuming 8000 or reading `settings/bs-config.json` (that file is the dev BrowserSync source of truth, not the static preview).
+
+See [static-export.md](./static-export.md) for the full export scope policy, `static_paths` dynamic-route pre-rendering, and the preview-server security and port behavior.
+
 ### Regenerate ORM after schema changes
 
 ```bash
 npx prisma migrate dev
 
-# If the change requires refreshed seed data:
-npx prisma generate
-# Destructive-data warning: ask the user for explicit approval before running this.
-npx prisma db seed
-
-npx ppy generate
-```
-
-Use when `prisma/schema.prisma` changes and you need migrations, seed flow, and the generated Python ORM layer to stay aligned.
-
-`npx prisma db seed` is a delicate operation because the configured seed script may clean tables or replace existing rows before inserting seed data. Before running it, an AI agent must say the exact command it plans to run, warn that it can delete or overwrite database data, confirm the active datasource when practical, and wait for explicit user approval.
+# If the change requires refreshed seed data:
+npx prisma generate
+# Destructive-data warning: ask the user for explicit approval before running this.
+npx prisma db seed
+
+npx ppy generate
+```
+
+Use when `prisma/schema.prisma` changes and you need migrations, seed flow, and the generated Python ORM layer to stay aligned.
+
+`npx prisma db seed` is a delicate operation because the configured seed script may clean tables or replace existing rows before inserting seed data. Before running it, an AI agent must say the exact command it plans to run, warn that it can delete or overwrite database data, confirm the active datasource when practical, and wait for explicit user approval.
 
 ## 2. Script Guardrails
 
 - Before using an optional feature, confirm its flag in `caspian.config.json`.
 - If the flag is false and the user wants that feature, ask first, then update `caspian.config.json` and run `npx casp update project` before assuming feature-managed files or scripts exist.
 - Do not run `package.json` scripts by default just because source files changed.
-- Treat `npm run dev` and `npm run build` as opt-in workflows.
+- Treat `npm run dev`, `npm run build`, `npm run static`, and `npm run static:serve` as opt-in workflows.
+- Use `npm run static` only when the user wants a static HTML export, and `npm run static:serve` only to preview it. Both are app-owned conventions; confirm the scripts and `settings/build-static.py` / `settings/serve-static.py` exist first.
 - Use `npm run dev` only when the user explicitly asks to start the local stack or the task truly needs that running workflow.
 - Use `npm run build` only for deployment prep or an explicit build request.
 - Treat `public/css/styles.css`, `settings/component-map.json`, `settings/files-list.json`, `__pycache__/`, and `.pyc` files as generated outputs when a script intentionally runs.
@@ -182,12 +205,12 @@ In skip-prompt mode, the default feature values are:
 
 - `backendOnly: false`
 - `tailwindcss: false`
-- `typescript: false`
-- `mcp: false`
-- `prisma: false`
-- `websocket: false`
-
-If a project needs WebSockets after creation, set `websocket: true` in `caspian.config.json`, then run the project update workflow so framework-managed files and any scaffolded socket surfaces stay aligned before assuming `@app.websocket(...)` routes or `src/lib/websocket/**` exist.
+- `typescript: false`
+- `mcp: false`
+- `prisma: false`
+- `websocket: false`
+
+If a project needs WebSockets after creation, set `websocket: true` in `caspian.config.json`, then run the project update workflow so framework-managed files and any scaffolded socket surfaces stay aligned before assuming `@app.websocket(...)` routes or `src/lib/websocket/**` exist.
 
 ### 4.2 Backend-only combinations
 
@@ -598,18 +621,18 @@ The create and update commands above are not the whole maintenance story for a P
 ```bash
 npx prisma migrate dev
 
-# Only when seed flow or prisma/seed.ts depends on the new schema:
-npx prisma generate
-# Destructive-data warning: ask the user for explicit approval before running this.
-npx prisma db seed
-
-npx ppy generate
-```
+# Only when seed flow or prisma/seed.ts depends on the new schema:
+npx prisma generate
+# Destructive-data warning: ask the user for explicit approval before running this.
+npx prisma db seed
+
+npx ppy generate
+```
 
 Use this order:
 
 1. Run `npx prisma migrate dev` first so migrations and the development database stay aligned.
-2. If `prisma/seed.ts` or seed data depends on the new schema, run `npx prisma generate`, then request explicit user approval before running `npx prisma db seed` because the seed script may delete or overwrite database data.
+2. If `prisma/seed.ts` or seed data depends on the new schema, run `npx prisma generate`, then request explicit user approval before running `npx prisma db seed` because the seed script may delete or overwrite database data.
 3. Run `npx ppy generate` last so the generated Python ORM layer matches the updated Prisma schema.
 
 Do not manually create or edit these generated files:
@@ -637,6 +660,8 @@ See [database.md](./database.md) for the full schema, migration, seed, and async
 | Update current project to beta safely in PowerShell | `npx casp update project --tag beta` |
 | Update current project to an exact version | `npx casp update project --version 1.2.3 -y` |
 | Regenerate Python ORM after schema changes | `npx prisma migrate dev` then optional seed commands, then `npx ppy generate` |
+| Export the app to static HTML (SSG) | `npm run static` (when the project defines it) |
+| Preview the exported static build over HTTP | `npm run static:serve` (auto-selects a free port) |
 
 ## 10. Configuration Notes
 
@@ -682,8 +707,9 @@ If an AI agent is deciding which command flow to use, apply these rules first.
 - Treat `--tailwindcss` and `--typescript` as frontend-oriented flags. They are not meaningful in normal backend-only scaffolds.
 - Treat starter kit defaults as a base layer that can be overridden by explicit flags.
 - Read `caspian.config.json` before running update commands.
-- When `prisma/schema.prisma` changes, run `npx prisma migrate dev` first, then any required seed refresh, then `npx ppy generate`. Before running `npx prisma db seed`, warn the user that it can delete or overwrite data and wait for explicit approval.
+- When `prisma/schema.prisma` changes, run `npx prisma migrate dev` first, then any required seed refresh, then `npx ppy generate`. Before running `npx prisma db seed`, warn the user that it can delete or overwrite data and wait for explicit approval.
 - Never hand-edit generated Python ORM files under `src/lib/prisma/` or `settings/prisma-schema.json`.
 - Read [database.md](./database.md) before generating Prisma schema, migration, seed, or ORM guidance.
+- Read [static-export.md](./static-export.md) before generating or explaining static export (`npm run static`), dynamic-route pre-rendering with `static_paths`, or the `npm run static:serve` preview server. Confirm the scripts and `settings/build-static.py` / `settings/serve-static.py` exist first.
 - Read [routing.md](./routing.md) before generating or modifying route folders under `src/app/`.
 - Read [project-structure.md](./project-structure.md) before placing generated files into the project.

package/dist/docs/index.md

@@ -95,6 +95,7 @@ The packaged Caspian docs referenced by this index live here:
 - `metadata.md` - Static and dynamic metadata, SEO inheritance, and Open Graph or Twitter card tags
 - `routing.md` - Next.js App Router-style file-based routing with `src/app`, dynamic segments, dashboard and section layouts, route groups, nested layouts, shared-shell scroll-reset ownership, single-parent authored templates, and backend Python companions that do not own visible markup
 - `project-structure.md` - Default Caspian layout and where route files, reusable UI in `src/components/`, reusable non-UI code in `src/lib/`, and database files belong
+- `static-export.md` - App-owned static HTML export (SSG, like Next.js `output: export`) via `npm run static`/`settings/build-static.py`, dynamic-route pre-rendering with `static_paths`, and the robust port-aware preview server `npm run static:serve`/`settings/serve-static.py`; not a shipped feature and not gated by a `caspian.config.json` flag, so verify the scripts exist in the project
 - `testing.md` - Recommended app-owned testing, type-checking, and linting gate over `main.py` and `src/**` (pyright + ruff + pytest behind one command, so the gate and Pylance in the editor report the same thing), plus the auto-fix command and why ruff must not auto-delete component imports used as `<x-*>` tags (F401 unfixable); not a shipped feature and not gated by a `caspian.config.json` flag, so verify the actual command, tools, and config in the project
 
 ## AI Retrieval Notes
@@ -118,6 +119,7 @@ Preferred lookup order:
 13. Use `ai-validation-checklist.md` when you want to verify that the docs lead AI to the correct files and behavior checkpoints.
 14. Keep `index.md` and cross-links aligned so AI can quickly discover the right doc.
 15. If the task is about tests, type checking, linting, a quality gate, CI checks, or making an app production-ready, read `testing.md`. It is an app-owned convention (not a shipped feature and not gated by a `caspian.config.json` flag), so confirm the actual gate command in `package.json`, the orchestrator in `settings/`, and the tools and config in `pyproject.toml` before assuming they exist.
+16. If the task is about static export, static-site generation, `output: export`-style output, previewing a static build over HTTP, pre-rendering dynamic routes, or a preview server whose port is already in use, read `static-export.md`. It is also an app-owned convention (not a shipped feature, not gated by a `caspian.config.json` flag), so confirm `settings/build-static.py`, `settings/serve-static.py`, and the `static`/`static:serve` scripts exist in the project before assuming static export is available.
 
 ## Maintenance
 

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/dist/docs/testing.md

@@ -80,7 +80,8 @@ ignore = ["E501"]
 [tool.pyright]
 # Pylance (the VS Code Python extension) reads this same config, so the editor
 # and `npm run check` report the same thing instead of disagreeing.
-include = ["main.py", "src"]
+# `settings/*.py` is included so the orchestrator scripts are type-checked too.
+include = ["main.py", "src", "settings/*.py"]
 exclude = [".venv", "node_modules", "**/__pycache__"]
 # `basic` is Pylance's default mode. It catches reportArgumentType-style bugs
 # (e.g. passing a dict[str, str | None] to a TypedDict whose field is `str`)

package/package.json

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