caspian-utils 0.0.24 → 0.0.26

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

@@ -53,13 +53,17 @@ Use prompts like these to check whether AI lands on the correct docs and files.
 | Prompt | First docs AI should read | Controlling files AI should reach | Verification focus |
 | --- | --- | --- | --- |
 | Create a protected dashboard section with child routes and a shared shell. | [index.md](./index.md), [routing.md](./routing.md), [auth.md](./auth.md), [project-structure.md](./project-structure.md) | `src/app/**`, `src/lib/auth/auth_config.py`, `main.py`, `.venv/Lib/site-packages/casp/layout.py` | section layout ownership, route privacy mode, and child-route wrapping |
+| Make a grouped shell keep sidebar scroll while resetting page content on child-route navigation. | [index.md](./index.md), [routing.md](./routing.md), [pulsepoint.md](./pulsepoint.md), [core-runtime-map.md](./core-runtime-map.md) | `src/app/**/layout.html`, `public/js/pp-reactive-v2.js`, `main.py` | `pp-reset-scroll` placement, push-vs-history scroll behavior, and shared-shell ownership |
 | Create a new contact page with interactive form behavior. | [index.md](./index.md), [routing.md](./routing.md), [pulsepoint.md](./pulsepoint.md), [components.md](./components.md) | `src/app/**/index.html`, `main.py`, `.venv/Lib/site-packages/casp/components_compiler.py`, `.venv/Lib/site-packages/casp/scripts_type.py` | single-root template shape, script-inside-root authoring, and authored-vs-runtime boundaries |
 | 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.
 
@@ -70,6 +74,7 @@ Treat the table as a prompt pack for spot checks, not as a full validation matri
 - AI edits framework internals when the task only requires app-owned route or helper changes.
 - AI treats runtime HTML examples as authored template examples.
 - AI generates a route or component template with a valid-looking root element but leaves a sibling top-level `<script>` or second top-level element after it.
+- AI puts `pp-reset-scroll="true"` on the whole shell or `body` when only the page-content pane should reset, causing persistent sidebars or rails to lose their scroll position.
 - AI decides behavior from memory without checking the owning implementation details.
 
 ## Decision Rule

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,19 +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. |
-
-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.
+
+## 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
 
@@ -65,6 +107,7 @@ Use these behavior checkpoints when AI needs the fastest verification path for a
 | Runtime area | Verify these behaviors |
 | --- | --- |
 | `main.py` routing and request flow | route registration, path and query injection, static asset handling, and exception rendering |
+| `public/js/pp-reactive-v2.js` browser runtime | SPA interception, history-vs-push scroll behavior, `pp-reset-scroll` semantics, and browser-side `pp.rpc()` behavior |
 | `casp.auth` | auth settings, signin and signout flow, provider wiring, and page protection behavior |
 | `casp.rpc` and streamed RPC responses | middleware interception, CSRF and session expectations, registry behavior, and helper-level RPC contracts |
 | `casp.layout` | layout discovery, metadata merge, root handling, and layout rendering rules |

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,19 +72,20 @@ 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
-- `pulsepoint.md` - Default reactive frontend runtime contract for component scripts, state, effects, directives, client-side behaviors, and direct browser `twMerge(...)` usage 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
 - `file-uploads.md` - Route-local file uploads and file-manager flows with `@rpc()`, `pp.rpc()`, Prisma metadata, public asset storage, and BrowserSync ignore rules
 - `state.md` - Request-scoped server state with `StateManager`, session-backed JSON persistence, and listener callbacks for transient flows
 - `cache.md` - Route-level HTML caching with `Cache`, `CacheHandler`, TTL behavior, file-system storage, and invalidation patterns
 - `validation.md` - Input validation and sanitization with `Validate`, `Rule`, direct field checks, and multi-rule workflows for routes and RPC actions
 - `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, single-parent authored templates, and backend Python companions that do not own visible markup
+- `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
 
 ## AI Retrieval Notes
@@ -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

@@ -1,14 +1,15 @@
 ---
 title: PulsePoint Runtime Guide
-description: Use this page when the task mentions PulsePoint, `pp.state`, `pp.effect`, `pp-ref`, `pp-style`, `pp-for`, portals, SPA navigation, or `public/js/pp-reactive-v2.js`.
+description: Use this page when the task mentions PulsePoint, `pp.state`, `pp.effect`, `pp-ref`, `pp-style`, `pp-for`, portals, `pp-reset-scroll`, SPA navigation, or `public/js/pp-reactive-v2.js`.
 related:
   title: Related docs
   description: Read the components, routing, data-fetching, and project-structure docs alongside the PulsePoint runtime contract.
   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
 ---
@@ -17,7 +18,7 @@ related:
 
 This file documents the PulsePoint contract for the shipped Caspian browser runtime. Treat it as the AI-facing source of truth when generating or reviewing interactive Caspian UI.
 
-If a task involves `pp.state`, `pp.effect`, `pp.layoutEffect`, `pp-ref`, `pp-style`, `pp-spread`, `pp-for`, context, portals, SPA navigation, or component boundary behavior, read this page first and keep generated code aligned with the current Caspian runtime.
+If a task involves `pp.state`, `pp.effect`, `pp.layoutEffect`, `pp-ref`, `pp-style`, `pp-spread`, `pp-for`, context, portals, `pp-reset-scroll`, SPA navigation, or component boundary behavior, read this page first and keep generated code aligned with the current Caspian runtime.
 
 Use `components.md` for authoring Python `@component` files, same-name HTML templates, and HTML-first `x-*` component tags. Use this page for the browser-side PulsePoint contract, the authoring rules that feed it, and the React-style mental model used by the shipped runtime.
 
