caspian-utils 0.0.25 → 0.0.27

package/dist/docs/ai-validation-checklist.md

@@ -58,9 +58,12 @@ Use prompts like these to check whether AI lands on the correct docs and files.
 | Add a file manager page with upload progress and persisted metadata. | [index.md](./index.md), [file-uploads.md](./file-uploads.md), [fetch-data.md](./fetch-data.md), [database.md](./database.md) | `src/app/**/index.html`, `src/app/**/index.py`, `src/lib/**`, `prisma/schema.prisma` when Prisma applies | route-owned upload actions, persisted metadata flow, and Prisma-backed storage boundaries |
 | Explain why authored Caspian templates use a plain `<script>` instead of `type="text/pp"`. | [index.md](./index.md), [pulsepoint.md](./pulsepoint.md), [components.md](./components.md), [routing.md](./routing.md) | `main.py`, `.venv/Lib/site-packages/casp/scripts_type.py`, `.venv/Lib/site-packages/casp/components_compiler.py` | script rewriting, `pp-component` injection, and authored-vs-runtime boundaries |
 | Debug why `StateManager` does not persist across a full redirect. | [index.md](./index.md), [state.md](./state.md), [auth.md](./auth.md), [core-runtime-map.md](./core-runtime-map.md) | `main.py`, `.venv/Lib/site-packages/casp/state_manager.py` | wire vs non-wire reset behavior and `request.state.session` dependency |
-| Trace the auth cookie and CSRF cookie names used in development. | [index.md](./index.md), [auth.md](./auth.md), [core-runtime-map.md](./core-runtime-map.md) | `main.py`, `.venv/Lib/site-packages/casp/auth.py` | development cookie scoping and CSRF or session naming ownership |
-| Find how route params and query params reach `page()`. | [index.md](./index.md), [routing.md](./routing.md), [core-runtime-map.md](./core-runtime-map.md) | `main.py`, `.venv/Lib/site-packages/casp/layout.py` | path-dict delivery, query coercion, and `request` injection |
-| Decide whether a dashboard child route should use page caching. | [index.md](./index.md), [cache.md](./cache.md), [routing.md](./routing.md), [fetch-data.md](./fetch-data.md) | `main.py`, `.venv/Lib/site-packages/casp/cache_handler.py`, the route's `index.py` | route-level cache ownership, cacheable HTML scope, and invalidation points |
+| Trace the auth cookie and CSRF cookie names used in development. | [index.md](./index.md), [auth.md](./auth.md), [core-runtime-map.md](./core-runtime-map.md) | `main.py`, `.venv/Lib/site-packages/casp/auth.py` | development cookie scoping and CSRF or session naming ownership |
+| Find how route params and query params reach `page()`. | [index.md](./index.md), [routing.md](./routing.md), [core-runtime-map.md](./core-runtime-map.md) | `main.py`, `.venv/Lib/site-packages/casp/layout.py` | path-dict delivery, query coercion, and `request` injection |
+| Decide whether a dashboard child route should use page caching. | [index.md](./index.md), [cache.md](./cache.md), [routing.md](./routing.md), [fetch-data.md](./fetch-data.md) | `main.py`, `.venv/Lib/site-packages/casp/cache_handler.py`, the route's `index.py` | route-level cache ownership, cacheable HTML scope, and invalidation points |
+| Add a PulsePoint context provider to a reusable component. | [index.md](./index.md), [pulsepoint-runtime-map.md](./pulsepoint-runtime-map.md), [pulsepoint.md](./pulsepoint.md), [components.md](./components.md) | `public/js/pp-reactive-v2.js`, component `.html`, `.venv/Lib/site-packages/casp/components_compiler.py` | `Context.Provider` usage, logical ancestry, single-root template shape |
+| Add upload progress to an existing file manager. | [index.md](./index.md), [pulsepoint-runtime-map.md](./pulsepoint-runtime-map.md), [file-uploads.md](./file-uploads.md), [fetch-data.md](./fetch-data.md) | `src/app/**/index.py`, `src/app/**/index.html`, `src/lib/**`, `public/js/pp-reactive-v2.js` | `pp.rpc` upload options, state replacement, persisted metadata, BrowserSync ignore rules |
+| Decide whether MCP files should be created. | [index.md](./index.md), [mcp.md](./mcp.md), [commands.md](./commands.md), [project-structure.md](./project-structure.md) | `caspian.config.json`, `settings/restart-mcp.ts`, `package.json`, `src/lib/mcp/**` when enabled | `mcp` feature gate, update workflow, nested FastMCP config ownership |
 
 Treat the table as a prompt pack for spot checks, not as a full validation matrix.
 

