caspian-utils 0.0.29 → 0.0.30

package/dist/docs/file-conventions.md

@@ -0,0 +1,259 @@
+---
+title: File Conventions
+description: Use this page when deciding what belongs in `index.html`, `index.py`, `layout.html`, `layout.py`, `loading.html`, `not-found.html`, or `error.html` in a Caspian app.
+related:
+  title: Related docs
+  description: Use the routing guide for URL and subtree behavior, the structure guide for placement, the metadata guide for SEO fields, the cache guide for route-level caching, and the runtime maps when the task crosses into framework internals.
+  links:
+    - /docs/routing
+    - /docs/project-structure
+    - /docs/metadata
+    - /docs/cache
+    - /docs/pulsepoint
+    - /docs/core-runtime-map
+    - /docs/pulsepoint-runtime-map
+    - /docs/index
+---
+
+This page is the quick decision guide for the special file conventions under `src/app`.
+
+Use it when a task names `index.html`, `index.py`, `layout.html`, `layout.py`, `loading.html`, `not-found.html`, or `error.html`, or when the question is where a page shell, route logic, loading UI, 404 page, or 500 page should live.
+
+Treat `caspian.config.json` and the actual project tree as the source of truth for which features exist in the current workspace. For runtime ownership, verify these rules against:
+
+- `main.py` for global `not-found.html` and `error.html` handling
+- `.venv/Lib/site-packages/casp/layout.py` for `render_page(...)`, `render_layout(...)`, and nested layout behavior
+- `.venv/Lib/site-packages/casp/loading.py` plus `public/js/pp-reactive-v2.js` for `loading.html` collection and SPA loading behavior
+- `.venv/Lib/site-packages/casp/caspian_config.py` for how `index.*`, `layout.html`, and `loading.html` are indexed under `src/app`
+
+## Quick Map
+
+| File | Purpose | Add it when | Verify against |
+| --- | --- | --- | --- |
+| `index.html` | Authored visible page template for a route | The route renders UI | `src/app/**`, `routing.md`, `pulsepoint.md` |
+| `index.py` | Backend companion for route logic and metadata | The route needs `page()`, metadata, auth checks, redirects, caching, or route-owned `@rpc()` actions | `main.py`, `.venv/Lib/site-packages/casp/layout.py` |
+| `layout.html` | Shared shell for a route subtree | Multiple child routes share wrapper markup | `.venv/Lib/site-packages/casp/layout.py`, `routing.md` |
+| `layout.py` | Shared synchronous props and metadata defaults for a subtree | The shared shell needs Python-provided values or metadata | `.venv/Lib/site-packages/casp/layout.py`, `metadata.md` |
+| `loading.html` | Route-scope loading UI used during SPA navigation | A section or page needs an immediate loading state before the next route finishes rendering | `.venv/Lib/site-packages/casp/loading.py`, `public/js/pp-reactive-v2.js` |
+| `not-found.html` | Global 404 page | The app needs a branded fallback for unmatched URLs | `main.py` |
+| `error.html` | Global 500 page | The app needs a safe fallback for unhandled exceptions | `main.py` |
+
+## Authored HTML Rule
+
+For authored route, layout, loading, not-found, and error HTML files, keep exactly one top-level parent HTML element or one imported `x-*` component root.
+
+- Keep any `<!-- @import ... -->` directives above that root.
+- Keep any owned plain `<script>` inside that root, not after it.
+- Do not handwrite `pp-component` or `type="text/pp"`.
+
+This is a runtime requirement, not a style preference.
+
+## `index.html`
+
+`index.html` is the authored page template for a route.
+
+Use it for:
+
+- visible page markup
+- HTML-first `x-*` component usage
+- PulsePoint state, refs, effects, and directives that belong to that route
+- route-local plain `<script>` blocks that stay inside the same root
+
+For any route that renders UI, keep the visible markup here even when the route also has an `index.py` companion.
+
+Example:
+
+```html
+<!-- @import Button from "../../components/Button.py" -->
+
+<section class="space-y-4 p-6">
+  <h1 class="text-2xl font-semibold">Dashboard</h1>
+
+  <x-button onclick="setFilter('open')">
+    Show Open
+  </x-button>
+
+  <script>
+    const [filter, setFilter] = pp.state("all");
+  </script>
+</section>
+```
+
+Use `index.html` by itself when the route is UI-only.
+
+## `index.py`
+
+`index.py` is the backend companion for a route.
+
+Add it when the route needs:
+
+- `page()`
+- metadata
+- auth checks or redirects
+- route-level `Cache(...)`
+- route-owned `@rpc()` actions
+- server-side context before rendering the sibling template
+
+For UI routes, `index.py` does not replace `index.html`. It prepares data and calls `render_page(__file__, ...)` so Caspian renders the sibling template.
+
+Example:
+
+```python
+from casp.layout import Metadata, render_page
+
+metadata = Metadata(
+    title="Dashboard | Caspian",
+    description="Overview page for the dashboard.",
+)
+
+
+async def page(params: dict, request=None):
+    return render_page(__file__, {
+        "slug": params.get("slug"),
+        "has_request": request is not None,
+    })
+```
+
+Current route-parameter behavior:
+
+- path params arrive as a single `params` dict
+- query params can be injected by name
+- `request` is injected by keyword when declared
+
+When one page needs to influence a wrapping layout, `page()` can return `(page_html, layout_props_dict)`.
+
+## `layout.html`
+
+`layout.html` is the shared wrapper for a route subtree.
+
+Use it for:
+
+- shared shell markup such as sidebars, headers, docs rails, or dashboard frames
+- the `[[children|safe]]` insertion point for child routes
+- shared layout props consumed as `[[ layout.* ]]`
+- shared metadata fields consumed as `[[ metadata.* ]]`
+
+Example:
+
+```html
+<div class="docs-shell">
+  <aside class="docs-nav">Docs navigation</aside>
+
+  <main class="docs-content" pp-reset-scroll="true">
+    [[children|safe]]
+  </main>
+</div>
+```
+
+Use nested `layout.html` files for sections like `dashboard/`, `docs/`, `account/`, or route groups such as `(marketing)/`.
+
+In grouped shells with separate shell and content scrolling, put `pp-reset-scroll="true"` on the content pane that should reset on child-route navigation. Leave persistent shell scrollers such as sidebars unmarked when they should keep their own scroll position.
+
+## `layout.py`
+
+`layout.py` is the Python companion for `layout.html`.
+
+Use it for:
+
+- shared synchronous props
+- metadata defaults for everything below that folder
+- small shared layout decisions that belong to the subtree rather than one page
+
+Return `render_layout(__file__), props` so the sibling `layout.html` stays the authored wrapper.
+
+Example:
+
+```python
+from casp.layout import Metadata, render_layout
+
+metadata = Metadata(
+    title="Docs Section | Caspian",
+    description="Shared metadata for the docs subtree.",
+)
+
+
+def layout():
+    return render_layout(__file__), {
+        "shell_class": "docs-shell",
+        "content_class": "docs-shell__content",
+    }
+```
+
+Important runtime detail: `layout()` is synchronous in the installed runtime. Put async I/O in route `page()` functions or route-owned `@rpc()` actions instead of awaiting inside `layout.py`.
+
+## `loading.html`
+
+`loading.html` provides route-scope loading UI for SPA navigation.
+
+The runtime indexes `src/app/**/loading.html` separately from routes and layouts. During navigation, the browser runtime looks for the closest matching loading file by URL scope and falls back up the path toward `/`.
+
+Examples:
+
+- `src/app/loading.html` can act as the root fallback loader
+- `src/app/dashboard/loading.html` applies to `/dashboard` and its descendants unless a closer loading file exists
+- `src/app/(marketing)/loading.html` applies to the grouped subtree even though `(marketing)` does not appear in the URL
+
+To preserve the surrounding shell during navigation, put `pp-loading-content="true"` on the live container that should be swapped during loading, usually the main content pane in a layout.
+
+Example layout shell:
+
+```html
+<main class="docs-content" pp-loading-content="true" pp-reset-scroll="true">
+  [[children|safe]]
+</main>
+```
+
+Example loader:
+
+```html
+<div class="space-y-4 p-6">
+  <div class="h-4 rounded bg-muted animate-pulse"></div>
+  <div class="h-24 rounded bg-muted/70 animate-pulse"></div>
+</div>
+```
+
+If no `pp-loading-content="true"` container exists, the browser runtime falls back to `document.body`.
+
+## `not-found.html`
+
+`src/app/not-found.html` is the global 404 page.
+
+When `main.py` catches a `404`, it looks for this exact root-level file, renders it through the nested layout pipeline, and returns it with a 404 status.
+
+Important scope rule:
+
+- this is a global root-level file, not a per-folder `not-found.html` convention in the current runtime
+
+The runtime passes `request` into the template context and sets default page metadata for the response.
+
+Use this file for branded invalid-URL fallbacks instead of leaving the app on the generic FastAPI or Starlette message.
+
+## `error.html`
+
+`src/app/error.html` is the global 500 page for unhandled exceptions.
+
+When `main.py` catches a general exception, it looks for this exact root-level file, renders it through the nested layout pipeline, and returns it with a 500 status.
+
+The runtime provides these template values:
+
+- `request`
+- `error_message`
+- `error_trace`
+
+In production, `error_trace` is suppressed. Keep this page safe for users and avoid exposing sensitive internals outside development environments.
+
+If rendering `error.html` fails, the runtime falls back to a minimal plain HTML 500 response.
+
+## Decision Rule
+
+Use this order when deciding where a concern belongs:
+
+1. Put visible route markup in `index.html`.
+2. Add `index.py` only when the same route needs backend work.
+3. Put shared subtree wrapper markup in `layout.html`.
+4. Add `layout.py` only when that shared shell needs synchronous Python props or metadata.
+5. Add `loading.html` when SPA navigation needs an immediate scoped loading state.
+6. Use root `not-found.html` for unmatched URLs.
+7. Use root `error.html` for unhandled exceptions.
+
+Use [routing.md](./routing.md) for the broader file-based routing model, [metadata.md](./metadata.md) for page and layout metadata, [cache.md](./cache.md) for route caching in `index.py`, and [pulsepoint.md](./pulsepoint.md) for the authored template contract and browser runtime behavior.

