caspian-utils 0.1.2 → 0.1.4

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

@@ -64,6 +64,7 @@ Use prompts like these to check whether AI lands on the correct docs and files.
 | 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) | `ts/TemplateCompiler.ts`, `public/js/pp-reactive-v2.js`, component `.html`, `.venv/Lib/site-packages/casp/components_compiler.py` | lowercase HTML-first `*.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 |
+| Add or debug a live WebSocket channel. | [index.md](./index.md), [websockets.md](./websockets.md), [core-runtime-map.md](./core-runtime-map.md), [pulsepoint.md](./pulsepoint.md), [auth.md](./auth.md) | `caspian.config.json`, `main.py`, `src/lib/websocket/**`, `src/app/**`, `settings/bs-config.json` | `websocket` feature gate, endpoint registration, origin checks, auth/session handling, native `WebSocket` client lifecycle, and BrowserSync URL selection |
 | 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/commands.md

@@ -179,9 +179,12 @@ In skip-prompt mode, the default feature values are:
 
 - `backendOnly: false`
 - `tailwindcss: false`
-- `typescript: false`
-- `mcp: false`
-- `prisma: false`
+- `typescript: false`
+- `mcp: false`
+- `prisma: false`
+- `websocket: false`
+
+If a project needs WebSockets after creation, set `websocket: true` in `caspian.config.json`, then run the project update workflow so framework-managed files and any scaffolded socket surfaces stay aligned before assuming `@app.websocket(...)` routes or `src/lib/websocket/**` exist.
 
 ### 4.2 Backend-only combinations
 

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

@@ -7,8 +7,9 @@ related:
   links:
     - /docs/project-structure
     - /docs/routing
-    - /docs/auth
+    - /docs/auth
     - /docs/fetch-data
+    - /docs/websockets
     - /docs/pulsepoint
     - /docs/pulsepoint-runtime-map
     - /docs/index
@@ -59,6 +60,7 @@ Use this table when the task names a framework feature but the owning file is no
 | Baseline response headers and safe public-file serving | `main.py` imports from `casp.runtime_security` | `.venv/Lib/site-packages/casp/runtime_security.py` | [auth.md](./auth.md), [project-structure.md](./project-structure.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) |
+| WebSockets | `main.py` `@app.websocket(...)` endpoints when `caspian.config.json` has `websocket: true`, `src/lib/**` socket helpers, route-owned browser clients in `src/app/**` | FastAPI app-owned ASGI endpoints in `main.py` | [websockets.md](./websockets.md), [auth.md](./auth.md), [pulsepoint.md](./pulsepoint.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) |
@@ -111,7 +113,8 @@ 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, session-middleware wiring, response-header middleware, 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 |
+| `main.py` WebSockets | `cfg.websocket` route-registration gate, `@app.websocket(...)` paths, origin checks before `accept()`, auth/session extraction, message-size and idle-timeout handling, close codes, and connection cleanup |
+| `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

@@ -23,6 +23,8 @@ This page explains how data fetching works in Caspian. Use route functions for i
 
 Treat RPC as the default way for browser code to talk to Python in Caspian. For CRUD operations and any browser-initiated backend reads after first render, default to `@rpc()` on the server and `pp.rpc()` in PulsePoint code. Do not reach for ad hoc fetch calls to custom JSON endpoints, alternate transport layers, or older helper names unless the task explicitly requires that shape.
 
+WebSockets are the main exception for long-lived bidirectional live channels when `caspian.config.json` has `websocket: true`. If the task needs a native browser `WebSocket`, persistent broadcast channel, presence, live chat, or socket origin/auth handling, confirm that flag and read [websockets.md](./websockets.md) before adding endpoint or client code. Do not use WebSockets as a replacement for ordinary RPC form submits or CRUD work.
+
 When `caspian.config.json` has `prisma: true`, the Python side of those route and RPC actions must use the generated Prisma Python ORM from `src/lib/prisma/**` for database reads and writes. The browser asks Python through `pp.rpc(...)`; Python asks the database through Prisma. Do not replace either side with a custom browser fetch, direct database driver, hand-written SQL helper, JSON active store, or second app-owned data-fetch abstraction.
 
 Browser-triggered data work should still be PulsePoint-first at the event layer. Bind the initiating click, submit, input, upload, refresh, filter, or pagination control in authored HTML with `onclick`, `onsubmit`, `oninput`, `onchange`, or another native `on*` attribute handled by PulsePoint. For normal form submissions, read named controls with `Object.fromEntries(new FormData(event.currentTarget).entries())` in the submit handler and pass that object directly to `pp.rpc(...)`; the route's Python `@rpc()` action should validate, normalize, and decide what to persist. Do not set up first-party data actions by assigning ids and then wiring `querySelector(...)`, `addEventListener(...)`, manual `fetch(...)`, manual DOM repainting, or per-input `pp-ref` payload collection.
@@ -184,7 +186,8 @@ 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.
+- 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.
+- Use [websockets.md](./websockets.md) when `caspian.config.json` has `websocket: true` and the browser and server need a persistent bidirectional channel instead of request/response RPC or one-way SSE streaming.
 
 ## Streaming Responses
 

package/dist/docs/index.md

@@ -11,8 +11,9 @@ related:
     - /docs/core-runtime-map
     - /docs/pulsepoint-runtime-map
     - /docs/mcp
-    - /docs/file-uploads
-    - /docs/file-conventions
+    - /docs/file-uploads
+    - /docs/websockets
+    - /docs/file-conventions
     - /docs/project-structure
     - /docs/components
 ---
@@ -23,7 +24,7 @@ Treat these docs as reusable Caspian feature guidance. Treat `./caspian.config.j
 
 The docs can mention optional features even when those features are disabled in a project. Their job is to explain how a feature works, when a doc applies, and which files to inspect next once the feature is confirmed as relevant.
 
-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.
+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, WebSockets, TypeScript, Tailwind, backend-only mode, and component scan directories.
 
 ## Default Stack
 
@@ -34,6 +35,7 @@ When generating or editing a Caspian app, treat these as the default choices unl
 - 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.
+- When `caspian.config.json` has `websocket: true`, use app-owned FastAPI WebSocket endpoints only for long-lived bidirectional live channels; keep normal browser-triggered data work on RPC.
 - When `caspian.config.json` has `prisma: true`, use the generated Prisma Python ORM from `src/lib/prisma/**` for Python-side database reads and writes. Do not invent a second fetch layer, raw driver wrapper, JSON active store, or browser-side data path that bypasses Prisma.
 - Use `Validate` and `Rule` from `casp.validate` for server-side input validation and sanitization.
 
@@ -83,8 +85,9 @@ The packaged Caspian docs referenced by this index live here:
 - `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, first-party `on*` events, 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
+- `fetch-data.md` - Initial server-side data loading and browser-triggered RPC flows with `pp.rpc()`, streaming, uploads, and auth-aware actions
+- `websockets.md` - WebSocket feature-gate guidance for projects where `caspian.config.json` has `websocket: true`, app-owned FastAPI endpoint placement, browser `WebSocket` clients inside PulsePoint templates, origin checks, auth/session handling, and when to choose sockets over RPC or SSE
+- `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
@@ -103,14 +106,15 @@ Preferred lookup order:
 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. Before inventing browser JavaScript, check whether the interaction is first-party UI behavior. If it is, use PulsePoint `on*` attributes, `pp.state`, refs, effects, directives, and `pp.rpc()` rather than id-driven DOM scripting.
 5. When Prisma is enabled, route all Python database work through the generated Prisma Python ORM. Use `database.md` before schema, migration, seed, or ORM decisions, and use `fetch-data.md` before wiring route data or RPC flows.
-6. 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`.
-7. 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.
-8. 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.
-9. 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.
-10. 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.
-11. Prefer packaged Caspian docs before upstream documentation when generating code, commands, or migration guidance.
-12. Use `ai-validation-checklist.md` when you want to verify that the docs lead AI to the correct files and behavior checkpoints.
-13. Keep `index.md` and cross-links aligned so AI can quickly discover the right doc.
+6. If the task asks for WebSockets, live bidirectional channels, socket origin checks, or native browser `WebSocket` clients, confirm `caspian.config.json` has `websocket: true`, read `websockets.md`, then inspect `main.py`, `src/lib/**`, the owning `src/app/**` route, and `settings/bs-config.json`. If `websocket` is false and the user wants it, ask first, then enable the config flag and follow the update workflow.
+7. 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`.
+8. 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.
+9. 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.
+10. 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.
+11. 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`, `websockets.md`, and `file-uploads.md` for task-specific guidance.
+12. Prefer packaged Caspian docs before upstream documentation when generating code, commands, or migration guidance.
+13. Use `ai-validation-checklist.md` when you want to verify that the docs lead AI to the correct files and behavior checkpoints.
+14. Keep `index.md` and cross-links aligned so AI can quickly discover the right doc.
 
 ## Maintenance
 

package/dist/docs/project-structure.md

@@ -31,7 +31,7 @@ In that layout, the default stack is Python components for reusable UI, PulsePoi
 
 For public pages that can safely reuse rendered HTML, Caspian also supports route-level page caching through `casp.cache_handler`.
 
-Before an AI agent decides which Caspian features are available in a workspace, it should read `./caspian.config.json` almost immediately. That file is the feature gate for project capabilities such as `backendOnly`, `tailwindcss`, `mcp`, `prisma`, `typescript`, and `componentScanDirs`.
+Before an AI agent decides which Caspian features are available in a workspace, it should read `./caspian.config.json` almost immediately. That file is the feature gate for project capabilities such as `backendOnly`, `tailwindcss`, `mcp`, `prisma`, `typescript`, `websocket`, and `componentScanDirs`.
 
 Treat `caspian.config.json` as the single source of truth for optional feature enablement. Use feature-specific files and docs only after the matching flag is confirmed as 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`.
 
@@ -40,9 +40,10 @@ Treat `caspian.config.json` as the single source of truth for optional feature e
 - `src/` contains routes, page templates, styles, reusable components, and shared libraries.
 - `src/components/` contains reusable application UI components and optional same-name HTML templates.
 - `src/lib/` contains reusable non-UI code such as helpers, services, validators, adapters, and shared support modules.
-- `src/lib/auth/auth_config.py` contains auth-specific configuration for the app.
-- `src/lib/mcp/` contains the app-owned FastMCP server and nested FastMCP config when MCP is enabled.
-- `prisma/` contains the Prisma schema and seed scripts.
+- `src/lib/auth/auth_config.py` contains auth-specific configuration for the app.
+- `src/lib/mcp/` contains the app-owned FastMCP server and nested FastMCP config when MCP is enabled.
+- `src/lib/websocket/` contains reusable socket helpers when WebSockets are enabled and the project includes shared session, auth, connection, or broadcast utilities.
+- `prisma/` contains the Prisma schema and seed scripts.
 - `public/` contains static assets served directly.
 - `settings/` contains BrowserSync, build, restart, and generated-project helper files.
 - `main.py` is the application entry point.
@@ -77,9 +78,11 @@ my-app/
     lib/
       auth/
         auth_config.py
-      mcp/
-        fastmcp.json
-        mcp_server.py
+      mcp/
+        fastmcp.json
+        mcp_server.py
+      websocket/
+        websocket_security.py
       prisma/
         __init__.py
         db.py
@@ -94,7 +97,7 @@ my-app/
         docs/
 ```
 
-Optional directories such as `src/lib/mcp/` appear only when the relevant feature flag is enabled in `caspian.config.json`.
+Optional directories such as `src/lib/mcp/` and `src/lib/websocket/` appear only when the relevant feature flag is enabled in `caspian.config.json` and the project needs that app-owned surface.
 
 ## Directory Breakdown
 

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

@@ -37,12 +37,12 @@ If an inspected browser DOM disagrees with authored template source, remember th
 | 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(...)`, lowercase `<themecontext.provider>`, `pp.context(token)` | `TemplateCompiler.ts`, `NestedBoundaryManager.ts`, `pp-reactive-v2.js` | authored provider tags are HTML-first and lowercase; `TemplateCompiler.transformContextProviderTags(...)` rewrites `*.provider` to runtime-owned `pp-context-provider`; ancestry is logical component ancestry; do not invent `pp-context` or `pp.provideContext` |
+| Context | `pp.createContext(...)`, lowercase `<themecontext.provider>`, `pp.context(token)` | `TemplateCompiler.ts`, `NestedBoundaryManager.ts`, `pp-reactive-v2.js` | authored provider tags are HTML-first and lowercase; `TemplateCompiler.transformContextProviderTags(...)` rewrites `*.provider` to runtime-owned `pp-context-provider`; 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`, `onchange`, `onsubmit` | `pp-reactive-v2.js` | first-party events belong in `on*` attributes; event scope exposes `event`, `e`, `$event`, `target`, `currentTarget`, and `el`; normal form submits should use `Object.fromEntries(new FormData(event.currentTarget).entries())` instead of per-input refs; avoid id-driven `querySelector`/`addEventListener` for normal UI |
+| Events | native `onclick`, `oninput`, `onchange`, `onsubmit` | `pp-reactive-v2.js` | first-party events belong in `on*` attributes; event scope exposes `event`, `e`, `$event`, `target`, `currentTarget`, and `el`; normal form submits should use `Object.fromEntries(new FormData(event.currentTarget).entries())` instead of per-input refs; avoid id-driven `querySelector`/`addEventListener` for normal UI |
 | 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 |
+| Upload progress | `pp.rpc(..., { onUploadProgress })` | `pp-reactive-v2.js`, `casp/rpc.py` | XHR path is used for progress callbacks; the callback receives `{ loaded, total, percent }` and `percent` can be `null` when length is not computable; 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 |
@@ -63,32 +63,32 @@ If an inspected browser DOM disagrees with authored template source, remember th
 - 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 native `on*` attributes for button clicks, form submits, input changes, filters, toggles, and menus instead of adding ids and manual listeners.
-- For ordinary form submits, bind `onsubmit` on the form and read named fields with `Object.fromEntries(new FormData(event.currentTarget).entries())`; reserve `pp-ref` for imperative access rather than routine payload collection.
-- Use lowercase provider tags such as `<themecontext.provider>` and `pp.context(...)` for context.
+- Use `pp.rpc(...)` for current browser-to-server calls.
+- Use native `on*` attributes for button clicks, form submits, input changes, filters, toggles, and menus instead of adding ids and manual listeners.
+- For ordinary form submits, bind `onsubmit` on the form and read named fields with `Object.fromEntries(new FormData(event.currentTarget).entries())`; reserve `pp-ref` for imperative access rather than routine payload collection.
+- Use lowercase provider tags such as `<themecontext.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.
 - Keep direct DOM APIs inside `pp.ref(...)` plus `pp.effect(...)` only when a third-party or browser API integration actually requires them.
 
 ## Compact Examples
 
-Context provider:
-
-```html
-<section>
-  <script>
-    const ThemeContext = pp.createContext("light");
+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>
-```
+  <themecontext.provider value="{theme}">
+    <button onclick="setTheme(theme === 'dark' ? 'light' : 'dark')">
+      Theme: {theme}
+    </button>
+  </themecontext.provider>
+</section>
+```
 
 Upload progress:
 
@@ -104,7 +104,7 @@ Upload progress:
       if (!file) return;
 
       await pp.rpc("upload_asset", { file }, {
-        onUploadProgress: (event) => setProgress(event.percentage ?? 0),
+        onUploadProgress: (event) => setProgress(Math.round(event.percent ?? 0)),
       });
     }
   </script>
@@ -115,11 +115,11 @@ Grouped shell scroll reset:
 
 ```html
 <section class="dashboard-shell">
-  <aside class="dashboard-sidebar">...</aside>
-  <main class="dashboard-content" pp-reset-scroll="true">
-    <slot />
-  </main>
-</section>
+  <aside class="dashboard-sidebar">...</aside>
+  <main class="dashboard-content" pp-reset-scroll="true">
+    <slot />
+  </main>
+</section>
 ```
 
 ## Verification Prompts

package/dist/docs/pulsepoint.md

@@ -26,6 +26,19 @@ PulsePoint is the default reactive frontend layer for Caspian. In the current ru
 
 Do not assume React, Vue, Svelte, JSX, Alpine, HTMX, or older PulsePoint docs unless the task explicitly asks for a different frontend contract.
 
+## Hard Invariants
+
+Apply these before generating any template, even without reading the rest of this page:
+
+1. One authored top-level root per route, layout, or component template; the owned plain `<script>` lives inside that root, never as a sibling.
+2. Never handwrite `pp-component`, `type="text/pp"`, `data-pp-ref`, or other runtime-managed attributes; the render pipeline injects them.
+3. Bind first-party events with native `on*` attributes in the HTML; never wire normal UI with ids, `querySelector`, `addEventListener`, or manual `innerHTML`.
+4. For ordinary form submits, use `onsubmit="{handler(event)}"` plus `Object.fromEntries(new FormData(event.currentTarget).entries())`; refs are for imperative access only.
+5. Keep reactive values in `pp.state(...)`; keep template-facing bindings at the top level of the script.
+6. Call the backend with `pp.rpc(...)` backed by Python `@rpc()` actions; do not invent fetch wrappers or `pp.fetchFunction()`.
+7. `pp-for` goes only on `<template>` with plain `key`; context uses `pp.createContext(...)`, a lowercase `<token.provider>` tag, and `pp.context(token)`.
+8. If an API is not in `public/js/pp-reactive-v2.js`, it does not exist; do not invent hooks, directives, or globals.
+
 ## Source Of Truth
 
 When documenting or generating PulsePoint code, follow this order:
@@ -48,245 +61,209 @@ Use [core-runtime-map.md](./core-runtime-map.md) when the controlling runtime fi
 
 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
-
-When a Caspian page needs reactive browser behavior, use PulsePoint.
-
-- Use PulsePoint component roots, scripts, directives, and runtime helpers for interactive UI.
-- Use PulsePoint state, effects, refs, and template directives as the default reactivity model in authored Caspian templates.
-- Bind first-party events in the HTML with PulsePoint-handled native `on*` attributes such as `onclick`, `oninput`, `onchange`, and `onsubmit`.
-- For ordinary forms, bind the submit event in the `<form>` and collect named fields with `Object.fromEntries(new FormData(event.currentTarget).entries())`. Let input `name` attributes define the payload keys, then validate and normalize those values in Python. Do not use `pp.ref(...)` on every input or an effect-managed listener just to read submitted values.
-- When the browser needs CRUD operations or follow-up reads from the backend, call `pp.rpc()` from PulsePoint code and back it with route or backend `@rpc()` actions.
-- Keep server-rendered HTML plus PulsePoint enhancement as the baseline architecture.
-- For dashboards, admin areas, account sections, docs sections, and other grouped subtrees, keep shared shell markup and shared PulsePoint behavior in the parent folder's `layout.html`, then keep child-route PulsePoint state local to each `index.html`. Follow the same mental model as the Next.js App Router.
-- Only introduce another frontend runtime when the user explicitly asks for it or the project already depends on one.
-
-## PulsePoint-First Events And Reactivity
-
-For first-party Caspian HTML, PulsePoint is not a later enhancement after ordinary JavaScript. It is the event, state, and reactivity model AI should use from the start.
-
-Default to this workflow:
-
-- Put the button, form, input, toggle, menu, filter, upload control, or list markup directly in the route, layout, or component HTML template.
-- Bind events with native `on*` attributes handled by PulsePoint, for example `onclick="save()"`, `oninput="setQuery(event.target.value)"`, or `onsubmit="{submitForm(event)}"`.
-- This is the PulsePoint `onClick`/native event-attribute model. Authored examples use lowercase HTML spellings such as `onclick` because browser HTML normalizes attribute names, but the important rule is to bind the event in the template instead of wiring it later with DOM selectors.
-- For simple form submissions, let HTML own the form shape and let the submit event carry the values: use `const data = Object.fromEntries(new FormData(event.currentTarget).entries())` inside the handler, then pass that object directly to `pp.rpc(...)`. In a form-level submit handler, `event.target` is usually the form too, but `event.currentTarget` is the copy-safe default because it always means the element that owns the handler.
-- Keep reactive values in `pp.state(...)`.
-- Render conditional text, classes, attributes, lists, and styles with template expressions, `pp-for`, `pp-style`, `pp-spread`, and other PulsePoint-supported template features.
-- Use `pp.ref(...)` and `pp-ref` when a real imperative element reference is needed, such as focus, measurement, media, canvas, third-party widgets, or resetting a specific file/password input after a successful action.
-- Use `pp.effect(...)` or `pp.layoutEffect(...)` for lifecycle work that must happen after render.
-- Use `pp.rpc(...)` for browser-triggered backend reads and writes.
-
-Avoid building a parallel JavaScript layer for normal UI behavior:
-
-- Do not add ids only so a script can find elements with `document.querySelector(...)` or `document.getElementById(...)`.
-- Do not use `data-*` attributes as a private client state system when PulsePoint state or props should own the data.
-- Do not create click-in buttons by placing intent in `data-*` attributes and then scanning for those attributes. Put the action directly on the element with `onclick`, `oninput`, `onchange`, `onsubmit`, or another native `on*` event attribute.
-- Do not bind normal first-party clicks, input changes, submits, filters, menus, or toggles with `addEventListener(...)`.
-- Do not use form refs plus input refs plus `pp.effect(...)` solely to construct an RPC payload from normal submitted fields.
-- Do not repaint first-party lists or panels with manual `innerHTML` writes when `pp.state(...)` plus `pp-for` can express the same UI.
-- Do not create a custom client-side store, event bus, or hydration routine for behavior that belongs in a PulsePoint component script.
-
-Use direct DOM APIs only as a narrow escape hatch: third-party widgets, browser APIs that require imperative access, measurements, focus, media, canvas, or behavior the current PulsePoint runtime cannot express declaratively. Even then, keep the imperative code inside the owning PulsePoint component script, usually through `pp.ref(...)` plus `pp.effect(...)`, so PulsePoint still owns the component's state, cleanup, and event flow.
-
-Preferred authored pattern:
-
-```html
-<section>
-  <input value="{query}" oninput="setQuery(event.target.value)" />
-  <button onclick="clearSearch()" disabled="{query.length === 0}">Clear</button>
-
-  <ul>
-    <template pp-for="item in filteredItems">
-      <li key="{item.id}">{item.label}</li>
-    </template>
-  </ul>
-
-  <script>
-    const [query, setQuery] = pp.state("");
-    const items = pp.props.items ?? [];
-    const filteredItems = items.filter((item) =>
-      item.label.toLowerCase().includes(query.toLowerCase())
-    );
-
-    function clearSearch() {
-      setQuery("");
-    }
-  </script>
-</section>
-```
-
-Avoid this first-party pattern:
-
-```html
-<section>
-  <input id="search" />
-  <button id="clear-search">Clear</button>
-  <ul id="results"></ul>
-
-  <script>
-    const input = document.querySelector("#search");
-    const button = document.querySelector("#clear-search");
-    const results = document.querySelector("#results");
-
-    button.addEventListener("click", () => {
-      input.value = "";
-      results.innerHTML = "";
-    });
-  </script>
-</section>
-```
-
-That second shape recreates a separate event and rendering system inside a Caspian component. It is harder to maintain because it bypasses PulsePoint's rerender, event rebinding, refs, cleanup, and backend RPC conventions.
-
-Preferred form submit pattern:
-
-```html
-<section>
-  <form onsubmit="{saveProfile(event)}" class="grid gap-4" novalidate>
-    <input name="name" value="{{ user_name }}" autocomplete="name" required />
-    <input name="email" type="email" value="{{ user_email }}" autocomplete="email" required />
-    <input name="password" type="password" autocomplete="new-password" />
-
-    <button type="submit" disabled="{isSubmitting}">
-      {isSubmitting ? "Saving..." : "Save changes"}
-    </button>
-  </form>
-
-  <script>
-    const [isSubmitting, setIsSubmitting] = pp.state(false);
-
-    async function saveProfile(event) {
-      event.preventDefault();
-      if (isSubmitting) return;
-
-      const data = Object.fromEntries(new FormData(event.currentTarget).entries());
-
-      setIsSubmitting(true);
-      try {
-        await pp.rpc("save_profile", data, { abortPrevious: true });
-      } finally {
-        setIsSubmitting(false);
-      }
-    }
-  </script>
-</section>
-```
-
-Avoid this for a normal form:
-
-```html
-<section>
-  <form pp-ref="{formRef}">
-    <input pp-ref="{nameRef}" name="name" />
-    <input pp-ref="{emailRef}" name="email" />
-  </form>
-
-  <script>
-    const formRef = pp.ref(null);
-    const nameRef = pp.ref(null);
-    const emailRef = pp.ref(null);
-
-    pp.effect(() => {
-      const form = formRef.current;
-      if (!form) return;
-
-      const submit = (event) => {
-        event.preventDefault();
-        return pp.rpc("save_profile", {
-          name: nameRef.current?.value ?? "",
-          email: emailRef.current?.value ?? "",
-        });
-      };
-
-      form.addEventListener("submit", submit);
-      return () => form.removeEventListener("submit", submit);
-    }, []);
-  </script>
-</section>
-```
-
-Refs are still useful when the feature actually requires imperative access. They are not the first choice for reading standard form fields that the browser already exposes through the submit event. Keep client code minimal and put reviewable data normalization in the route's Python `@rpc()` action unless the client must transform values for UX before submitting.
-
-Basic two-way state pattern:
-
-```html
-<section>
-  <label>
-    Name
-    <input name="name" value="{name}" oninput="setName(event.target.value)" />
-  </label>
-
-  <p>Hello, {name || "friend"}.</p>
-  <button onclick="setName('')">Clear</button>
-
-  <script>
-    const [name, setName] = pp.state("");
-  </script>
-</section>
-```
-
-Basic RPC-backed form pattern:
-
-```html
-<section>
-  <form onsubmit="{saveContact(event)}" novalidate>
-    <input name="name" value="{name}" oninput="setName(event.target.value)" required />
-    <input name="email" type="email" required />
-
-    <button type="submit" disabled="{isSaving}">
-      {isSaving ? "Saving..." : "Save"}
-    </button>
-  </form>
-
-  <script>
-    const [name, setName] = pp.state("");
-    const [isSaving, setIsSaving] = pp.state(false);
-
-    async function saveContact(event) {
-      event.preventDefault();
-      if (isSaving) return;
-
-      const data = Object.fromEntries(new FormData(event.currentTarget).entries());
-
-      setIsSaving(true);
-      try {
-        await pp.rpc("save_contact", data, { abortPrevious: true });
-      } finally {
-        setIsSaving(false);
-      }
-    }
-  </script>
-</section>
-```
-
-Back that form with a route-owned `@rpc()` action in the sibling `index.py`. If Prisma is enabled, the action should use the generated Prisma Python ORM for persistence.
-
-```python
-from casp.rpc import rpc
-from casp.validate import Validate
-from src.lib.prisma import prisma
-
-
-@rpc()
-async def save_contact(name: str, email: str):
-    name = name.strip()
-    email = email.strip().lower()
-
-    if not name:
-        raise ValueError("Name is required.")
-    if Validate.with_rules(email, "required|email") is not True:
-        raise ValueError("A valid email address is required.")
-
-    contact = await prisma.contact.create(
-        data={
-            "name": name,
-            "email": email,
-        }
-    )
-
-    return contact.to_dict()
-```
+## Default Frontend Rule
+
+When a Caspian page needs reactive browser behavior, use PulsePoint.
+
+- Use PulsePoint component roots, scripts, directives, and runtime helpers for interactive UI.
+- Use PulsePoint state, effects, refs, and template directives as the default reactivity model in authored Caspian templates.
+- Bind first-party events in the HTML with PulsePoint-handled native `on*` attributes such as `onclick`, `oninput`, `onchange`, and `onsubmit`.
+- For ordinary forms, bind the submit event in the `<form>` and collect named fields with `Object.fromEntries(new FormData(event.currentTarget).entries())`. Let input `name` attributes define the payload keys, then validate and normalize those values in Python. Do not use `pp.ref(...)` on every input or an effect-managed listener just to read submitted values.
+- When the browser needs CRUD operations or follow-up reads from the backend, call `pp.rpc()` from PulsePoint code and back it with route or backend `@rpc()` actions.
+- Keep server-rendered HTML plus PulsePoint enhancement as the baseline architecture.
+- For dashboards, admin areas, account sections, docs sections, and other grouped subtrees, keep shared shell markup and shared PulsePoint behavior in the parent folder's `layout.html`, then keep child-route PulsePoint state local to each `index.html`. Follow the same mental model as the Next.js App Router.
+- Only introduce another frontend runtime when the user explicitly asks for it or the project already depends on one.
+
+## PulsePoint-First Events And Reactivity
+
+For first-party Caspian HTML, PulsePoint is not a later enhancement after ordinary JavaScript. It is the event, state, and reactivity model AI should use from the start.
+
+Default to this workflow:
+
+- Put the button, form, input, toggle, menu, filter, upload control, or list markup directly in the route, layout, or component HTML template.
+- Bind events with native `on*` attributes handled by PulsePoint, for example `onclick="save()"`, `oninput="setQuery(event.target.value)"`, or `onsubmit="{submitForm(event)}"`.
+- This is the PulsePoint `onClick`/native event-attribute model. Authored examples use lowercase HTML spellings such as `onclick` because browser HTML normalizes attribute names, but the important rule is to bind the event in the template instead of wiring it later with DOM selectors.
+- For simple form submissions, let HTML own the form shape and let the submit event carry the values: use `const data = Object.fromEntries(new FormData(event.currentTarget).entries())` inside the handler, then pass that object directly to `pp.rpc(...)`. In a form-level submit handler, `event.target` is usually the form too, but `event.currentTarget` is the copy-safe default because it always means the element that owns the handler.
+- Keep reactive values in `pp.state(...)`.
+- Render conditional text, classes, attributes, lists, and styles with template expressions, `pp-for`, `pp-style`, `pp-spread`, and other PulsePoint-supported template features.
+- Use `pp.ref(...)` and `pp-ref` when a real imperative element reference is needed, such as focus, measurement, media, canvas, third-party widgets, or resetting a specific file/password input after a successful action.
+- Use `pp.effect(...)` or `pp.layoutEffect(...)` for lifecycle work that must happen after render.
+- Use `pp.rpc(...)` for browser-triggered backend reads and writes.
+
+Avoid building a parallel JavaScript layer for normal UI behavior:
+
+- Do not add ids only so a script can find elements with `document.querySelector(...)` or `document.getElementById(...)`.
+- Do not use `data-*` attributes as a private client state system when PulsePoint state or props should own the data.
+- Do not create click-in buttons by placing intent in `data-*` attributes and then scanning for those attributes. Put the action directly on the element with `onclick`, `oninput`, `onchange`, `onsubmit`, or another native `on*` event attribute.
+- Do not bind normal first-party clicks, input changes, submits, filters, menus, or toggles with `addEventListener(...)`.
+- Do not use form refs plus input refs plus `pp.effect(...)` solely to construct an RPC payload from normal submitted fields.
+- Do not repaint first-party lists or panels with manual `innerHTML` writes when `pp.state(...)` plus `pp-for` can express the same UI.
+- Do not create a custom client-side store, event bus, or hydration routine for behavior that belongs in a PulsePoint component script.
+
+Use direct DOM APIs only as a narrow escape hatch: third-party widgets, browser APIs that require imperative access, measurements, focus, media, canvas, or behavior the current PulsePoint runtime cannot express declaratively. Even then, keep the imperative code inside the owning PulsePoint component script, usually through `pp.ref(...)` plus `pp.effect(...)`, so PulsePoint still owns the component's state, cleanup, and event flow.
+
+Preferred authored pattern:
+
+```html
+<section>
+  <input value="{query}" oninput="setQuery(event.target.value)" />
+  <button onclick="clearSearch()" disabled="{query.length === 0}">Clear</button>
+
+  <ul>
+    <template pp-for="item in filteredItems">
+      <li key="{item.id}">{item.label}</li>
+    </template>
+  </ul>
+
+  <script>
+    const [query, setQuery] = pp.state("");
+    const items = pp.props.items ?? [];
+    const filteredItems = items.filter((item) =>
+      item.label.toLowerCase().includes(query.toLowerCase())
+    );
+
+    function clearSearch() {
+      setQuery("");
+    }
+  </script>
+</section>
+```
+
+Avoid this first-party pattern:
+
+```html
+<section>
+  <input id="search" />
+  <button id="clear-search">Clear</button>
+  <ul id="results"></ul>
+
+  <script>
+    const input = document.querySelector("#search");
+    const button = document.querySelector("#clear-search");
+    const results = document.querySelector("#results");
+
+    button.addEventListener("click", () => {
+      input.value = "";
+      results.innerHTML = "";
+    });
+  </script>
+</section>
+```
+
+That second shape recreates a separate event and rendering system inside a Caspian component. It is harder to maintain because it bypasses PulsePoint's rerender, event rebinding, refs, cleanup, and backend RPC conventions.
+
+Preferred form submit pattern:
+
+```html
+<section>
+  <form onsubmit="{saveProfile(event)}" class="grid gap-4" novalidate>
+    <input name="name" value="{{ user_name }}" autocomplete="name" required />
+    <input name="email" type="email" value="{{ user_email }}" autocomplete="email" required />
+    <input name="password" type="password" autocomplete="new-password" />
+
+    <button type="submit" disabled="{isSubmitting}">
+      {isSubmitting ? "Saving..." : "Save changes"}
+    </button>
+  </form>
+
+  <script>
+    const [isSubmitting, setIsSubmitting] = pp.state(false);
+
+    async function saveProfile(event) {
+      event.preventDefault();
+      if (isSubmitting) return;
+
+      const data = Object.fromEntries(new FormData(event.currentTarget).entries());
+
+      setIsSubmitting(true);
+      try {
+        await pp.rpc("save_profile", data, { abortPrevious: true });
+      } finally {
+        setIsSubmitting(false);
+      }
+    }
+  </script>
+</section>
+```
+
+Avoid this for a normal form:
+
+```html
+<section>
+  <form pp-ref="{formRef}">
+    <input pp-ref="{nameRef}" name="name" />
+    <input pp-ref="{emailRef}" name="email" />
+  </form>
+
+  <script>
+    const formRef = pp.ref(null);
+    const nameRef = pp.ref(null);
+    const emailRef = pp.ref(null);
+
+    pp.effect(() => {
+      const form = formRef.current;
+      if (!form) return;
+
+      const submit = (event) => {
+        event.preventDefault();
+        return pp.rpc("save_profile", {
+          name: nameRef.current?.value ?? "",
+          email: emailRef.current?.value ?? "",
+        });
+      };
+
+      form.addEventListener("submit", submit);
+      return () => form.removeEventListener("submit", submit);
+    }, []);
+  </script>
+</section>
+```
+
+Refs are still useful when the feature actually requires imperative access. They are not the first choice for reading standard form fields that the browser already exposes through the submit event. Keep client code minimal and put reviewable data normalization in the route's Python `@rpc()` action unless the client must transform values for UX before submitting.
+
+Back the form with a route-owned `@rpc()` action in the sibling `index.py`. If Prisma is enabled, the action should use the generated Prisma Python ORM for persistence.
+
+```python
+from casp.rpc import rpc
+from casp.validate import Validate
+from src.lib.prisma import prisma
+
+
+@rpc()
+async def save_profile(name: str, email: str, password: str = ""):
+    name = name.strip()
+    email = email.strip().lower()
+
+    if not name:
+        raise ValueError("Name is required.")
+    if Validate.with_rules(email, "required|email") is not True:
+        raise ValueError("A valid email address is required.")
+
+    profile = await prisma.user.update(
+        where={"email": email},
+        data={"name": name},
+    )
+
+    return profile.to_dict()
+```
+
+Basic two-way state pattern:
+
+```html
+<section>
+  <label>
+    Name
+    <input name="name" value="{name}" oninput="setName(event.target.value)" />
+  </label>
+
+  <p>Hello, {name || "friend"}.</p>
+  <button onclick="setName('')">Clear</button>
+
+  <script>
+    const [name, setName] = pp.state("");
+  </script>
+</section>
+```
 
 ## Authoring Model
 
@@ -447,14 +424,101 @@ Notes:
 - Keep template-facing bindings at the top level so the AST-based exporter can see them.
 - For predictable code generation, prefer passing an explicit dependency array to `pp.effect`, `pp.layoutEffect`, `pp.memo`, and `pp.callback`.
 
+Effect with cleanup and dependencies:
+
+```html
+<section>
+  <p>Elapsed: {seconds}s</p>
+  <button onclick="setRunning(!running)">{running ? "Pause" : "Resume"}</button>
+
+  <script>
+    const [seconds, setSeconds] = pp.state(0);
+    const [running, setRunning] = pp.state(true);
+
+    pp.effect(() => {
+      if (!running) return;
+      const id = setInterval(() => setSeconds((s) => s + 1), 1000);
+      return () => clearInterval(id);
+    }, [running]);
+  </script>
+</section>
+```
+
+Use the same shape for any subscription: attach in the effect body, detach in the returned cleanup. The cleanup also runs on component disposal, which is why route-owned `WebSocket` clients close their socket from a cleanup effect.
+
+Memoized derived value:
+
+```html
+<section>
+  <input value="{query}" oninput="setQuery(event.target.value)" />
+  <p>{visible.length} of {items.length} items</p>
+
+  <script>
+    const [query, setQuery] = pp.state("");
+    const items = pp.props.items ?? [];
+
+    const visible = pp.memo(
+      () => items.filter((item) => item.label.toLowerCase().includes(query.toLowerCase())),
+      [query]
+    );
+  </script>
+</section>
+```
+
+For cheap derivations, a plain top-level `const` recomputed each render is fine; reach for `pp.memo` when the computation is heavy or the result identity matters for dependencies.
+
+Reducer for multi-field update logic:
+
+```html
+<section>
+  <p>{cart.count} items, total {cart.total}</p>
+  <button onclick="dispatch({ type: 'add', price: 10 })">Add</button>
+  <button onclick="dispatch({ type: 'clear' })">Clear</button>
+
+  <script>
+    const [cart, dispatch] = pp.reducer((state, action) => {
+      if (action.type === "add") {
+        return { count: state.count + 1, total: state.total + action.price };
+      }
+      if (action.type === "clear") {
+        return { count: 0, total: 0 };
+      }
+      return state;
+    }, { count: 0, total: 0 });
+  </script>
+</section>
+```
+
+Portal pattern for overlays that must escape clipping ancestors:
+
+```html
+<div>
+  <button onclick="setOpen(true)">Open dialog</button>
+
+  <div pp-ref="dialogRef" hidden="{!open}" class="modal">
+    <p>Rendered under document.body.</p>
+    <button onclick="setOpen(false)">Close</button>
+  </div>
+
+  <script>
+    const [open, setOpen] = pp.state(false);
+    const dialogRef = pp.ref(null);
+
+    pp.portal(dialogRef);
+  </script>
+</div>
+```
+
+`pp.portal(ref)` moves the ref-managed element to `document.body` by default, or to the element passed as the second argument. Portaled content keeps its logical component ancestry, so context, props, and events keep working.
+
 ## Context
 
-Context is implemented in the current runtime with a React-style provider pattern rather than a legacy `pp.provideContext(...)` helper. Because Caspian templates are HTML-first, authored provider tags should be written in lowercase HTML form, for example `<themecontext.provider>`, even when the JavaScript token is named `ThemeContext`.
+Context is implemented in the current runtime with a React-style provider pattern rather than a legacy `pp.provideContext(...)` helper. Because Caspian templates are HTML-first, authored provider tags should be written in lowercase HTML form, for example `<themecontext.provider>`, even when the JavaScript token is named `ThemeContext`.
 
 How it works:
 
 - Create a token with `pp.createContext(defaultValue)`.
-- Provide a value with a lowercase provider tag such as `<themecontext.provider value="{theme}">`.
+- Provide a value with a lowercase provider tag such as `<themecontext.provider value="{theme}">`.
 - Read it in a descendant component with `pp.context(token)`.
 - Resolution walks the logical component parent chain stored in the registry, not the live DOM.
 - Portaled descendants still resolve providers through component ancestry.
@@ -468,24 +532,24 @@ Important:
 - Context is component-level, not directive-based. There is no `pp-context` attribute.
 - `pp.context(token)` resolves from ancestors. A component does not consume the value it provides in the same render.
 - If provider and consumer live in different component script scopes, pass the token through props or store it in shared outer or global state.
-- The preferred authoring style is a lowercase provider tag in the template. The TypeScript runtime's `TemplateCompiler.transformContextProviderTags(...)` recognizes `*.provider` tags case-insensitively and rewrites them to runtime-owned `<pp-context-provider>` boundaries. The runtime context lookup is also case-insensitive, so `<themecontext.provider>` can resolve a script binding named `ThemeContext`.
-- The runtime also supports imperative `ThemeContext.Provider({ value })` calls during render, but that form provides from the component boundary rather than documenting the HTML subtree shape. Use it only when component-wide provision is intended.
-- Do not invent or document `pp.provideContext`. The current runtime explicitly does not expose it.
+- The preferred authoring style is a lowercase provider tag in the template. The TypeScript runtime's `TemplateCompiler.transformContextProviderTags(...)` recognizes `*.provider` tags case-insensitively and rewrites them to runtime-owned `<pp-context-provider>` boundaries. The runtime context lookup is also case-insensitive, so `<themecontext.provider>` can resolve a script binding named `ThemeContext`.
+- The runtime also supports imperative `ThemeContext.Provider({ value })` calls during render, but that form provides from the component boundary rather than documenting the HTML subtree shape. Use it only when component-wide provision is intended.
+- Do not invent or document `pp.provideContext`. The current runtime explicitly does not expose it.
 
 Provider example:
 
 ```html
 <section>
-  <script>
-    const ThemeContext = pp.createContext("light");
-    const [theme] = pp.state("dark");
-  </script>
-
-  <themecontext.provider value="{theme}">
-    <p>This subtree receives the provided theme.</p>
-  </themecontext.provider>
-</section>
-```
+  <script>
+    const ThemeContext = pp.createContext("light");
+    const [theme] = pp.state("dark");
+  </script>
+
+  <themecontext.provider value="{theme}">
+    <p>This subtree receives the provided theme.</p>
+  </themecontext.provider>
+</section>
+```
 
 Consumer example for a child component that receives the token through props:
 
@@ -555,10 +619,10 @@ Example:
 </div>
 ```
 
-## Refs
-
-- Refs are for imperative element access. Do not use `pp-ref` as the default way to read normal form input values on submit; prefer the form's `onsubmit` event plus `Object.fromEntries(new FormData(event.currentTarget).entries())`.
-- Use `pp-ref="nameInput"` when the ref object or callback is already available in scope.
+## Refs
+
+- Refs are for imperative element access. Do not use `pp-ref` as the default way to read normal form input values on submit; prefer the form's `onsubmit` event plus `Object.fromEntries(new FormData(event.currentTarget).entries())`.
+- Use `pp-ref="nameInput"` when the ref object or callback is already available in scope.
 - Use `pp-ref="{registerRef(id)}"` when you want the compiler to capture a dynamic ref expression.
 - `pp.ref(null)` is the normal way to create a ref object.
 - Callback refs and `{ current }` refs are both supported.
@@ -618,19 +682,19 @@ Example:
 </div>
 ```
 
-## Events
-
-- Use native `on*` attributes such as `onclick`, `oninput`, `onchange`, and `onsubmit` for first-party events.
-- Treat this as the HTML form of `onClick`-style PulsePoint event binding. Prefer lowercase examples in authored HTML because the browser normalizes attribute names.
-- Event values may be raw code or wrapped in `{...}`.
-- The runtime injects `event`, `e`, `$event`, `target`, `currentTarget`, and `el`.
-- For form submit handlers, prefer `onsubmit="{submitForm(event)}"` and `Object.fromEntries(new FormData(event.currentTarget).entries())` when collecting named fields for `pp.rpc(...)`.
-- `event.target` can also work for form-level submit handlers, but examples use `event.currentTarget` so nested event origins do not change which element becomes the `FormData` source.
-- Do not use hyphenated event attrs like `on-click`.
-- Event attributes are removed from the live DOM after binding and rebound after DOM morphing.
-- Owned template/event-owner internals are runtime-managed. Do not author them directly.
-- Do not replace normal PulsePoint event attributes with id-driven `querySelector(...)` plus `addEventListener(...)` wiring. If an imperative listener is unavoidable for an integration, attach and clean it up from `pp.effect(...)`.
-- Do not replace a normal `onclick` with a `data-action`, `data-target`, or similar attribute plus a script that scans the DOM. PulsePoint event attributes are the event contract for first-party Caspian UI.
+## Events
+
+- Use native `on*` attributes such as `onclick`, `oninput`, `onchange`, and `onsubmit` for first-party events.
+- Treat this as the HTML form of `onClick`-style PulsePoint event binding. Prefer lowercase examples in authored HTML because the browser normalizes attribute names.
+- Event values may be raw code or wrapped in `{...}`.
+- The runtime injects `event`, `e`, `$event`, `target`, `currentTarget`, and `el`.
+- For form submit handlers, prefer `onsubmit="{submitForm(event)}"` and `Object.fromEntries(new FormData(event.currentTarget).entries())` when collecting named fields for `pp.rpc(...)`.
+- `event.target` can also work for form-level submit handlers, but examples use `event.currentTarget` so nested event origins do not change which element becomes the `FormData` source.
+- Do not use hyphenated event attrs like `on-click`.
+- Event attributes are removed from the live DOM after binding and rebound after DOM morphing.
+- Owned template/event-owner internals are runtime-managed. Do not author them directly.
+- Do not replace normal PulsePoint event attributes with id-driven `querySelector(...)` plus `addEventListener(...)` wiring. If an imperative listener is unavoidable for an integration, attach and clean it up from `pp.effect(...)`.
+- Do not replace a normal `onclick` with a `data-action`, `data-target`, or similar attribute plus a script that scans the DOM. PulsePoint event attributes are the event contract for first-party Caspian UI.
 
 ## SPA, loading, and navigation helpers
 
@@ -654,8 +718,9 @@ RPC notes:
 - Passing `true` as the third argument means `abortPrevious: true`.
 - The options object supports `abortPrevious`, `onStream`, `onStreamError`, `onStreamComplete`, `onUploadProgress`, and `onUploadComplete`.
 - File uploads switch to the XHR path when upload progress callbacks are needed.
+- The `onUploadProgress` callback receives `{ loaded, total, percent }`. `percent` is a 0-100 number, and both `total` and `percent` are `null` when the browser cannot compute the upload length. Do not document or generate `event.percentage`.
 - For file managers, use upload callbacks for progress UI but replace the asset list from returned RPC state with `pp.state(...)` and `pp-for` instead of manual DOM repainting. See [file-uploads.md](./file-uploads.md).
-- Streamed `text/event-stream` responses are supported when a stream handler is provided.
+- Streamed `text/event-stream` responses are supported when a stream handler is provided. Each `onStream` chunk is JSON-parsed when the event data looks like JSON; otherwise the raw string is passed through. If the response streams but no `onStream` handler was given, the runtime warns and discards the stream.
 - Redirect headers are honored through `pp.redirect()`.
 
 Notes:
@@ -664,6 +729,53 @@ Notes:
 - Root-layout mismatches during SPA navigation trigger a hard reload.
 - `pp.mount()` bootstraps every `[pp-component]` it finds, so generated code should call it only through the global runtime if you are manually mounting at all.
 
+Upload with progress pattern:
+
+```html
+<section>
+  <input type="file" onchange="{uploadFile(event.target.files?.[0])}" />
+  <progress max="100" value="{percent ?? 0}"></progress>
+
+  <script>
+    const [percent, setPercent] = pp.state(null);
+
+    async function uploadFile(file) {
+      if (!file) return;
+
+      await pp.rpc("upload_asset", { file }, {
+        onUploadProgress: ({ percent }) => setPercent(percent),
+        onUploadComplete: () => setPercent(100),
+      });
+    }
+  </script>
+</section>
+```
+
+Streaming pattern for server generators that return `text/event-stream`:
+
+```html
+<section>
+  <button onclick="ask()" disabled="{isStreaming}">Ask</button>
+  <pre>{answer}</pre>
+
+  <script>
+    const [answer, setAnswer] = pp.state("");
+    const [isStreaming, setIsStreaming] = pp.state(false);
+
+    function ask() {
+      setAnswer("");
+      setIsStreaming(true);
+
+      pp.rpc("ask_question", { topic: "caspian" }, {
+        onStream: (chunk) => setAnswer((current) => current + chunk),
+        onStreamError: () => setIsStreaming(false),
+        onStreamComplete: () => setIsStreaming(false),
+      });
+    }
+  </script>
+</section>
+```
+
 ## Runtime Output And Debugging
 
 When you inspect rendered HTML in the browser, you should expect to see runtime-managed attributes and elements that are not part of authored source.
@@ -684,23 +796,23 @@ These are runtime details.
 
 Use these rules when generating or editing PulsePoint runtime code:
 
-- Treat PulsePoint as the default reactive frontend for Caspian app code.
-- For first-party HTML interactions, use PulsePoint `on*` event attributes, state, refs, effects, directives, and `pp.rpc()` before reaching for DOM APIs.
-- For simple forms, bind `onsubmit` in the authored HTML and read named fields with `Object.fromEntries(new FormData(event.currentTarget).entries())`; do not generate per-input refs or effect-managed submit listeners just to gather values.
-- Treat `pp.rpc()` as the default browser-to-server path for CRUD operations and interactive backend reads.
+- Treat PulsePoint as the default reactive frontend for Caspian app code.
+- For first-party HTML interactions, use PulsePoint `on*` event attributes, state, refs, effects, directives, and `pp.rpc()` before reaching for DOM APIs.
+- For simple forms, bind `onsubmit` in the authored HTML and read named fields with `Object.fromEntries(new FormData(event.currentTarget).entries())`; do not generate per-input refs or effect-managed submit listeners just to gather values.
+- Treat `pp.rpc()` as the default browser-to-server path for CRUD operations and interactive backend reads.
 - Use `public/js/pp-reactive-v2.js` as the shipped runtime contract AI should follow.
 - Keep `main.py` in view because it injects the runtime-facing attributes and rewrites authored scripts before the browser sees them.
 - 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.
-- Avoid generating ids, `data-*` state, `querySelector`, `getElementById`, `addEventListener`, manual `innerHTML`, or custom event buses for normal Caspian UI behavior.
-- Avoid data-attribute click wiring such as `data-action="save"` plus a delegated listener. Use `onclick="save()"` or `onsubmit="{save(event)}"` in authored HTML and keep reactive state in `pp.state(...)`.
+- Prefer PulsePoint state and template directives over manual DOM mutation for reactive updates.
+- Avoid generating ids, `data-*` state, `querySelector`, `getElementById`, `addEventListener`, manual `innerHTML`, or custom event buses for normal Caspian UI behavior.
+- Avoid data-attribute click wiring such as `data-action="save"` plus a delegated listener. Use `onclick="save()"` or `onsubmit="{save(event)}"` in authored HTML and keep reactive state in `pp.state(...)`.
 - 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"]`.
 - Keep template-facing variables at top level.
-- Follow the HTML-first context pattern: `pp.createContext(...)`, a lowercase provider tag such as `<themecontext.provider value="{...}">`, and `pp.context(token)`.
+- Follow the HTML-first context pattern: `pp.createContext(...)`, a lowercase provider tag such as `<themecontext.provider value="{...}">`, and `pp.context(token)`.
 - Do not invent `pp.provideContext`, `pp-context`, or other legacy context helpers.
 - Keep `pp-for` on `<template>` and use plain `key`.
 - Use native `on*` attributes, not framework-specific event syntax.
@@ -715,9 +827,9 @@ Use these rules when generating or editing PulsePoint runtime code:
 
 Do not generate these unless the current source explicitly adds support:
 
-- React, Vue, Svelte, Alpine, HTMX, or JSX-first patterns as the default Caspian frontend approach
-- standard DOM scripting as the default first-party interaction model, including id/data-attribute driven `querySelector(...)`, `addEventListener(...)`, or manual `innerHTML` rendering for normal buttons, forms, filters, toggles, uploads, and reactive lists
-- `pp-context`
+- React, Vue, Svelte, Alpine, HTMX, or JSX-first patterns as the default Caspian frontend approach
+- standard DOM scripting as the default first-party interaction model, including id/data-attribute driven `querySelector(...)`, `addEventListener(...)`, or manual `innerHTML` rendering for normal buttons, forms, filters, toggles, uploads, and reactive lists
+- `pp-context`
 - `pp-key`
 - `data-pp-ref`
 - `pp-context-provider`
@@ -741,7 +853,7 @@ These are current runtime caveats that matter for authors and AI tools:
 - The global `pp` singleton auto-mounts on DOM ready, and `pp.mount()` is idempotent.
 - `pp.effect` and `pp.layoutEffect` are cleanup-style hooks. Their callbacks are not promise-aware.
 - `pp.context()` resolves through ancestor components, not the current component's own pending providers.
-- `pp.provideContext` is not part of the current runtime API. Use an HTML-first lowercase provider tag such as `<themecontext.provider>`.
+- `pp.provideContext` is not part of the current runtime API. Use an HTML-first lowercase provider tag such as `<themecontext.provider>`.
 - `pp.portal()` preserves logical ancestry through the registry, so context and prop refresh behavior continue to work through portaled descendants.
 
 ## Final reminder

package/dist/docs/websockets.md

@@ -0,0 +1,165 @@
+---
+title: WebSockets
+description: Use this page when the task mentions FastAPI WebSocket endpoints, live channels, broadcast managers, browser `WebSocket`, origin checks, or authenticated socket sessions in Caspian.
+related:
+  title: Related docs
+  description: Use routing and PulsePoint for client placement, auth for session policy, and the core runtime map for endpoint ownership in `main.py`.
+  links:
+    - /docs/routing
+    - /docs/pulsepoint
+    - /docs/auth
+    - /docs/fetch-data
+    - /docs/core-runtime-map
+    - /docs/index
+---
+
+WebSockets in Caspian are gated by `caspian.config.json` and implemented as app-owned FastAPI endpoints, not the default RPC data path.
+
+Use `@rpc()` plus `pp.rpc()` for ordinary browser-triggered reads, writes, uploads, and Server-Sent Event streams. Use WebSockets only when the task needs a bidirectional, long-lived channel such as live chat, collaboration, multiplayer state, server push that is not a good SSE fit, or presence.
+
+Treat `caspian.config.json` as the single source of truth for whether the WebSocket feature is enabled. If `websocket` is false, this page is reference material only; do not assume `@app.websocket(...)` endpoints, `src/lib/websocket/**`, or socket demo routes exist until the user chooses to enable the feature and the update workflow has run.
+
+## Source Of Truth
+
+Before adding, debugging, or documenting a WebSocket feature:
+
+- Read `caspian.config.json` first and confirm `websocket: true`.
+- If `websocket` is false and the user wants live channels, ask for confirmation before enabling it, then update the config and follow the project update workflow.
+- Inspect `main.py` for `@app.websocket(...)` routes, origin checks, close codes, message limits, idle timeout, and middleware interactions.
+- Inspect `src/lib/**` for app-owned socket helpers such as session extraction, auth payload checks, connection managers, or broadcast utilities.
+- Inspect the owning route under `src/app/**` for the browser client, first-render URL selection, and PulsePoint state around the native `WebSocket`.
+- Check `settings/bs-config.json` before testing development URLs through BrowserSync or a proxy.
+
+Packaged docs should describe this workflow generally. Keep endpoint names, route names, ports, and demo inventory project-owned; do not treat one app's route tree as the framework convention.
+
+## Recommended Shape
+
+When `caspian.config.json` has `websocket: true`, put socket endpoints in `main.py` when they are application-level ASGI routes:
+
+```python
+from fastapi import WebSocket, WebSocketDisconnect, status
+
+WEBSOCKET_PATH = "/ws/channel"
+
+@app.websocket(WEBSOCKET_PATH)
+async def websocket_live_endpoint(websocket: WebSocket):
+    if not is_origin_allowed(websocket):
+        await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
+        return
+
+    await manager.connect(websocket)
+    try:
+        while True:
+            raw_message = await websocket.receive_text()
+            ...
+    except WebSocketDisconnect:
+        return
+    finally:
+        manager.disconnect(websocket)
+```
+
+Keep reusable socket helpers in `src/lib/**` when they are shared by more than one endpoint or route. Good candidates include connection managers, session helpers, auth-payload extraction, payload normalization, and shared broadcast code.
+
+Keep route-specific browser UI in `src/app/**/index.html` and route-specific first-render values in the matching `index.py`. For example, an `index.py` can pass `websocket_path` and a development-only BrowserSync-aware `websocket_url` into the template with `render_page(__file__, {...})`.
+
+## Browser Client Pattern
+
+Use PulsePoint for the component state and lifecycle, while using the native browser `WebSocket` object for the socket itself.
+
+```html
+<main>
+  <button onclick="{connectSocket()}" disabled="{isConnected}">Connect</button>
+  <button onclick="{disconnectSocket()}" disabled="{!isConnected}">Disconnect</button>
+
+  <script>
+    const websocketPath = "{{ websocket_path }}";
+    const socketRef = pp.ref(null);
+    const [status, setStatus] = pp.state("idle");
+    const isConnected = status === "connected";
+
+    function buildWebSocketUrl(path) {
+      const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
+      return new URL(`${protocol}//${window.location.host}${path}`, window.location.href).toString();
+    }
+
+    function connectSocket() {
+      const socket = new WebSocket(buildWebSocketUrl(websocketPath));
+      socketRef.current = socket;
+
+      socket.addEventListener("message", (event) => {
+        const payload = JSON.parse(event.data);
+        ...
+      });
+    }
+
+    function disconnectSocket() {
+      socketRef.current?.close(1000, "Client disconnect");
+      socketRef.current = null;
+    }
+
+    pp.effect(() => {
+      return () => socketRef.current?.close(1000, "Page disposed");
+    }, []);
+  </script>
+</main>
+```
+
+This is one of the narrow cases where direct browser APIs and event listeners are expected. Keep them inside the owning PulsePoint component script, store the socket in `pp.ref(...)`, and keep rendered UI state in `pp.state(...)`.
+
+## Auth And Sessions
+
+HTTP route privacy does not automatically make a WebSocket endpoint private. If a socket is authenticated, the endpoint must explicitly inspect the session or auth payload available on the WebSocket scope and close unauthenticated clients.
+
+Use close code `1008` for policy violations such as failed origin checks or missing authentication. If the endpoint accepts before rejecting, send a small JSON error payload first so the browser UI can show a useful message.
+
+If the app refreshes auth sessions, verify whether the WebSocket helper refreshes session expiry and whether that session mutation is persisted in the current middleware stack. Do not assume HTTP `AuthMiddleware` behavior applies to `scope["type"] == "websocket"`.
+
+## Origin And Proxy Checks
+
+WebSocket endpoints should validate the `Origin` header before accepting connections, especially in production.
+
+Common allowed origins:
+
+- same-origin derived from the socket URL
+- explicit values from environment variables such as `WEBSOCKET_ALLOWED_ORIGINS`, `CORS_ALLOWED_ORIGINS`, `APP_BASE_URL`, `PUBLIC_BASE_URL`, or `SITE_URL`
+- localhost HTTP origins in development when the app intentionally permits local BrowserSync or proxy testing
+
+When testing locally, read `settings/bs-config.json` first and build `ws://` or `wss://` URLs from its active `local` value. Do not assume the BrowserSync port is the default.
+
+## Message Contract
+
+Document the JSON message contract near the endpoint and client that own it.
+
+Useful baseline conventions:
+
+- Clients send JSON objects, usually `{ "type": "message", "text": "..." }` or `{ "type": "ping" }`.
+- Servers send `ready`, `message`, `error`, and `pong` payloads as JSON.
+- Enforce a maximum incoming message size before parsing or broadcasting.
+- Close idle sockets after a configured timeout when the app does not need long silent connections.
+- Sanitize or trim outbound text so one client cannot broadcast unbounded data.
+- Disconnect stale sockets when sends fail.
+
+## WebSockets Vs RPC/SSE
+
+Choose the transport deliberately:
+
+| Need | Preferred transport |
+| --- | --- |
+| CRUD, form submits, button actions, upload progress | `@rpc()` plus `pp.rpc()` |
+| Server sends one-way progress chunks for a request | RPC streaming / SSE |
+| Browser and server both send messages over a persistent channel | WebSocket |
+| Presence, collaboration, live chat, multiplayer state | WebSocket |
+
+Do not replace normal Caspian RPC with WebSockets just because a page is interactive.
+
+## AI Retrieval Notes
+
+If an AI agent is working on WebSockets in a Caspian app:
+
+- Start with `caspian.config.json`. Continue only after confirming `websocket: true`, unless the task is specifically to enable the feature.
+- Use [core-runtime-map.md](./core-runtime-map.md) to connect `main.py` behavior back to this doc.
+- Use [routing.md](./routing.md) before changing the route files that render the client.
+- Use [pulsepoint.md](./pulsepoint.md) for authored template rules and component lifecycle cleanup.
+- Use [auth.md](./auth.md) before changing authenticated socket behavior.
+- Keep reusable connection/session helpers in `src/lib/websocket/**` when they are shared; keep route UI in whichever `src/app/**` route owns the live experience; keep app-level ASGI endpoints in `main.py` unless the runtime intentionally provides another registration layer.
+- Verify local test URLs from `settings/bs-config.json`.

package/package.json

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