package/dist/docs/cache.md

@@ -26,11 +26,18 @@ Import the API like this:
 from casp.cache_handler import Cache, CacheHandler
 ```
 
-The current installed implementation lives in `.venv/Lib/site-packages/casp/cache_handler.py`.
-
-Use [core-runtime-map.md](./core-runtime-map.md) when a cache task crosses `main.py` request flow, cache lookup timing, and the installed cache-handler internals.
-
-The real API surface is:
+The current installed implementation lives in `.venv/Lib/site-packages/casp/cache_handler.py`.
+
+Use [core-runtime-map.md](./core-runtime-map.md) when a cache task crosses `main.py` request flow, cache lookup timing, and the installed cache-handler internals.
+
+## Source Of Truth
+
+- Route cache intent belongs in `src/app/**/index.py` through module-level `cache_settings = Cache(...)`.
+- Cache lookup and save timing are controlled by `main.py`.
+- Disk-backed cache behavior lives in `.venv/Lib/site-packages/casp/cache_handler.py`.
+- Cache invalidation after writes usually belongs in the owning route `@rpc()` action or a shared helper under `src/lib/**`.
+
+The real API surface is:
 
 - declarative route config with `Cache(ttl=..., enabled=...)`
 - disk-backed HTML lookup with `CacheHandler.serve_cache(...)`

package/dist/docs/components.md

@@ -7,9 +7,10 @@ related:
   links:
     - /docs/project-structure
     - /docs/core-runtime-map
-    - /docs/routing
-    - /docs/pulsepoint
-    - /docs/fetch-data
+    - /docs/routing
+    - /docs/pulsepoint
+    - /docs/pulsepoint-runtime-map
+    - /docs/fetch-data
     - /docs/index
 ---
 
@@ -39,7 +40,7 @@ When the task is about component internals rather than normal app-owned componen
 - `.venv/Lib/site-packages/casp/html_attrs.py` owns `get_attributes(...)` and the Python-side `merge_classes(...)` contract.
 - `.venv/Lib/site-packages/casp/syntax_compiler.py` owns Caspian template syntax transpilation before Jinja render.
 
-Use [core-runtime-map.md](./core-runtime-map.md) when you need the broader runtime-module map.
+Use [core-runtime-map.md](./core-runtime-map.md) when you need the broader Python runtime-module map. Use [pulsepoint-runtime-map.md](./pulsepoint-runtime-map.md) when a component task is specifically about browser-side PulsePoint state, refs, context, portals, events, RPC, or SPA behavior.
 
 ## Basic Component
 

package/dist/docs/core-runtime-map.md

@@ -8,9 +8,10 @@ related:
     - /docs/project-structure
     - /docs/routing
     - /docs/auth
-    - /docs/fetch-data
-    - /docs/pulsepoint
-    - /docs/index
+    - /docs/fetch-data
+    - /docs/pulsepoint
+    - /docs/pulsepoint-runtime-map
+    - /docs/index
 ---
 
 This page maps the app entry point and the installed Caspian runtime modules to the packaged docs that explain them.
@@ -24,21 +25,60 @@ Use it when you already know a behavior is controlled by `main.py` or `.venv/Lib
 - the task is about framework internals rather than normal app-owned route or component code
 - AI needs to know which packaged doc should be kept aligned with a core-file change
 
-## App Entry Point
+## App Entry Point
 
 | Concern | Core file | Read first | Why it matters |
 | --- | --- | --- | --- |
 | App bootstrap and request flow | [main.py](../../../../main.py) | [project-structure.md](./project-structure.md), [routing.md](./routing.md), [auth.md](./auth.md) | FastAPI app creation, static asset routes, middleware order, route registration, cache check and save, exception handlers, and final HTML transforms all live here. |
-| Browser runtime, SPA navigation, and scroll restoration | [public/js/pp-reactive-v2.js](../../../../public/js/pp-reactive-v2.js) | [pulsepoint.md](./pulsepoint.md), [fetch-data.md](./fetch-data.md) | The shipped `pp` runtime, same-origin SPA interception, per-history-entry scroll state, `pp-reset-scroll` behavior, and browser RPC helpers live here. |
-
-Important current `main.py` behaviors AI should keep in mind:
+| Browser runtime, SPA navigation, and scroll restoration | [public/js/pp-reactive-v2.js](../../../../public/js/pp-reactive-v2.js) | [pulsepoint.md](./pulsepoint.md), [fetch-data.md](./fetch-data.md) | The shipped `pp` runtime, same-origin SPA interception, per-history-entry scroll state, `pp-reset-scroll` behavior, and browser RPC helpers live here. |
+
+Important current `main.py` behaviors AI should keep in mind:
 
 - In development, `_scoped_cookie_name(...)` appends the active BrowserSync or dev port to both the session cookie name and the CSRF cookie name. The scope is resolved from `CASPIAN_BROWSER_SYNC_PORT`, then `settings/bs-config.json`, then `PORT`.
 - `register_single_route(...)` passes path params to `page()` as one positional dict, injects matching query params by name, and injects `request` by keyword when declared.
 - The render pipeline is `transform_components(...)`, then `render_with_nested_layouts(...)`, then `transform_scripts(...)`.
 - Route-level generators returned from `page()` are wrapped in `SSE(...)` before the response is sent.
 - Middleware is added in source order as `RPCMiddleware`, `AuthMiddleware`, `CSRFMiddleware`, `SessionMiddleware`, so the effective request order is reversed at runtime.
-- `public/js/pp-reactive-v2.js` saves scroll positions per history entry, resets window scroll on push navigation, and uses `pp-reset-scroll="true"` to opt specific containers or the whole body into reset behavior.
+- `public/js/pp-reactive-v2.js` saves scroll positions per history entry, resets window scroll on push navigation, and uses `pp-reset-scroll="true"` to opt specific containers or the whole body into reset behavior.
+
+## Caspian Core Feature Map
+
+Use this table when the task names a framework feature but the owning file is not obvious yet.
+
+| Core feature | App-owned entry points | Runtime owner | Packaged docs |
+| --- | --- | --- | --- |
+| Feature flags and generated surface area | `caspian.config.json` | `casp.caspian_config` | [commands.md](./commands.md), [project-structure.md](./project-structure.md) |
+| File-based routing | `src/app/**/index.html`, `src/app/**/index.py` | `main.py`, `casp.layout`, `casp.caspian_config` | [routing.md](./routing.md) |
+| Nested layouts | `src/app/**/layout.html`, `src/app/**/layout.py` | `casp.layout`, `main.py` | [routing.md](./routing.md), [metadata.md](./metadata.md) |
+| Metadata | route or layout `metadata`, runtime metadata helpers | `casp.layout`, `main.py` | [metadata.md](./metadata.md), [routing.md](./routing.md) |
+| Component imports and `x-*` tags | `src/components/**`, `src/app/**/*.html` | `casp.components_compiler`, `casp.component_decorator` | [components.md](./components.md), [routing.md](./routing.md) |
+| Auth and route protection | `src/lib/auth/auth_config.py`, `main.py`, route decorators | `casp.auth`, `main.py` middleware | [auth.md](./auth.md) |
+| RPC and server actions | route or component Python modules with `@rpc()` | `casp.rpc`, `main.py` middleware | [fetch-data.md](./fetch-data.md), [file-uploads.md](./file-uploads.md) |
+| Streaming | route `page()` generators, RPC generators | `casp.streaming`, `casp.rpc`, `main.py` | [fetch-data.md](./fetch-data.md) |
+| Server state | request handlers and RPC actions | `casp.state_manager`, `main.py` middleware | [state.md](./state.md) |
+| Page caching | route-level `Cache(...)` declarations | `casp.cache_handler`, `main.py` cache check/save | [cache.md](./cache.md) |
+| Validation | route and RPC input boundaries | `casp.validate` | [validation.md](./validation.md) |
+| Tailwind class merge | Python components and PulsePoint templates | `casp.html_attrs`, browser `twMerge(...)` | [components.md](./components.md), [pulsepoint.md](./pulsepoint.md) |
+| Prisma persistence | `prisma/**`, `src/lib/prisma/**`, route/RPC code | generated Prisma and Python clients | [database.md](./database.md), [fetch-data.md](./fetch-data.md) |
+| MCP tools | `src/lib/mcp/**` when enabled | app-owned FastMCP server | [mcp.md](./mcp.md), [commands.md](./commands.md) |
+
+For browser-side PulsePoint details, use [pulsepoint-runtime-map.md](./pulsepoint-runtime-map.md) instead of expanding this Python-runtime map.
+
+## Task-To-File Examples
+
+Protected dashboard route:
+
+1. Check `caspian.config.json` for enabled features such as Prisma and Tailwind.
+2. Read [routing.md](./routing.md) for the section layout shape.
+3. Read [auth.md](./auth.md) for route privacy and decorators.
+4. Update `src/app/dashboard/layout.html` for the shared shell and child `index.html` or `index.py` files for page-specific behavior.
+5. Verify auth bootstrap and middleware ownership in `main.py` only if route protection behaves unexpectedly.
+
+Interactive CRUD page:
+
+1. Read [fetch-data.md](./fetch-data.md) for the `page()` plus `@rpc()` split.
+2. Read [pulsepoint-runtime-map.md](./pulsepoint-runtime-map.md) for browser-side `pp.rpc(...)` behavior.
+3. Keep first-render data in `src/app/**/index.py`, visible markup in `src/app/**/index.html`, reusable helpers in `src/lib/**`, and database schema changes in `prisma/**`.
 
 ## Installed Runtime Map
 

package/dist/docs/fetch-data.md

@@ -12,9 +12,10 @@ related:
     - /docs/database
     - /docs/file-uploads
     - /docs/cache
-    - /docs/routing
-    - /docs/pulsepoint
-    - /docs/project-structure
+    - /docs/routing
+    - /docs/pulsepoint
+    - /docs/pulsepoint-runtime-map
+    - /docs/project-structure
     - /docs/index
 ---
 
@@ -139,10 +140,11 @@ Validate incoming form and mutation payloads before persisting them. See [valida
 
 If an RPC action needs transient request-scoped success or error state beyond its direct return payload, read [state.md](./state.md) and verify the current wire-request lifecycle before depending on persistence across navigations or full-page reloads.
 
-Important:
-
-- `pp.rpc()` posts to the current route RPC bridge.
-- Older docs may refer to `pp.fetchFunction()`. In this repo's current runtime, the supported helper is `pp.rpc()`.
+Important:
+
+- `pp.rpc()` posts to the current route RPC bridge.
+- Older docs may refer to `pp.fetchFunction()`. In this repo's current runtime, the supported helper is `pp.rpc()`.
+- Use [pulsepoint-runtime-map.md](./pulsepoint-runtime-map.md) when debugging browser-side RPC options such as streaming, upload progress, abort behavior, redirects, or SPA interaction.
 
 ## Streaming Responses
 

package/dist/docs/file-uploads.md

@@ -16,11 +16,20 @@ related:
 
 This page documents the recommended file upload and file manager pattern for Caspian projects.
 
-Treat uploads as normal route behavior. Keep the owning browser UI in the route template, keep upload and delete `@rpc()` actions in the owning route `index.py`, and move reusable storage or persistence helpers into `src/lib/`.
-
-If the file manager lives inside a grouped subtree such as a dashboard, account area, or admin area, apply the section layout pattern from [routing.md](./routing.md): keep the shared shell in the parent folder's `layout.html` and keep the file-manager route itself in a child folder.
-
-## Default Pattern
+Treat uploads as normal route behavior. Keep the owning browser UI in the route template, keep upload and delete `@rpc()` actions in the owning route `index.py`, and move reusable storage or persistence helpers into `src/lib/`.
+
+If the file manager lives inside a grouped subtree such as a dashboard, account area, or admin area, apply the section layout pattern from [routing.md](./routing.md): keep the shared shell in the parent folder's `layout.html` and keep the file-manager route itself in a child folder.
+
+## Source Of Truth
+
+- File picker UI and upload progress state belong in `src/app/**/index.html`.
+- Upload, delete, and list refresh actions belong in the owning `src/app/**/index.py` as `@rpc()` actions.
+- Reusable storage, naming, and persistence helpers belong in `src/lib/**`.
+- Durable metadata belongs in Prisma when `caspian.config.json` enables Prisma.
+- Browser-side progress, state replacement, and `pp-for` list rendering follow [pulsepoint-runtime-map.md](./pulsepoint-runtime-map.md).
+- BrowserSync upload ignore behavior belongs in `settings/bs-config.ts`.
+
+## Default Pattern
 
 - Keep first-render file manager data in `page()` so the initial HTML already contains the current asset list and storage summary.
 - Keep upload and delete actions in the route's `index.py`; do not move ordinary upload flows into `main.py`.

package/dist/docs/index.md

@@ -8,8 +8,9 @@ related:
     - /docs/ai-validation-checklist
     - /docs/installation
     - /docs/commands
-    - /docs/core-runtime-map
-    - /docs/mcp
+    - /docs/core-runtime-map
+    - /docs/pulsepoint-runtime-map
+    - /docs/mcp
     - /docs/file-uploads
     - /docs/project-structure
     - /docs/components
@@ -23,15 +24,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.
+- 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
 
@@ -45,8 +72,9 @@ 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
-- `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
 - `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
@@ -70,12 +98,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. 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.
-7. 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.
-8. Prefer packaged Caspian docs before upstream documentation when generating code, commands, or migration guidance.
-9. Use `ai-validation-checklist.md` when you want to verify that the docs lead AI to the correct files and behavior checkpoints.
-10. 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 `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/metadata.md

@@ -12,9 +12,17 @@ related:
 
 This page explains how Caspian handles document metadata, SEO fields, and social sharing tags.
 
-At render time, Caspian resolves metadata through the layout engine and exposes the merged result to templates as `[[ metadata.* ]]`.
-
-## Overview
+At render time, Caspian resolves metadata through the layout engine and exposes the merged result to templates as `[[ metadata.* ]]`.
+
+## Source Of Truth
+
+- Metadata objects and layout merge behavior are implemented in `.venv/Lib/site-packages/casp/layout.py`.
+- Route registration and runtime metadata collection are controlled by `main.py`.
+- Shared metadata defaults belong in `src/app/**/layout.py`.
+- Page-specific static or dynamic metadata belongs in `src/app/**/index.py`.
+- Rendered metadata is consumed from layout templates through `[[ metadata.* ]]`.
+
+## Overview
 
 Caspian uses a cascading metadata model similar to the Next.js App Router. Define defaults high in the tree, then override them closer to the final route.
 

package/dist/docs/pulsepoint-runtime-map.md

@@ -0,0 +1,129 @@
+---
+title: PulsePoint Runtime Map
+description: Use this page when AI needs a fast feature-to-runtime lookup for PulsePoint behavior before editing `src/app/**`, component templates, or `public/js/pp-reactive-v2.js`.
+related:
+  title: Related docs
+  description: Use the PulsePoint guide for authoring rules, the routing and component guides for template placement, and the core runtime map when Python-side transforms are involved.
+  links:
+    - /docs/pulsepoint
+    - /docs/routing
+    - /docs/components
+    - /docs/fetch-data
+    - /docs/core-runtime-map
+    - /docs/index
+---
+
+This page is the quick AI routing layer for PulsePoint core features.
+
+Use [pulsepoint.md](./pulsepoint.md) for the full authoring contract. Use this file when you need to jump from a feature name, directive, or runtime symptom to the files and behavior checkpoints that matter.
+
+## Source Of Truth
+
+- `public/js/pp-reactive-v2.js` is the shipped browser runtime.
+- `main.py` owns the final render pipeline that calls `transform_components(...)` and `transform_scripts(...)`.
+- `.venv/Lib/site-packages/casp/components_compiler.py` injects `pp-component` after component expansion and validates the single-root contract.
+- `.venv/Lib/site-packages/casp/scripts_type.py` rewrites authored body `<script>` tags to `type="text/pp"`.
+- `.venv/Lib/site-packages/casp/html_attrs.py` owns Python-side class and attribute helpers such as `merge_classes(...)`.
+
+If an inspected browser DOM disagrees with authored template source, remember that the runtime DOM includes framework-managed output. Do not copy runtime-only attributes back into authored templates.
+
+## Feature Map
+
+| PulsePoint feature | Authoring surface | Runtime owner | Verify before changing |
+| --- | --- | --- | --- |
+| Component roots | `src/app/**/index.html`, `layout.html`, component `.html` files | `components_compiler.py`, `pp-reactive-v2.js` | one authored root, final expanded root receives one `pp-component`, no sibling scripts |
+| Component scripts | plain `<script>` inside the authored root | `scripts_type.py`, `pp-reactive-v2.js` | authored scripts are plain, runtime scripts become `type="text/pp"`, one owned script per root |
+| Template expressions | text and attributes with `{...}` | `pp-reactive-v2.js` | top-level script bindings are exported, nested bindings are not assumed |
+| State | `pp.state(initial)` | `pp-reactive-v2.js` | setters accept values or updater functions, state belongs to the component instance |
+| Effects | `pp.effect(...)`, `pp.layoutEffect(...)` | `pp-reactive-v2.js` | callbacks may return cleanup functions, promises are not awaited |
+| Refs | `pp.ref(...)`, `pp-ref` | `pp-reactive-v2.js` | generated ref internals are runtime-managed; do not author `data-pp-ref` |
+| Context | `pp.createContext(...)`, `<Context.Provider>`, `pp.context(token)` | `pp-reactive-v2.js` | ancestry is logical component ancestry; do not invent `pp-context` or `pp.provideContext` |
+| Portals | `pp.portal(ref, target?)` | `pp-reactive-v2.js` | context should preserve logical ancestry through the registry |
+| Lists | `<template pp-for="item in items">` | `pp-reactive-v2.js` | `pp-for` belongs on `<template>`, use plain `key`, not `pp-key` |
+| Events | native `onclick`, `oninput`, `onsubmit` | `pp-reactive-v2.js` | event scope exposes `event`, `e`, `$event`, `target`, `currentTarget`, and `el` |
+| RPC | `pp.rpc(...)` in scripts, `@rpc()` in Python | `pp-reactive-v2.js`, `casp/rpc.py` | use `pp.rpc`, not legacy `pp.fetchFunction`; protected actions use `@rpc(require_auth=True)` |
+| Upload progress | `pp.rpc(..., { onUploadProgress })` | `pp-reactive-v2.js`, `casp/rpc.py` | XHR path is used for progress callbacks; replace state from returned payload |
+| Streaming | `pp.rpc(..., { onStream })` | `pp-reactive-v2.js`, `casp/rpc.py`, `casp/streaming.py` | server generators become SSE responses |
+| SPA navigation | `body[pp-spa="true"]`, links | `pp-reactive-v2.js`, `main.py` | same-origin eligible links intercept; root-layout mismatches hard reload |
+| Scroll restoration | `pp-reset-scroll="true"` | `pp-reactive-v2.js` | push navigation resets window; mark only content panes that should reset |
+| Tailwind merge | `{twMerge(...)}`, Python `merge_classes(...)` | `html_attrs.py`, `pp-reactive-v2.js` | Python emits frontend-ready expressions when Tailwind is enabled |
+
+## AI Decision Rules
+
+- Read `caspian.config.json` first when the task depends on Tailwind, generated files, or optional project features.
+- Read [routing.md](./routing.md) before adding route or layout templates.
+- Read [components.md](./components.md) before adding reusable Python components or `x-*` imports.
+- Read [fetch-data.md](./fetch-data.md) before adding browser-triggered backend work.
+- Use this map when the task names a PulsePoint feature and you need the owning runtime file quickly.
+- Verify implemented behavior in `public/js/pp-reactive-v2.js` before adding new PulsePoint API claims.
+
+## Copy-Safe Authoring Rules
+
+- Author one root element or one imported `x-*` root per route, layout, or component template.
+- Keep any owned plain `<script>` inside that same root.
+- Do not handwrite `pp-component`, `type="text/pp"`, `data-pp-ref`, `pp-owner`, `pp-event-owner`, or other runtime-managed attributes.
+- Use `pp.rpc(...)` for current browser-to-server calls.
+- Use `Context.Provider` and `pp.context(...)` for context.
+- Use `pp-for` only on `<template>` and plain `key` for keyed lists.
+- Prefer PulsePoint state and directives over manual `innerHTML` repainting.
+
+## Compact Examples
+
+Context provider:
+
+```html
+<section>
+  <script>
+    const ThemeContext = pp.createContext("light");
+    const [theme, setTheme] = pp.state("dark");
+  </script>
+
+  <ThemeContext.Provider value="{theme}">
+    <button onclick="setTheme(theme === 'dark' ? 'light' : 'dark')">
+      Theme: {theme}
+    </button>
+  </ThemeContext.Provider>
+</section>
+```
+
+Upload progress:
+
+```html
+<section>
+  <input type="file" onchange="{uploadFile(event.target.files?.[0])}" />
+  <p>{progress}%</p>
+
+  <script>
+    const [progress, setProgress] = pp.state(0);
+
+    async function uploadFile(file) {
+      if (!file) return;
+
+      await pp.rpc("upload_asset", { file }, {
+        onUploadProgress: (event) => setProgress(event.percentage ?? 0),
+      });
+    }
+  </script>
+</section>
+```
+
+Grouped shell scroll reset:
+
+```html
+<section class="dashboard-shell">
+  <aside class="dashboard-sidebar">...</aside>
+  <main class="dashboard-content" pp-reset-scroll="true">
+    [[ children | safe ]]
+  </main>
+</section>
+```
+
+## Verification Prompts
+
+Use these prompts after docs or runtime changes to confirm AI can route correctly:
+
+- "Create an interactive filter in a Caspian route template."
+- "Explain why authored scripts are plain `<script>` but browser output shows `type=\"text/pp\"`."
+- "Debug a dashboard sidebar losing scroll during child-route navigation."
+- "Add an upload widget with progress and a reactive file list."
+- "Use context to share theme state between parent and child components."