package/dist/docs/index.md

@@ -8,10 +8,11 @@ related:
     - /docs/ai-validation-checklist
     - /docs/installation
     - /docs/commands
-    - /docs/core-runtime-map
-    - /docs/pulsepoint-runtime-map
-    - /docs/mcp
+    - /docs/core-runtime-map
+    - /docs/pulsepoint-runtime-map
+    - /docs/mcp
     - /docs/file-uploads
+    - /docs/file-conventions
     - /docs/project-structure
     - /docs/components
 ---
@@ -24,41 +25,41 @@ The docs can mention optional features even when those features are disabled in
 
 Before making feature, tooling, or file-placement decisions in a Caspian project, read `./caspian.config.json` almost immediately. That file tells you which optional capabilities are enabled, such as Prisma, MCP, TypeScript, Tailwind, backend-only mode, and component scan directories.
 
-## Default Stack
-
-When generating or editing a Caspian app, treat these as the default choices unless the task explicitly requires something else:
+## Default Stack
+
+When generating or editing a Caspian app, treat these as the default choices unless the task explicitly requires something else:
 
 - Use PulsePoint for reactive frontend behavior.
 - Treat every authored route, layout, and component HTML file like a React component return value: exactly one top-level parent HTML element or one imported `x-*` root, with any owned plain `<script>` kept inside that same root.
 - When `caspian.config.json` has `tailwindcss: true`, use Python `merge_classes(...)` plus browser `twMerge(...)` as the only supported Tailwind class-merging path.
