caspian-utils 0.1.5 → 0.1.7

package/dist/docs/auth.md

@@ -20,14 +20,14 @@ Treat `casp.auth` as the default authentication layer in Caspian app code. Do no
 
 ## Overview
 
-Caspian authentication has two main layers:
-
-- app-level policy, controlled by `src/lib/auth/auth_config.py`
-- framework runtime behavior, implemented by `.venv/Lib/site-packages/casp/auth.py`
+Caspian authentication has two main layers:
+
+- app-level policy, controlled by `src/lib/auth/auth_config.py`
+- framework runtime behavior, implemented by `.venv/Lib/site-packages/casp/auth.py`
 
 The main public API includes:
 
-- `AuthSettings` for centralized app auth policy
+- `AuthSettings` for centralized app auth policy
 - `configure_auth(...)` and `get_auth_settings()` for app startup and reads
 - the global `auth` object for session lifecycle work
 - `require_auth`, `require_role`, and `guest_only` for page-level protection
@@ -49,7 +49,7 @@ from casp.auth import (
 
 ## Default Auth Rule
 
-- Define app-wide auth behavior in `src/lib/auth/auth_config.py` through `build_auth_settings()` and apply it once at startup with `configure_auth(...)`.
+- Define app-wide auth behavior in `src/lib/auth/auth_config.py` through `build_auth_settings()` and apply it once at startup with `configure_auth(...)`.
 - Use `auth.sign_in(...)` and `auth.sign_out(...)` instead of setting or clearing session keys directly.
 - Prefer `pp.rpc(...)` plus `@rpc(require_auth=True)` for signout buttons or menus rendered in pages or components. Use a dedicated signout route only when you need a plain HTML form POST or a no-JavaScript fallback.
 - Use `@require_auth`, `@require_role`, and `@guest_only` for page access rules.
@@ -61,15 +61,15 @@ from casp.auth import (
 
 ## Framework Internals Note
 
-- The centralized app auth policy controller is `src/lib/auth/auth_config.py`.
-- The installed framework implementation lives in `.venv/Lib/site-packages/casp/auth.py`.
-- Treat `auth_config.py` as project code and `casp/auth.py` as framework runtime code. Do not edit `casp/auth.py` to control app route privacy, redirects, or RBAC.
+- The centralized app auth policy controller is `src/lib/auth/auth_config.py`.
+- The installed framework implementation lives in `.venv/Lib/site-packages/casp/auth.py`.
+- Treat `auth_config.py` as project code and `casp/auth.py` as framework runtime code. Do not edit `casp/auth.py` to control app route privacy, redirects, or RBAC.
 - If upstream docs and the installed implementation disagree, prefer the installed implementation for local project guidance.
 - Use [core-runtime-map.md](./core-runtime-map.md) when an auth task crosses `main.py` bootstrap behavior such as development cookie scoping or middleware ownership.
 
 ## Centralized Auth Settings
 
-Keep application auth policy in `src/lib/auth/auth_config.py`. This file is the controller for route privacy, redirects, and RBAC.
+Keep application auth policy in `src/lib/auth/auth_config.py`. This file is the controller for route privacy, redirects, and RBAC.
 
 Example:
 
@@ -80,12 +80,12 @@ from casp.auth import AuthSettings
 
 def build_auth_settings() -> AuthSettings:
     """
-    Centralized app auth policy controller.
-
-    Keep secrets (AUTH_SECRET, AUTH_COOKIE_NAME) in .env.
-    Keep app-level session settings in .env (SESSION_LIFETIME_HOURS, etc).
-    Decide route privacy, redirects, and RBAC here at app setup time instead of
-    changing Caspian core runtime files.
+    Centralized app auth policy controller.
+
+    Keep secrets (AUTH_SECRET, AUTH_COOKIE_NAME) in .env.
+    Keep app-level session settings in .env (SESSION_LIFETIME_HOURS, etc).
+    Decide route privacy, redirects, and RBAC here at app setup time instead of
+    changing Caspian core runtime files.
     """
 
     return AuthSettings(
@@ -103,7 +103,7 @@ def build_auth_settings() -> AuthSettings:
         is_role_based=False,
         role_identifier="role",
 
-        # RBAC policy is app-owned here; the runtime expects ROUTE/PATTERN -> [ROLES].
+        # RBAC policy is app-owned here; the runtime expects ROUTE/PATTERN -> [ROLES].
         role_based_routes={},
 
         # Redirects / prefixes
@@ -152,7 +152,7 @@ Make this decision at app setup time in `src/lib/auth/auth_config.py`.
 - In the current runtime, `auth_routes=["/signin", "/signup"]` stays public by default, and most apps do not need to change it unless the user explicitly asks for different auth routes.
 - In all-private mode, the default `public_routes=["/"]` keeps the home page public unless you change that list.
 - `token_auto_refresh=True` does not make routes private. It only enables sliding-session refresh when the request lifecycle calls `auth.refresh_session()`.
-- Do not modify Caspian core files for this decision. Keep the policy in `src/lib/auth/auth_config.py`.
+- Do not modify Caspian core files for this decision. Keep the policy in `src/lib/auth/auth_config.py`.
 - If you customize `src/lib/auth/auth_config.py`, add it to `excludeFiles` in `caspian.config.json` so update commands do not overwrite your local auth policy.
 
 Example all-private setup with a few public exceptions:
@@ -720,6 +720,33 @@ In the installed implementation:
 
 The installed `casp.auth` file includes provider helpers for Google and GitHub OAuth.
 
+In the app-owned starter bootstrap, both providers are already registered. Treat Google and GitHub sign-in as a shipped feature, not something to build from scratch. The current `main.py` calls:
+
+```python
+Auth.set_providers(GithubProvider(), GoogleProvider())
+```
+
+so `AuthMiddleware` already delegates the provider signin and callback paths through `auth.auth_providers(...)` on every request. To add a working social sign-in to a page, you usually need only two things:
+
+- a link or button that navigates to the provider signin path, and
+- the provider credentials in `.env`.
+
+The signin and callback paths live under `api_auth_prefix` (default `/api/auth`):
+
+- Google sign-in link target: `/api/auth/signin/google`
+- GitHub sign-in link target: `/api/auth/signin/github`
+- Google callback (provider-side redirect URI): `/api/auth/callback/google`
+- GitHub callback (provider-side redirect URI): `/api/auth/callback/github`
+
+Minimal sign-in button:
+
+```html
+<a href="/api/auth/signin/google">Continue with Google</a>
+<a href="/api/auth/signin/github">Continue with GitHub</a>
+```
+
+Do not reinvent this flow. When a task asks for Google or GitHub login, do not add `authlib`, a hand-written `httpx` token-exchange, a parallel session writer, or custom `/callback` route handlers. The shipped providers plus `auth.auth_providers(...)` already perform the redirect, the code exchange, payload normalization, `auth.sign_in(...)`, and the post-login redirect to `default_signin_redirect`. Reuse them and keep credentials in `.env`.
+
 Available provider classes:
 
 - `GoogleProvider(client_id, client_secret, redirect_uri, max_age="30d")`
@@ -767,7 +794,7 @@ Behavior:
 
 Use this helper when custom form or fetch flows need access to the session CSRF token.
 
-## Current Implementation Notes
+## Current Implementation Notes
 
 - The installed auth runtime is session-backed. It stores the auth payload and CSRF token in `request.session`.
 - Expiration uses timestamps and the current duration parser only accepts `s`, `m`, `h`, and `d` units.
@@ -810,7 +837,7 @@ If an AI agent is deciding how to handle auth in Caspian, apply these rules firs
 - Treat `public_routes` as the public exception list for all-private apps. In the current defaults, `/` stays public and `auth_routes=["/signin", "/signup"]` stays public too.
 - For protected grouped sections, follow the section layout pattern in [routing.md](./routing.md) and keep auth-specific route policy in `src/lib/auth/auth_config.py`.
 - Apply settings at startup in `main.py` with `configure_auth(build_auth_settings())`.
-- Register provider instances in `main.py` with `Auth.set_providers(...)` when Google or GitHub OAuth is enabled.
+- Treat Google and GitHub OAuth as shipped: the starter `main.py` already registers both providers with `Auth.set_providers(GithubProvider(), GoogleProvider())`. For social sign-in, link to `/api/auth/signin/{google,github}` and set `.env` credentials; do not hand-roll OAuth, token exchange, or callback routes. Only call `Auth.set_providers(...)` yourself if you are changing which providers are registered.
 - Use `auth.sign_in(...)` and `auth.sign_out(...)` for session lifecycle changes.
 - Prefer `pp.rpc("signout")` plus `@rpc(require_auth=True)` for logout buttons or menus in pages and components.
 - Use a dedicated `/signout` route only for plain HTML form POST, no-JavaScript fallback, or other full-navigation edge cases.

package/dist/docs/fetch-data.md

@@ -21,13 +21,13 @@ related:
 
 This page explains how data fetching works in Caspian. Use route functions for initial page data and use RPC actions for browser-triggered reads, writes, streams, uploads, and normal CRUD work.
 
-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.
+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.
 
 MCP is a separate integration surface. Do not place app-owned FastMCP tools in route `index.py` files or treat `@rpc()` actions as a replacement for MCP tools. Use `mcp.md` and `src/lib/mcp/` only when `caspian.config.json` has `mcp: true`. If `mcp` is false, do not assume those files exist.
 
@@ -35,7 +35,7 @@ MCP is a separate integration surface. Do not place app-owned FastMCP tools in r
 
 Caspian has two main data-loading paths:
 
-- `page()` for initial-render data, plus `layout()` for shared props or metadata during the render
+- `page()` for initial-render data, plus `layout()` for shared props or metadata during the render
 - `@rpc()` plus `pp.rpc()` for interactive fetches after the page is already loaded
 
 In practice, most pages use both:
@@ -50,13 +50,13 @@ When a page belongs to a grouped subtree such as a dashboard, account area, admi
 
 ## Default Data Rule
 
-- Use `page()` for route-level data required before HTML renders, and use `layout()` only for shared subtree props or metadata.
+- Use `page()` for route-level data required before HTML renders, and use `layout()` only for shared subtree props or metadata.
 - When a route renders UI and also needs backend work, keep the HTML in the sibling `index.html`; `index.py` should prepare data and call `render_page(__file__, ...)`, not inline the route markup.
-- Use `@rpc()` on the server and `pp.rpc()` in PulsePoint code for all browser-triggered data work after first render, including CRUD operations and follow-up reads.
-- When Prisma is enabled, route all Python database I/O inside `page()`, `layout()` when truly shared, `@rpc()` actions, and reusable helpers through the generated Prisma Python ORM.
-- Trigger those browser actions through PulsePoint event attributes in the HTML, not through a separate DOM listener layer.
-- For simple form submits, prefer `onsubmit="{submitForm(event)}"` plus `Object.fromEntries(new FormData(event.currentTarget).entries())` over `pp-ref` fields and effect-managed submit listeners.
-- Keep custom REST or other endpoint patterns as explicit exceptions, not the baseline Caspian approach.
+- Use `@rpc()` on the server and `pp.rpc()` in PulsePoint code for all browser-triggered data work after first render, including CRUD operations and follow-up reads.
+- When Prisma is enabled, route all Python database I/O inside `page()`, `layout()` when truly shared, `@rpc()` actions, and reusable helpers through the generated Prisma Python ORM.
+- Trigger those browser actions through PulsePoint event attributes in the HTML, not through a separate DOM listener layer.
+- For simple form submits, prefer `onsubmit="{submitForm(event)}"` plus `Object.fromEntries(new FormData(event.currentTarget).entries())` over `pp-ref` fields and effect-managed submit listeners.
+- Keep custom REST or other endpoint patterns as explicit exceptions, not the baseline Caspian approach.
 
 ## Initial Data In `index.py`
 
@@ -87,11 +87,11 @@ If a route's first-render HTML is public and stable enough to reuse across reque
 Notes:
 
 - Prefer `async def page()` when your database or API client is async-capable.
-- Put shared section-level props in `layout.py` when multiple child routes need the same payload. The current layout engine supports synchronous and async `layout()` results, but route-specific data should stay in `page()`.
+- Put shared section-level props in `layout.py` when multiple child routes need the same payload. The current layout engine supports synchronous and async `layout()` results, but route-specific data should stay in `page()`.
 - Use a normal parent folder such as `dashboard/` when the section name should appear in the URL. Use a route-group folder such as `(reports)/` only when the shared wrapper should organize child routes without adding a URL segment.
 - Keep reusable database or API clients under `src/lib/`; keep route-specific orchestration in `src/app/`.
 
-If the data source is Prisma, confirm `caspian.config.json` has `prisma: true`, then see `database.md` for the project's schema, migration, and generation workflow. If the project includes an app-owned Python database layer under `src/lib/prisma/`, reuse it instead of creating another helper. In Prisma-enabled projects, direct driver access and custom fetch helpers are exceptions to avoid, not alternate defaults.
+If the data source is Prisma, confirm `caspian.config.json` has `prisma: true`, then see `database.md` for the project's schema, migration, and generation workflow. If the project includes an app-owned Python database layer under `src/lib/prisma/`, reuse it instead of creating another helper. In Prisma-enabled projects, direct driver access and custom fetch helpers are exceptions to avoid, not alternate defaults.
 
 ## Interactive Data With RPC
 
@@ -113,18 +113,18 @@ from src.lib.prisma import prisma
 async def list_todos():
     return await prisma.todo.find_many()
 
-@rpc(require_auth=True, limits="20/minute")
-async def create_todo(title: str):
-    title = title.strip()
-    if not title:
-        raise ValueError("Title is required.")
-
-    return await prisma.todo.create(
-        data={"title": title, "completed": False}
-    )
+@rpc(require_auth=True, limits="20/minute")
+async def create_todo(title: str):
+    title = title.strip()
+    if not title:
+        raise ValueError("Title is required.")
+
+    return await prisma.todo.create(
+        data={"title": title, "completed": False}
+    )
 ```
 
-Call it from the client with `pp.rpc()`:
+Call it from the client with `pp.rpc()`:
 
 ```html
 <script>
@@ -137,39 +137,39 @@ Call it from the client with `pp.rpc()`:
     const todo = await pp.rpc("create_todo", { title });
     console.log(todo);
   }
-</script>
-```
-
-Do not call `fetch("/api/todos")` from the browser for normal Caspian CRUD when the route can expose an `@rpc()` action. Do not use `fetch()` or a database driver in Python to work around Prisma when `src/lib/prisma/**` already provides the generated ORM client.
-
-For form submissions, let the form event provide the submitted values. The inputs' `name` attributes define the RPC payload keys, and the Python action owns trimming, validation, coercion, and persistence decisions.
-
-```html
-<form onsubmit="{createTodoFromForm(event)}" novalidate>
-  <input name="title" required />
-  <button type="submit" disabled="{isSaving}">Add</button>
-
-  <script>
-    const [isSaving, setIsSaving] = pp.state(false);
-
-    async function createTodoFromForm(event) {
-      event.preventDefault();
-
-      const data = Object.fromEntries(new FormData(event.currentTarget).entries());
-      if (isSaving) return;
-
-      setIsSaving(true);
-      try {
-        await pp.rpc("create_todo", data, { abortPrevious: true });
-      } finally {
-        setIsSaving(false);
-      }
-    }
-  </script>
-</form>
-```
-
-Use RPC for:
+</script>
+```
+
+Do not call `fetch("/api/todos")` from the browser for normal Caspian CRUD when the route can expose an `@rpc()` action. Do not use `fetch()` or a database driver in Python to work around Prisma when `src/lib/prisma/**` already provides the generated ORM client.
+
+For form submissions, let the form event provide the submitted values. The inputs' `name` attributes define the RPC payload keys, and the Python action owns trimming, validation, coercion, and persistence decisions.
+
+```html
+<form onsubmit="{createTodoFromForm(event)}" novalidate>
+  <input name="title" required />
+  <button type="submit" disabled="{isSaving}">Add</button>
+
+  <script>
+    const [isSaving, setIsSaving] = pp.state(false);
+
+    async function createTodoFromForm(event) {
+      event.preventDefault();
+
+      const data = Object.fromEntries(new FormData(event.currentTarget).entries());
+      if (isSaving) return;
+
+      setIsSaving(true);
+      try {
+        await pp.rpc("create_todo", data, { abortPrevious: true });
+      } finally {
+        setIsSaving(false);
+      }
+    }
+  </script>
+</form>
+```
+
+Use RPC for:
 
 - CRUD reads and writes after the initial render
 - Button-triggered refreshes
@@ -186,8 +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 [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.
+- 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
 
@@ -227,6 +227,43 @@ Client example:
 
 Use streaming when the user should see partial progress instead of waiting for a single final payload.
 
+This is the shipped, default mechanism for AI/LLM/chat token streaming in Caspian. When a task asks for a chat app, an assistant reply, or any "stream the model's tokens as they arrive" experience, use this RPC streaming path. Do not reinvent one-way streaming with raw `fetch` + `ReadableStream`, a browser `EventSource`, or a WebSocket. WebSockets are only for genuinely bidirectional channels (see [websockets.md](./websockets.md)); a one-way token stream from server to browser belongs in a generator `@rpc()` consumed by `pp.rpc(..., { onStream })`.
+
+Bridging a Python LLM/SDK stream is the common case: `async for` over the provider's streaming response inside the `@rpc()` action and `yield` each chunk. The runtime turns the generator into an SSE response automatically.
+
+```python
+from casp.rpc import rpc
+from anthropic import AsyncAnthropic
+
+client = AsyncAnthropic()
+
+@rpc(require_auth=True, limits="20/minute")
+async def chat(message: str):
+    async with client.messages.stream(
+        model="claude-opus-4-8",
+        max_tokens=1024,
+        messages=[{"role": "user", "content": message}],
+    ) as stream:
+        async for text in stream.text_stream:
+            yield text
+```
+
+Client side, append each chunk to reactive state so the UI grows token by token:
+
+```html
+<script>
+  const [answer, setAnswer] = pp.state("");
+
+  async function send(message) {
+    setAnswer("");
+    await pp.rpc("chat", { message }, {
+      onStream: (chunk) => setAnswer((current) => current + chunk),
+      onStreamComplete: () => console.log("done"),
+    });
+  }
+</script>
+```
+
 In the current runtime, generator and async-generator RPC results are wrapped with `SSE(...)` inside `casp.rpc.py`, and route-level generator results are also wrapped by `main.py` before the response is returned.
 
 ## File Uploads
@@ -334,7 +371,7 @@ For initial route rendering with `render_page(...)`, prefer passing plain templa
 
 ## Recommended Decision Rule
 
-Use `page()` when route-specific data is part of the page render. Use `layout()` for shared subtree props or metadata. Use `@rpc()` plus `pp.rpc()` when the browser needs to ask the server for more data after the page is already visible.
+Use `page()` when route-specific data is part of the page render. Use `layout()` for shared subtree props or metadata. Use `@rpc()` plus `pp.rpc()` when the browser needs to ask the server for more data after the page is already visible.
 
 A common pattern is:
 
@@ -366,8 +403,8 @@ If the first-render HTML is expensive to produce and safe to share between visit
 If an AI agent is choosing how to load data in Caspian, apply these rules first.
 
 - Put first-render data loading in `src/app/**/index.py`.
-- Put shared section props in `layout.py` only when multiple child routes need the same shared data.
-- Keep route-specific async I/O in `page()` or `@rpc()` so `layout.py` stays focused on shared subtree props or metadata.
+- Put shared section props in `layout.py` only when multiple child routes need the same shared data.
+- Keep route-specific async I/O in `page()` or `@rpc()` so `layout.py` stays focused on shared subtree props or metadata.
 - For grouped subtrees, follow the section layout pattern in [routing.md](./routing.md) before deciding where `page()` data and `@rpc()` actions belong.
 - Treat RPC as the default read and write layer between PulsePoint code and Python route logic, especially for CRUD and interactive backend reads.
 - Use `@rpc()` for backend functions that should be callable from the browser.
@@ -377,6 +414,7 @@ If an AI agent is choosing how to load data in Caspian, apply these rules first.
 - Use [cache.md](./cache.md) when a route's initial HTML should be reused across requests and invalidated after writes.
 - Use [state.md](./state.md) when an RPC mutation needs transient request-scoped success or error state outside the direct response payload.
 - Use `onStream` for streamed responses and `onUploadProgress` for upload-aware client calls.
+- For AI/LLM/chat token streaming, default to a generator `@rpc()` that `yield`s chunks (bridge a Python SDK stream with `async for ... yield`) consumed by `pp.rpc(..., { onStream })`. Do not reinvent one-way streaming with raw `fetch`/`ReadableStream`, `EventSource`, or WebSockets.
 - Add `require_auth`, `allowed_roles`, and `limits` to sensitive RPC actions.
 - Keep reusable database clients and service wrappers in `src/lib/`.
 - Use `.venv/Lib/site-packages/casp/rpc.py` only when the task is about Caspian core RPC internals or framework debugging.

package/dist/docs/pulsepoint.md

@@ -346,11 +346,12 @@ Important:
 - The script lookup walks the current root and skips nested `pp-component` boundaries, so a parent does not consume a child component's script.
 - If multiple matching runtime scripts exist in the same root, the first matching owned script wins. Generate one script per root.
 - Authored route, layout, and component templates still need one top-level parent node so Caspian can inject the component boundary correctly after component expansion.
-- A scriptless component root still mounts and can receive props, refs, events, and nested children, but it has no local runtime scope beyond its props.
+- A scriptless component root still mounts and can receive props, refs, events, and nested children, but it does not create local bindings from those props on its own.
 - Component scripts are plain JavaScript executed with `new Function(...)`. Do not use `import`, `export`, or top-level `await` inside them.
 - The runtime auto-returns supported top-level bindings from the script. Do not rely on manual `return { ... }` objects.
-- `pp.props` contains the current prop bag for the component.
-- `pp.props.children` contains the root's initial inner HTML before the owned script is removed from the render template.
+- `pp.props` contains the current prop bag for the component.
+- `pp.props.children` contains the root's initial inner HTML before the owned script is removed from the render template.
+- Props are not auto-injected as standalone top-level template or handler variables. Read them through `pp.props` or explicitly destructure them in the component script.
 
 Bindings exported to the template:
 
@@ -569,12 +570,13 @@ When a child component needs the same token object, pass it from the provider sc
 
 - Child component props are derived from DOM attributes.
 - Attribute names are converted from kebab-case to camelCase for the prop bag.
-- Native `on*` attributes and `pp-component` are not included in props.
-- Empty attributes become boolean `true` props.
-- Pure prop expressions such as `title="{pageTitle}"` are evaluated in the parent scope.
-- Mixed strings such as `class="card {isActive ? 'active' : ''}"` are interpolated in the parent scope.
-- Non-expression attribute values are passed through as strings.
-- `children` is injected into props using the root's initial inner HTML.
+- Native `on*` attributes and `pp-component` are not included in props.
+- Empty attributes become boolean `true` props.
+- Pure prop expressions such as `title="{pageTitle}"` are evaluated in the parent scope.
+- Mixed strings such as `class="card {isActive ? 'active' : ''}"` are interpolated in the parent scope.
+- Non-expression attribute values are passed through as strings.
+- `children` is injected into props using the root's initial inner HTML.
+- Inside the child component, those values should be accessed through `pp.props` or a top-level destructure such as `const { title } = pp.props`; they are not implicitly available as bare identifiers.
 
 Nested components:
 
@@ -751,7 +753,7 @@ Upload with progress pattern:
 </section>
 ```
 
-Streaming pattern for server generators that return `text/event-stream`:
+Streaming pattern for server generators that return `text/event-stream`. This is the default path for AI/LLM/chat token streaming: a generator `@rpc()` that `yield`s tokens (often by `async for`-ing over a Python SDK stream) consumed by `pp.rpc(..., { onStream })` that appends each chunk to reactive state. Do not reinvent one-way streaming with raw `fetch`/`ReadableStream`, `EventSource`, or a WebSocket; see [fetch-data.md](./fetch-data.md) for the Python side.
 
 ```html
 <section>

package/package.json

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