package/dist/docs/pulsepoint.md

@@ -7,8 +7,9 @@ related:
   links:
     - /docs/components
     - /docs/routing
-    - /docs/fetch-data
-    - /docs/core-runtime-map
+    - /docs/fetch-data
+    - /docs/pulsepoint-runtime-map
+    - /docs/core-runtime-map
     - /docs/project-structure
     - /docs/index
 ---
@@ -43,7 +44,9 @@ Important current facts:
 
 If docs, generated examples, or older notes disagree with `public/js/pp-reactive-v2.js` plus `main.py`, follow the code that actually runs.
 
-Use [core-runtime-map.md](./core-runtime-map.md) when the controlling runtime file is not obvious yet.
+Use [core-runtime-map.md](./core-runtime-map.md) when the controlling runtime file is not obvious yet.
+
+Use [pulsepoint-runtime-map.md](./pulsepoint-runtime-map.md) when the task names a specific PulsePoint feature or directive and you need a quick feature-to-runtime lookup before reading the full guide.
 
 ## Default Frontend Rule
 

package/dist/docs/routing.md

@@ -12,6 +12,7 @@ related:
     - /docs/file-uploads
     - /docs/metadata
     - /docs/pulsepoint
+    - /docs/pulsepoint-runtime-map
     - /docs/index
 ---
 