-- Use `@rpc()` plus `pp.rpc()` for browser-triggered reads, writes, streaming, and uploads.
-- Use `Validate` and `Rule` from `casp.validate` for server-side input validation and sanitization.
-
-## AI Doc Shape
-
-Each packaged feature doc should help AI answer the same five questions quickly:
-
-- When does this doc apply?
-- Which `caspian.config.json` flag, if any, gates the feature?
-- Which app-owned files usually change?
-- Which `main.py` or installed `casp` runtime files own the behavior?
-- Which behavior should be verified before editing or explaining the feature?
-
-Keep project-specific facts, temporary file inventory, and current app feature flags out of packaged docs. Put those in `AGENTS.md`, `.github/copilot-instructions.md`, or the project code instead.
-
-Use [core-runtime-map.md](./core-runtime-map.md) for Python-side Caspian runtime ownership and [pulsepoint-runtime-map.md](./pulsepoint-runtime-map.md) for browser-side PulsePoint runtime ownership.
-
-## Redundancy Rule
-
-Prefer one canonical explanation plus links from related docs.
-
-- Put the full authored-template and PulsePoint runtime contract in [pulsepoint.md](./pulsepoint.md).
-- Put the full route and layout placement contract in [routing.md](./routing.md).
-- Put the full reusable component contract in [components.md](./components.md).
-- Put the full Python runtime ownership map in [core-runtime-map.md](./core-runtime-map.md).
-- Put the full PulsePoint feature lookup map in [pulsepoint-runtime-map.md](./pulsepoint-runtime-map.md).
-
-Other docs should summarize these rules only when the reminder prevents a common mistake, then link to the canonical page instead of restating the whole rule block.
+- Use `@rpc()` plus `pp.rpc()` for browser-triggered reads, writes, streaming, and uploads.
+- Use `Validate` and `Rule` from `casp.validate` for server-side input validation and sanitization.
+
+## AI Doc Shape
+
+Each packaged feature doc should help AI answer the same five questions quickly:
+
+- When does this doc apply?
+- Which `caspian.config.json` flag, if any, gates the feature?
+- Which app-owned files usually change?
+- Which `main.py` or installed `casp` runtime files own the behavior?
+- Which behavior should be verified before editing or explaining the feature?
+
+Keep project-specific facts, temporary file inventory, and current app feature flags out of packaged docs. Put those in `AGENTS.md`, `.github/copilot-instructions.md`, or the project code instead.
+
+Use [core-runtime-map.md](./core-runtime-map.md) for Python-side Caspian runtime ownership and [pulsepoint-runtime-map.md](./pulsepoint-runtime-map.md) for browser-side PulsePoint runtime ownership.
+
+## Redundancy Rule
+
+Prefer one canonical explanation plus links from related docs.
+
+- Put the full authored-template and PulsePoint runtime contract in [pulsepoint.md](./pulsepoint.md).
+- Put the full route and layout placement contract in [routing.md](./routing.md).
+- Put the full reusable component contract in [components.md](./components.md).
+- Put the full Python runtime ownership map in [core-runtime-map.md](./core-runtime-map.md).
+- Put the full PulsePoint feature lookup map in [pulsepoint-runtime-map.md](./pulsepoint-runtime-map.md).
+
+Other docs should summarize these rules only when the reminder prevents a common mistake, then link to the canonical page instead of restating the whole rule block.
 
 ## Docs Location
 