@@ -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
 
@@ -401,7 +404,12 @@ Example:
 - `pp-loading-content="true"` marks the page region that gets swapped or faded during navigation.
 - Route-specific loading states are looked up with `pp-loading-url`.
 - `pp-loading-transition` accepts JSON with `fadeIn` and `fadeOut` timing values.
-- `pp-reset-scroll="true"` resets scroll positions during navigation.
+- The runtime saves scroll positions per history entry while SPA navigation is enabled.
+- Push navigation resets window scroll to the top.
+- Saved history-entry scroll state is used during history traversal instead of relying only on the live DOM scroll at the time the user clicks Back or Forward.
+- Unmarked scrollable containers may keep their outgoing scroll on push navigation so shared shells such as sidebars, rails, and docs nav panes stay stable across child-route changes.
+- `pp-reset-scroll="true"` on a scroll container opts that container into reset-on-navigation behavior. Use it on the main content pane of a grouped shell when page content should start at the top on each child-route navigation.
+- `body[pp-reset-scroll="true"]` is the global override for routes that should reset window scroll and every scrollable element.
 - Navigation dispatches `pp:navigation:start`, `pp:navigation:complete`, and `pp:navigation:error` events on `document`.
 
 RPC notes:
@@ -447,6 +455,7 @@ Use these rules when generating or editing PulsePoint runtime code:
 - If a development-only source tree exists behind the shipped runtime, treat it as optional implementation detail rather than something generated apps are guaranteed to contain.
 - In authored Caspian templates, do not handwrite `pp-component` or `type="text/pp"`; let the render pipeline inject them.
 - For grouped subtrees, follow the section layout pattern in [routing.md](./routing.md), keep the shared interactive shell in the parent folder's `layout.html`, and keep route-specific PulsePoint code in each child `index.html`.
+- For grouped shells with independent shell and content scrolling, put `pp-reset-scroll="true"` on the content pane rather than the whole shell when only the page content should reset between child-route navigations.
 - Prefer PulsePoint state and template directives over manual DOM mutation for reactive updates.
 - If you are explicitly editing raw runtime HTML or internals, keep `pp-component` unique per live instance.
 - In authored templates, use a plain `<script>` inside the root. In runtime HTML, the owned script appears as `script[type="text/pp"]`.

package/dist/docs/routing.md

@@ -10,9 +10,10 @@ related:
     - /docs/components
     - /docs/cache
     - /docs/file-uploads
-    - /docs/metadata
-    - /docs/pulsepoint
-    - /docs/index
+    - /docs/metadata
+    - /docs/pulsepoint
+    - /docs/pulsepoint-runtime-map
+    - /docs/index
 ---
 
 Caspian follows the same mental model as the Next.js App Router: routes live under `src/app`, folders define URL segments, layouts nest automatically, and special folder names control grouping and dynamic matching.
@@ -31,6 +32,7 @@ Start with these rules:
 - Add `index.py` only when the same route needs metadata, `page()`, `@rpc()` actions, auth checks, caching, redirects, or other server-side logic.
 - 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.
 - 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.
@@ -145,6 +147,8 @@ src/
 
 Use this pattern when the app has a public grouped section that should stay out of the URL and a private dashboard section that should appear in the URL. The root layout owns app-wide chrome, `(marketing)/layout.html` owns the shared public marketing shell, and `dashboard/layout.html` owns the shared dashboard shell for `/dashboard/*` child routes.
 
+When a shared shell has its own scrollable sidebar or rail plus a separate page-content scroller, keep the persistent shell scrollers unmarked and put `pp-reset-scroll="true"` on the page-content scroller in `layout.html`. That gives grouped sections the common app-router behavior where the main pane resets on child-route navigation while the sidebar keeps its scroll position. Use `body[pp-reset-scroll="true"]` only when the target route should reset every scrollable surface.
+
 ## Core Concepts
 
 Every route lives inside `src/app`. For routes that render UI, `index.html` owns the markup and `index.py` is only an optional companion for server logic or metadata.
@@ -224,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`
 
@@ -392,15 +396,15 @@ Example:
 ```python
 from casp.auth import auth
 
-def layout(context_data):
-    user = auth.get_payload()
-
-    return {
-        "user": user,
-    "dashboard_body_class": "w-screen h-screen overflow-hidden",
-        "theme": "dark",
-    }
-```
+def layout(context_data):
+    user = auth.get_payload()
+
+    return {
+        "user": user,
+        "dashboard_body_class": "w-screen h-screen overflow-hidden",
+        "theme": "dark",
+    }
+```
 
 `context_data` includes URL parameters such as dynamic route values.
 
@@ -498,6 +502,7 @@ If an AI agent is choosing where to add or update route code, apply these rules
 - 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 synchronous 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.
 - Keep `<!-- @import ... -->` directives at the top of `index.html` and `layout.html`, above the single authored parent node.

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.24",
+  "version": "0.0.26",
   "description": "Caspian tooling",
   "main": "index.js",
   "scripts": {