@@ -227,7 +228,7 @@ Also bad:
 </section>
 ```
 
-Use [pulsepoint.md](./pulsepoint.md) when you need the full authored-vs-rendered example instead of this routing-focused reminder.
+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`
 
@@ -235,6 +236,8 @@ Use `index.py` as the backend companion when a route needs metadata or async ser
 
 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.
 
+When `page()` calls `render_page(__file__, ...)`, root-validation errors are attributed to the sibling `index.html` because that file is the authored template. If `page()` 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.
+
 Example:
 
 ```python
@@ -390,6 +393,8 @@ Example root layout:
 
 If a layout needs shared synchronous 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.
+
 Example:
 
 ```python
@@ -400,7 +405,7 @@ def layout(context_data):
 
     return {
         "user": user,
-    "dashboard_body_class": "w-screen h-screen overflow-hidden",
+        "dashboard_body_class": "w-screen h-screen overflow-hidden",
         "theme": "dark",
     }
 ```

package/dist/docs/state.md

@@ -27,11 +27,18 @@ Import the public API like this:
 from casp.state_manager import StateManager
 ```
 
-The current installed implementation lives in `.venv/Lib/site-packages/casp/state_manager.py`.
-
-Use [core-runtime-map.md](./core-runtime-map.md) when a state task crosses `main.py` middleware setup, wire-request behavior, and the installed state-manager internals.
-
-The real API surface is:
+The current installed implementation lives in `.venv/Lib/site-packages/casp/state_manager.py`.
+
+Use [core-runtime-map.md](./core-runtime-map.md) when a state task crosses `main.py` middleware setup, wire-request behavior, and the installed state-manager internals.
+
+## Source Of Truth
+
+- Request initialization and middleware timing are controlled by `main.py`.
+- The server state implementation lives in `.venv/Lib/site-packages/casp/state_manager.py`.
+- Route and RPC code should use `StateManager` only for transient server request state.
+- Browser interaction state belongs in PulsePoint; read [pulsepoint.md](./pulsepoint.md) before moving UI state into `StateManager`.
+
+The real API surface is:
 
 - request initialization with `StateManager.init(request)`
 - top-level state reads with `StateManager.get_state(...)`

package/dist/docs/validation.md

@@ -26,9 +26,16 @@ Import the public API like this:
 from casp.validate import Validate, Rule
 ```
 
-The current installed implementation lives in `.venv/Lib/site-packages/casp/validate.py`.
-
-The real API surface is:
+The current installed implementation lives in `.venv/Lib/site-packages/casp/validate.py`.
+
+## Source Of Truth
+
+- The implemented validation API lives in `.venv/Lib/site-packages/casp/validate.py`.
+- Route and RPC input boundaries live in `src/app/**/index.py`.
+- Reusable app-owned validation workflows belong in `src/lib/**`.
+- Browser-side validation is UX only; server-side `Validate` and `Rule` checks remain authoritative.
+
+The real API surface is:
 
 - direct single-value validation with `Validate.*(...)`
 - multi-rule validation with `Validate.with_rules(...)`

package/package.json

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