@@ -72,11 +73,12 @@ The packaged Caspian docs referenced by this index live here:
 - `ai-validation-checklist.md` - workflow and representative prompts for checking whether AI can find the correct Caspian docs, core files, and verification checkpoints
 - `installation.md` - First-time setup flow for creating a new Caspian application
 - `commands.md` - Main Caspian CLI workflows for project creation, generation, updates, and config-aware maintenance
-- `core-runtime-map.md` - map of `main.py` plus installed `casp` modules to the packaged docs that explain them and the behaviors AI should trace there
-- `pulsepoint-runtime-map.md` - fast feature-to-runtime lookup for PulsePoint state, effects, refs, context, portals, lists, events, RPC, uploads, streaming, SPA navigation, scroll restoration, and Tailwind merge behavior
-- `mcp.md` - MCP-specific layout, launch flow, and AI routing rules for projects where `caspian.config.json` enables MCP
+- `core-runtime-map.md` - map of `main.py` plus installed `casp` modules to the packaged docs that explain them and the behaviors AI should trace there
+- `pulsepoint-runtime-map.md` - fast feature-to-runtime lookup for PulsePoint state, effects, refs, context, portals, lists, events, RPC, uploads, streaming, SPA navigation, scroll restoration, and Tailwind merge behavior
+- `mcp.md` - MCP-specific layout, launch flow, and AI routing rules for projects where `caspian.config.json` enables MCP
 - `database.md` - Prisma schema, migration, seed, and client-generation workflow for projects where `caspian.config.json` enables Prisma, plus Python-side helper caveats
 - `auth.md` - Session-backed authentication with `casp.auth`, centralized `auth_config.py`, public-vs-private route mode guidance, RPC-first signout guidance, RBAC, and OAuth provider helpers
+- `file-conventions.md` - quick decision guide for `index.html`, `index.py`, `layout.html`, `layout.py`, `loading.html`, `not-found.html`, and `error.html`, plus the owning runtime files to verify
 - `components.md` - Create reusable Python components, template-backed UI, HTML-first `x-*` component tags, the single-parent authored-root rule for component HTML files, and the Python-side `merge_classes(...)` contract when Tailwind CSS is enabled
 - `pulsepoint.md` - Default reactive frontend runtime contract for component scripts, state, effects, directives, SPA navigation scroll restoration, `pp-reset-scroll`, and direct browser `twMerge(...)` usage when Tailwind CSS is enabled
 - `fetch-data.md` - Initial server-side data loading and browser-triggered RPC flows with `pp.rpc()`, streaming, uploads, and auth-aware actions
