caspian-utils 0.1.2 → 0.1.3

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/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.3",
   "description": "Caspian tooling",
   "main": "index.js",
   "scripts": {