@@ -98,13 +100,13 @@ Preferred lookup order:
 2. Read `./caspian.config.json` before making any feature assumption. A doc existing in the package does not mean that feature is enabled in the current project.
 3. Before authoring or editing any `src/app/**` or component HTML template, apply the single-root invariant: one authored root only, any owned `<script>` inside that root, and no handwritten `pp-component` or `type="text/pp"`.
 4. Treat `caspian.config.json` as the single source of truth for optional features. Use feature-specific docs only when the matching flag is enabled. If a feature is disabled and the user wants it, ask first, then update `caspian.config.json` and follow the update workflow in `commands.md`.
-5. If the task touches `main.py` or `.venv/Lib/site-packages/casp/**`, read `core-runtime-map.md` to jump to the controlling runtime file and the matching feature doc.
-6. If the task names a PulsePoint feature or directive, read `pulsepoint-runtime-map.md` for the fastest feature-to-runtime lookup, then read `pulsepoint.md` for authoring rules.
-7. After the feature is confirmed, inspect the actual project files that decide behavior, such as `package.json`, `main.py`, `src/app/**`, `src/lib/**`, `settings/**`, `prisma/**`, and the installed `casp` runtime.
-8. Use `commands.md` for scaffold and update workflows, `project-structure.md` for placement decisions, and the feature docs such as `mcp.md`, `database.md`, `auth.md`, `fetch-data.md`, and `file-uploads.md` for task-specific guidance.
-9. Prefer packaged Caspian docs before upstream documentation when generating code, commands, or migration guidance.
-10. Use `ai-validation-checklist.md` when you want to verify that the docs lead AI to the correct files and behavior checkpoints.
-11. Keep `index.md` and cross-links aligned so AI can quickly discover the right doc.
+5. If the task touches `main.py` or `.venv/Lib/site-packages/casp/**`, read `core-runtime-map.md` to jump to the controlling runtime file and the matching feature doc.
+6. If the task names a PulsePoint feature or directive, read `pulsepoint-runtime-map.md` for the fastest feature-to-runtime lookup, then read `pulsepoint.md` for authoring rules.
+7. After the feature is confirmed, inspect the actual project files that decide behavior, such as `package.json`, `main.py`, `src/app/**`, `src/lib/**`, `settings/**`, `prisma/**`, and the installed `casp` runtime.
+8. Use `file-conventions.md` for quick decisions about `index.html`, `index.py`, `layout.html`, `layout.py`, `loading.html`, `not-found.html`, and `error.html`; use `commands.md` for scaffold and update workflows, `project-structure.md` for placement decisions, and the feature docs such as `mcp.md`, `database.md`, `auth.md`, `fetch-data.md`, and `file-uploads.md` for task-specific guidance.
+9. Prefer packaged Caspian docs before upstream documentation when generating code, commands, or migration guidance.
+10. Use `ai-validation-checklist.md` when you want to verify that the docs lead AI to the correct files and behavior checkpoints.
+11. Keep `index.md` and cross-links aligned so AI can quickly discover the right doc.
 
 ## Maintenance
 

package/dist/docs/routing.md

@@ -33,7 +33,7 @@ Start with these rules:
 - 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 synchronous props or metadata before rendering.
+- Use `layout.py` when a layout needs shared props or metadata before rendering. The `layout()` function may be synchronous or async.
 - Keep visible route and layout markup in `index.html` and `layout.html`. Treat `index.py` and `layout.py` as backend companions, not as places to author visible HTML.
 - Treat every authored route and layout template like a React component body: it must have exactly one top-level parent HTML element or one imported `x-*` root, and any owned plain `<script>` must live inside that same root.
 
@@ -86,7 +86,7 @@ When a user asks for a dashboard, admin area, account section, docs section, or
 
 - Create a parent folder for the section.
 - Add `layout.html` in that folder for the shared shell.
-- Add `layout.py` only when that shared shell needs synchronous props or metadata.
+- Add `layout.py` only when that shared shell needs shared props or metadata.
 - Put each child page in its own route folder with `index.html` and an optional `index.py` companion.
 - Use a normal folder name such as `dashboard/` when the section name should appear in the URL.
 - Use a route-group folder such as `(marketing)/` when the folder should organize code and own a layout without adding a URL segment.

package/package.json

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