caspian-utils 0.0.34 → 0.1.1

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

@@ -55,14 +55,14 @@ Use prompts like these to check whether AI lands on the correct docs and files.
 | Create a protected dashboard section with child routes and a shared shell. | [index.md](./index.md), [routing.md](./routing.md), [auth.md](./auth.md), [project-structure.md](./project-structure.md) | `src/app/**`, `src/lib/auth/auth_config.py`, `main.py`, `.venv/Lib/site-packages/casp/layout.py` | section layout ownership, route privacy mode, and child-route wrapping |
 | Make a grouped shell keep sidebar scroll while resetting page content on child-route navigation. | [index.md](./index.md), [routing.md](./routing.md), [pulsepoint.md](./pulsepoint.md), [core-runtime-map.md](./core-runtime-map.md) | `src/app/**/layout.html`, `public/js/pp-reactive-v2.js`, `main.py` | `pp-reset-scroll` placement, push-vs-history scroll behavior, and shared-shell ownership |
 | Create a new contact page with interactive form behavior. | [index.md](./index.md), [routing.md](./routing.md), [pulsepoint.md](./pulsepoint.md), [components.md](./components.md) | `src/app/**/index.html`, `main.py`, `.venv/Lib/site-packages/casp/components_compiler.py`, `.venv/Lib/site-packages/casp/scripts_type.py` | single-root template shape, script-inside-root authoring, and authored-vs-runtime boundaries |
-| Add a button, filter, or form interaction to a route template. | [index.md](./index.md), [routing.md](./routing.md), [pulsepoint.md](./pulsepoint.md), [pulsepoint-runtime-map.md](./pulsepoint-runtime-map.md) | `src/app/**/index.html`, `public/js/pp-reactive-v2.js`, `main.py` | PulsePoint `on*` event attributes, `pp.state`, directives, and avoiding id-driven `querySelector` or `addEventListener` wiring |
+| Add a button, filter, or form interaction to a route template. | [index.md](./index.md), [routing.md](./routing.md), [pulsepoint.md](./pulsepoint.md), [pulsepoint-runtime-map.md](./pulsepoint-runtime-map.md) | `src/app/**/index.html`, `public/js/pp-reactive-v2.js`, `main.py` | PulsePoint `on*` event attributes, `pp.state`, directives, `Object.fromEntries(new FormData(...).entries())` for simple form submits, and avoiding id-driven `querySelector` or `addEventListener` wiring |
 | Add a file manager page with upload progress and persisted metadata. | [index.md](./index.md), [file-uploads.md](./file-uploads.md), [fetch-data.md](./fetch-data.md), [database.md](./database.md) | `src/app/**/index.html`, `src/app/**/index.py`, `src/lib/**`, `prisma/schema.prisma` when Prisma applies | route-owned upload actions, persisted metadata flow, and Prisma-backed storage boundaries |
 | Explain why authored Caspian templates use a plain `<script>` instead of `type="text/pp"`. | [index.md](./index.md), [pulsepoint.md](./pulsepoint.md), [components.md](./components.md), [routing.md](./routing.md) | `main.py`, `.venv/Lib/site-packages/casp/scripts_type.py`, `.venv/Lib/site-packages/casp/components_compiler.py` | script rewriting, `pp-component` injection, and authored-vs-runtime boundaries |
 | Debug why `StateManager` does not persist across a full redirect. | [index.md](./index.md), [state.md](./state.md), [auth.md](./auth.md), [core-runtime-map.md](./core-runtime-map.md) | `main.py`, `.venv/Lib/site-packages/casp/state_manager.py` | wire vs non-wire reset behavior and `request.state.session` dependency |
 | Trace the auth cookie and CSRF cookie names used in development. | [index.md](./index.md), [auth.md](./auth.md), [core-runtime-map.md](./core-runtime-map.md) | `main.py`, `.venv/Lib/site-packages/casp/auth.py` | development cookie scoping and CSRF or session naming ownership |
 | Find how route params and query params reach `page()`. | [index.md](./index.md), [routing.md](./routing.md), [core-runtime-map.md](./core-runtime-map.md) | `main.py`, `.venv/Lib/site-packages/casp/layout.py` | path-dict delivery, query coercion, and `request` injection |
 | Decide whether a dashboard child route should use page caching. | [index.md](./index.md), [cache.md](./cache.md), [routing.md](./routing.md), [fetch-data.md](./fetch-data.md) | `main.py`, `.venv/Lib/site-packages/casp/cache_handler.py`, the route's `index.py` | route-level cache ownership, cacheable HTML scope, and invalidation points |
-| Add a PulsePoint context provider to a reusable component. | [index.md](./index.md), [pulsepoint-runtime-map.md](./pulsepoint-runtime-map.md), [pulsepoint.md](./pulsepoint.md), [components.md](./components.md) | `public/js/pp-reactive-v2.js`, component `.html`, `.venv/Lib/site-packages/casp/components_compiler.py` | `Context.Provider` usage, logical ancestry, single-root template shape |
+| Add 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 |
 | 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 |
 
@@ -75,7 +75,7 @@ Treat the table as a prompt pack for spot checks, not as a full validation matri
 - AI edits framework internals when the task only requires app-owned route or helper changes.
 - AI treats runtime HTML examples as authored template examples.
 - AI generates a route or component template with a valid-looking root element but leaves a sibling top-level `<script>` or second top-level element after it.
-- AI starts first-party interactivity with ids, `data-*` attributes, `querySelector`, `addEventListener`, manual `fetch`, or manual `innerHTML` instead of PulsePoint `on*` attributes, state, directives, and `pp.rpc()`.
+- AI starts first-party interactivity with ids, `data-*` attributes, `querySelector`, `addEventListener`, manual `fetch`, manual `innerHTML`, or per-input `pp-ref` payload collection instead of PulsePoint `on*` attributes, form submit events, state, directives, and `pp.rpc()`.
 - AI puts `pp-reset-scroll="true"` on the whole shell or `body` when only the page-content pane should reset, causing persistent sidebars or rails to lose their scroll position.
 - AI decides behavior from memory without checking the owning implementation details.
 

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 in `src/lib/auth/auth_config.py`
-- framework runtime behavior in `.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 auth configuration
+- `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 `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 config belongs in `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 code.
+- 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`.
+Keep application auth policy in `src/lib/auth/auth_config.py`. This file is the controller for route privacy, redirects, and RBAC.
 
 Example:
 
@@ -80,10 +80,12 @@ from casp.auth import AuthSettings
 
 def build_auth_settings() -> AuthSettings:
     """
-    Centralized auth configuration.
-
-    Keep secrets (AUTH_SECRET, AUTH_COOKIE_NAME) in .env.
-    Keep app-level session settings in .env (SESSION_LIFETIME_HOURS, etc).
+    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(
@@ -101,7 +103,7 @@ def build_auth_settings() -> AuthSettings:
         is_role_based=False,
         role_identifier="role",
 
-        # IMPORTANT: current casp.auth expects PATH -> [ROLES]
+        # RBAC policy is app-owned here; the runtime expects ROUTE/PATTERN -> [ROLES].
         role_based_routes={},
 
         # Redirects / prefixes
@@ -150,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()`.
-- You do not need to 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:
@@ -765,18 +767,7 @@ Behavior:
 
 Use this helper when custom form or fetch flows need access to the session CSRF token.
 
-## Backwards Compatibility Alias
-
-The installed auth file still includes `AuthConfig` as a compatibility alias.
-
-It exposes:
-
-- property proxies for `PUBLIC_ROUTES`, `PRIVATE_ROUTES`, `AUTH_ROUTES`, `IS_ALL_ROUTES_PRIVATE`, `DEFAULT_SIGNIN_REDIRECT`, and `DEFAULT_SIGNOUT_REDIRECT`
-- `AuthConfig.check_auth_role(...)` as a proxy to `auth.check_role(...)`
-
-Prefer `AuthSettings`, `configure_auth(...)`, and `auth.settings` in new code.
-
-## 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.

package/dist/docs/components.md

@@ -39,8 +39,6 @@ When the task is about component internals rather than normal app-owned componen
 - `.venv/Lib/site-packages/casp/component_decorator.py` owns `@component`, `Component`, `render_html(...)`, and component loading.
 - `.venv/Lib/site-packages/casp/components_compiler.py` owns `@import` parsing, `x-*` tag resolution, root validation, and `pp-component` injection.
 - `.venv/Lib/site-packages/casp/html_attrs.py` owns `get_attributes(...)` and the Python-side `merge_classes(...)` contract.
-- `.venv/Lib/site-packages/casp/syntax_compiler.py` owns Caspian template syntax transpilation before Jinja render.
-
 Use [core-runtime-map.md](./core-runtime-map.md) when you need the broader Python runtime-module map. Use [pulsepoint-runtime-map.md](./pulsepoint-runtime-map.md) when a component task is specifically about browser-side PulsePoint state, refs, context, portals, events, RPC, or SPA behavior.
 
 ## Basic Component
@@ -203,7 +201,7 @@ def Counter(label: str = "Clicks") -> str:
 
 ```html
 <div>
-  <h3>[[ label ]]</h3>
+  <h3>{{ label }}</h3>
   <button onclick="setCount(count + 1)">
     {count}
   </button>

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

@@ -88,7 +88,7 @@ Interactive CRUD page:
 
 | Runtime file | Primary responsibility | Read these docs |
 | --- | --- | --- |
-| [.venv/Lib/site-packages/casp/layout.py](../../../../.venv/Lib/site-packages/casp/layout.py) | `render_page(...)`, `render_layout(...)`, nested layout discovery, metadata merge, and the synchronous `layout()` contract | [routing.md](./routing.md), [metadata.md](./metadata.md) |
+| [.venv/Lib/site-packages/casp/layout.py](../../../../.venv/Lib/site-packages/casp/layout.py) | `render_page(...)`, `render_layout(...)`, nested layout discovery, metadata merge, sync or async `layout()` results, and parser-based `<slot />` replacement | [routing.md](./routing.md), [metadata.md](./metadata.md) |
 | [.venv/Lib/site-packages/casp/auth.py](../../../../.venv/Lib/site-packages/casp/auth.py) | `AuthSettings`, route privacy checks, session payloads, OAuth providers, CSRF helper behavior, and redirect logic | [auth.md](./auth.md) |
 | [.venv/Lib/site-packages/casp/runtime_security.py](../../../../.venv/Lib/site-packages/casp/runtime_security.py) | safe public-file serving, baseline non-CSP response headers, production-safe error messages, and production session-secret enforcement used by `main.py` | [project-structure.md](./project-structure.md), [auth.md](./auth.md) |
 | [.venv/Lib/site-packages/casp/rpc.py](../../../../.venv/Lib/site-packages/casp/rpc.py) | `@rpc()` registration, rate limits, request handling, auth-aware action checks, and streamed RPC responses | [fetch-data.md](./fetch-data.md) |
@@ -101,9 +101,8 @@ Interactive CRUD page:
 | [.venv/Lib/site-packages/casp/scripts_type.py](../../../../.venv/Lib/site-packages/casp/scripts_type.py) | rewriting authored body `<script>` tags to `type="text/pp"` in rendered HTML | [pulsepoint.md](./pulsepoint.md), [routing.md](./routing.md), [components.md](./components.md) |
 | [.venv/Lib/site-packages/casp/html_attrs.py](../../../../.venv/Lib/site-packages/casp/html_attrs.py) | `get_attributes(...)`, alias normalization, and the Python-side `merge_classes(...)` contract | [components.md](./components.md) |
 | [.venv/Lib/site-packages/casp/caspian_config.py](../../../../.venv/Lib/site-packages/casp/caspian_config.py) | typed config loading, feature-flag reads, `settings/files-list.json` parsing, and route rule derivation | [project-structure.md](./project-structure.md), [commands.md](./commands.md), [routing.md](./routing.md) |
-| [.venv/Lib/site-packages/casp/syntax_compiler.py](../../../../.venv/Lib/site-packages/casp/syntax_compiler.py) | transpiling Caspian `<[[ ... ]]>` and `<template casp-*>` syntax before template render | [components.md](./components.md), [routing.md](./routing.md) |
 
-Secondary helpers such as `html_native.py`, `loading.py`, and `string_helpers.py` support the modules above. Read them only when a higher-level runtime file is still insufficient to explain the behavior you are tracing.
+Secondary helpers such as `html_native.py`, `loading.py`, and `string_helpers.py` support the modules above. `html_native.py` owns BeautifulSoup-backed fragment parsing used by component/root transforms and layout slot replacement. Read these helpers only when a higher-level runtime file is still insufficient to explain the behavior you are tracing.
 
 ## Verification Focus
 
@@ -116,7 +115,7 @@ Use these behavior checkpoints when AI needs the fastest verification path for a
 | `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 |
-| `casp.components_compiler`, `casp.component_decorator`, `casp.scripts_type`, and template-root injection | `@import` parsing, `x-*` expansion, syntax transpilation, deterministic root keys, `pp-component` injection, and authored-script rewriting to `type="text/pp"` |
+| `casp.components_compiler`, `casp.component_decorator`, `casp.scripts_type`, and template-root injection | `@import` parsing, `x-*` expansion, deterministic root keys, `pp-component` injection, and authored-script rewriting to `type="text/pp"` |
 | `casp.state_manager` | wire vs non-wire reset behavior, request-state persistence assumptions, and AttributeDict access |
 | `casp.cache_handler` | filename generation, manifest writes, TTL handling, and invalidation behavior |
 | `casp.caspian_config` | config parsing, files index building, and Next.js-style route inventory behavior |

package/dist/docs/database.md

@@ -178,7 +178,7 @@ Prisma calls fit naturally in:
 - `async def page()` for first-render data
 - `@rpc()` actions for browser-triggered reads and writes
 
-Keep Prisma I/O out of `layout.py` in the current runtime because `casp.layout` calls `layout()` synchronously.
+Keep route-specific Prisma I/O in `page()` or `@rpc()` actions. The installed layout engine supports synchronous and async `layout()` results, but layout work should stay focused on shared subtree props or metadata.
 
 See `fetch-data.md` for the recommended route-render versus RPC split.
 
@@ -352,5 +352,5 @@ If an AI agent is working on a Caspian app with Prisma enabled, apply these rule
 - Reuse the existing `src/lib/prisma/` package when the Python app needs database access.
 - For file managers and uploads, persist metadata in Prisma and keep blob storage separate. See [file-uploads.md](./file-uploads.md).
 - Put reusable database helpers in `src/lib/`; keep route and RPC orchestration in `src/app/`.
-- Use `async def page()` for first-render reads. Keep `layout()` synchronous in the current runtime, and use `@rpc()` plus `pp.rpc()` for browser-triggered reads and writes.
+- Use `async def page()` for route-specific first-render reads. Use `layout()` only for shared subtree props or metadata, and use `@rpc()` plus `pp.rpc()` for browser-triggered reads and writes.
 - Check `fetch-data.md` for route versus RPC guidance and `validation.md` before writing public mutations.

package/dist/docs/fetch-data.md

@@ -23,7 +23,7 @@ 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.
 
-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. Do not set up first-party data actions by assigning ids and then wiring `querySelector(...)`, `addEventListener(...)`, manual `fetch(...)`, or manual DOM repainting.
+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.
 
@@ -31,7 +31,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 synchronous 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:
@@ -46,10 +46,11 @@ When a page belongs to a grouped subtree such as a dashboard, account area, admi
 
 ## Default Data Rule
 
-- Use `page()` for async or route-level data required before HTML renders, and use `layout()` only for synchronous shared 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.
 - 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`
@@ -81,7 +82,7 @@ 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 synchronous payload. The current layout engine does not await `layout()`.
+- 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/`.
 
@@ -107,14 +108,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):
-    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>
@@ -127,10 +132,37 @@ Call it from the client with `pp.rpc()`:
     const todo = await pp.rpc("create_todo", { title });
     console.log(todo);
   }
-</script>
-```
-
-Use RPC for:
+</script>
+```
+
+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
@@ -294,7 +326,7 @@ For initial route rendering with `render_page(...)`, prefer passing plain templa
 
 ## Recommended Decision Rule
 
-Use `page()` when async or route-specific data is part of the page render. Use `layout()` for synchronous shared 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:
 
@@ -326,8 +358,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 synchronous data.
-- Keep async I/O in `page()` or `@rpc()` because the current layout engine does not await `layout()`.
+- 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.

package/dist/docs/file-conventions.md

@@ -33,7 +33,7 @@ Treat `caspian.config.json` and the actual project tree as the source of truth f
 | `index.html` | Authored visible page template for a route | The route renders UI | `src/app/**`, `routing.md`, `pulsepoint.md` |
 | `index.py` | Backend companion for route logic and metadata | The route needs `page()`, metadata, auth checks, redirects, caching, or route-owned `@rpc()` actions | `main.py`, `.venv/Lib/site-packages/casp/layout.py` |
 | `layout.html` | Shared shell for a route subtree | Multiple child routes share wrapper markup | `.venv/Lib/site-packages/casp/layout.py`, `routing.md` |
-| `layout.py` | Shared synchronous props and metadata defaults for a subtree | The shared shell needs Python-provided values or metadata | `.venv/Lib/site-packages/casp/layout.py`, `metadata.md` |
+| `layout.py` | Shared props and metadata defaults for a subtree | The shared shell needs Python-provided values or metadata | `.venv/Lib/site-packages/casp/layout.py`, `metadata.md` |
 | `loading.html` | Route-scope loading UI used during SPA navigation | A section or page needs an immediate loading state before the next route finishes rendering | `.venv/Lib/site-packages/casp/loading.py`, `public/js/pp-reactive-v2.js` |
 | `not-found.html` | Global 404 page | The app needs a branded fallback for unmatched URLs | `main.py` |
 | `error.html` | Global 500 page | The app needs a safe fallback for unhandled exceptions | `main.py` |
@@ -129,9 +129,9 @@ When one page needs to influence a wrapping layout, `page()` can return `(page_h
 Use it for:
 
 - shared shell markup such as sidebars, headers, docs rails, or dashboard frames
-- the `[[children|safe]]` insertion point for child routes
-- shared layout props consumed as `[[ layout.* ]]`
-- shared metadata fields consumed as `[[ metadata.* ]]`
+- the `<slot />` insertion point for child routes
+- shared layout props consumed as `{{ layout.* }}`
+- shared metadata fields consumed as `{{ metadata.* }}`
 
 Example:
 
@@ -140,12 +140,14 @@ Example:
   <aside class="docs-nav">Docs navigation</aside>
 
   <main class="docs-content" pp-reset-scroll="true">
-    [[children|safe]]
+    <slot />
   </main>
 </div>
 ```
 
-Use nested `layout.html` files for sections like `dashboard/`, `docs/`, `account/`, or route groups such as `(marketing)/`.
+Use nested `layout.html` files for sections like `dashboard/`, `docs/`, `account/`, or route groups such as `(marketing)/`.
+
+The child outlet must be a real authored `<slot />` element in `layout.html`. The runtime parses layout HTML and replaces real slot elements during nested rendering; it does not invent an implicit slot from `layout.py` or replace escaped documentation text such as `&lt;slot /&gt;`.
 
 In grouped shells with separate shell and content scrolling, put `pp-reset-scroll="true"` on the content pane that should reset on child-route navigation. Leave persistent shell scrollers such as sidebars unmarked when they should keep their own scroll position.
 
@@ -155,7 +157,7 @@ In grouped shells with separate shell and content scrolling, put `pp-reset-scrol
 
 Use it for:
 
-- shared synchronous props
+- shared props
 - metadata defaults for everything below that folder
 - small shared layout decisions that belong to the subtree rather than one page
 
@@ -179,7 +181,7 @@ def layout():
     }
 ```
 
-Important runtime detail: `layout()` is synchronous in the installed runtime. Put async I/O in route `page()` functions or route-owned `@rpc()` actions instead of awaiting inside `layout.py`.
+Important runtime detail: `layout()` may be synchronous or async in the installed runtime. Keep async layout work focused on shared subtree props or metadata; put route-specific first-render data in `page()` and browser-triggered work in route-owned `@rpc()` actions.
 
 ## `loading.html`
 
@@ -199,7 +201,7 @@ Example layout shell:
 
 ```html
 <main class="docs-content" pp-loading-content="true" pp-reset-scroll="true">
-  [[children|safe]]
+  <slot />
 </main>
 ```
 

package/dist/docs/metadata.md

@@ -12,7 +12,7 @@ related:
 
 This page explains how Caspian handles document metadata, SEO fields, and social sharing tags.
 
-At render time, Caspian resolves metadata through the layout engine and exposes the merged result to templates as `[[ metadata.* ]]`.
+At render time, Caspian resolves metadata through the layout engine and exposes the merged result to templates as `{{ metadata.* }}`.
 
 ## Source Of Truth
 
@@ -20,7 +20,7 @@ At render time, Caspian resolves metadata through the layout engine and exposes
 - Route registration and runtime metadata collection are controlled by `main.py`.
 - Shared metadata defaults belong in `src/app/**/layout.py`.
 - Page-specific static or dynamic metadata belongs in `src/app/**/index.py`.
-- Rendered metadata is consumed from layout templates through `[[ metadata.* ]]`.
+- Rendered metadata is consumed from layout templates through `{{ metadata.* }}`.
 
 ## Overview
 
@@ -168,10 +168,10 @@ Resolved metadata is passed into layout rendering as a `metadata` object.
 Example:
 
 ```html
-<title>[[ metadata.title ]]</title>
-<meta name="description" content="[[ metadata.description ]]" />
-<meta property="og:image" content="[[ metadata['og:image'] ]]" />
-<meta name="twitter:card" content="[[ metadata['twitter:card'] ]]" />
+<title>{{ metadata.title }}</title>
+<meta name="description" content="{{ metadata.description }}" />
+<meta property="og:image" content="{{ metadata['og:image'] }}" />
+<meta name="twitter:card" content="{{ metadata['twitter:card'] }}" />
 ```
 
 Use bracket access for `extra` keys that contain characters such as `:`.
@@ -196,9 +196,9 @@ Use stable, publicly reachable image paths for social cards so crawlers can fetc
 
 Keep visual layout data and SEO metadata separate.
 
-- Values returned from `layout()` are exposed as `[[ layout.* ]]`.
-- The second dict returned from `page()` as `(page_html, layout_props_dict)` is also exposed to wrapping layouts as `[[ layout.* ]]`.
-- SEO values are exposed as `[[ metadata.* ]]`.
+- Values returned from `layout()` are exposed as `{{ layout.* }}`.
+- The second dict returned from `page()` as `(page_html, layout_props_dict)` is also exposed to wrapping layouts as `{{ layout.* }}`.
+- SEO values are exposed as `{{ metadata.* }}`.
 - Do not return `title` or `description` from `layout()` expecting SEO changes.
 - The layout engine explicitly strips `title` and `description` from layout props to avoid mixing visual props with metadata.
 
@@ -223,5 +223,5 @@ If an AI agent is deciding where to put SEO fields, apply these rules first.
 - If a single route only needs to tweak a wrapping layout, return `(render_page(__file__, ...), {"dashboard_body_class": ...})` from `page()` instead of moving that prop into metadata.
 - Use `extra` for Open Graph and Twitter card tags.
 - Access `extra` values in templates with bracket syntax such as `metadata['og:image']`.
-- Keep `layout()` return data in `[[ layout.* ]]` and keep SEO fields in `Metadata(...)`.
+- Keep `layout()` return data in `{{ layout.* }}` and keep SEO fields in `Metadata(...)`.
 - Check [routing.md](./routing.md) when deciding whether metadata belongs in a layout or a specific route folder.

package/dist/docs/project-structure.md

@@ -106,7 +106,7 @@ This is the main application area. It contains route files, templates, styles, a
 
 This directory handles file-based routing. Route templates and route-specific backend logic live here.
 
-For any route that renders UI, keep that markup in `src/app/**/index.html`. If the route is UI-only, `index.html` alone is enough. Add `src/app/**/index.py` only as a companion when the same route needs metadata, `page()`, `@rpc()` actions, auth checks, caching, redirects, or other server-side behavior. Keep shared wrappers in `layout.html` and use `layout.py` only for shared synchronous props or metadata. Use a lone `index.py` only for non-visual routes such as redirect-only or action-only handlers.
+For any route that renders UI, keep that markup in `src/app/**/index.html`. If the route is UI-only, `index.html` alone is enough. Add `src/app/**/index.py` only as a companion when the same route needs metadata, `page()`, `@rpc()` actions, auth checks, caching, redirects, or other server-side behavior. Keep shared wrappers in `layout.html` and use `layout.py` only for shared props or metadata. Use a lone `index.py` only for non-visual routes such as redirect-only or action-only handlers.
 
 When a folder represents a section with child routes, such as `dashboard`, `account`, `settings`, or `docs`, create `layout.html` in that folder and let the child routes live beneath it. See [routing.md](./routing.md) for the canonical section layout pattern.
 
@@ -261,7 +261,7 @@ Keep visible wrapper markup in `layout.html`, not in `layout.py`.
 
 ### `src/app/layout.py`
 
-The backend companion for a layout. Use this file for shared synchronous props, metadata defaults, and other server-side preparation for the sibling `layout.html`.
+The backend companion for a layout. Use this file for shared props, metadata defaults, and other server-side preparation for the sibling `layout.html`.
 
 Do not store layout HTML in `layout.py`. Keep the authored wrapper in `layout.html` and let `layout.py` return props or metadata.
 

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

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

package/dist/docs/pulsepoint.md

@@ -55,6 +55,7 @@ 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.
@@ -69,9 +70,10 @@ 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 element reference is needed.
+- 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.
 
@@ -80,6 +82,7 @@ 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 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.
 
@@ -134,6 +137,75 @@ Avoid this first-party pattern:
 ```
 
 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.
 
 ## Authoring Model
 
@@ -296,12 +368,12 @@ Notes:
 
 ## Context
 
-Context is implemented in the current runtime, but the current API follows a React-style `Context.Provider` pattern rather than a legacy `pp.provideContext(...)` helper.
+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 `Context.Provider`.
+- 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.
@@ -315,23 +387,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 provider tag in the template. The runtime also supports imperative `ThemeContext.Provider({ value })` calls during render, but the tag form is clearer for AI-generated authored templates.
-- 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:
 
@@ -401,9 +474,10 @@ Example:
 </div>
 ```
 
-## Refs
-
-- 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.
@@ -469,6 +543,8 @@ Example:
 - 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.
@@ -528,6 +604,7 @@ 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.
 - 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.
@@ -540,7 +617,7 @@ Use these rules when generating or editing PulsePoint runtime code:
 - 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 React-style context pattern: `pp.createContext(...)`, `<Context.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.
@@ -581,7 +658,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 `Context.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/routing.md

@@ -35,8 +35,8 @@ Start with these rules:
 - In grouped shells with separate shell and content scrolling, put `pp-reset-scroll="true"` on the content pane in `layout.html` when that pane should reset on child-route navigation while the shell sidebar or rail keeps its own scroll.
 - Use `layout.py` when a layout needs shared props or metadata before rendering. The `layout()` function may be synchronous or async.
 - Keep visible route and layout markup in `index.html` and `layout.html`. Treat `index.py` and `layout.py` as backend companions, not as places to author visible HTML.
-- Treat every authored route and layout template like a React component body: it must have exactly one top-level parent HTML element or one imported `x-*` root, and any owned plain `<script>` must live inside that same root.
-- For route and layout interactivity, use PulsePoint in the authored HTML first: native `on*` event attributes, `pp.state(...)`, refs, effects, directives, and `pp.rpc()`. Do not create standard JavaScript event systems with ids, `data-*` state, `querySelector`, `addEventListener`, or manual `innerHTML` for normal first-party UI.
+- Treat every authored route and layout template like a React component body: it must have exactly one top-level parent HTML element or one imported `x-*` root, and any owned plain `<script>` must live inside that same root.
+- For route and layout interactivity, use PulsePoint in the authored HTML first: native `on*` event attributes, `pp.state(...)`, refs, effects, directives, and `pp.rpc()`. Do not create standard JavaScript event systems with ids, `data-*` state, `querySelector`, `addEventListener`, or manual `innerHTML` for normal first-party UI.
 
 ## Hard Template Invariant
 
@@ -182,11 +182,11 @@ Route templates can import reusable Python components with `<!-- @import ... -->
 
 Place those import comments at the top of the file, above the authored root element. They are file-level directives, not children of the route root.
 
-Route templates follow the same authored-vs-runtime contract documented in [pulsepoint.md](./pulsepoint.md) and the same single-root discipline documented in [components.md](./components.md): keep one authored parent node, keep any `<!-- @import ... -->` directives above that root, use a plain `<script>` inside that root when needed, and do not handwrite `pp-component` or `type="text/pp"`. That root may be a native HTML element or a single imported `x-*` component tag, but after expansion it must resolve to one final HTML root.
-
-When a route needs button clicks, form submits, input changes, filters, tabs, menus, uploads, polling, or reactive list updates, author those interactions as PulsePoint behavior in `index.html`. Use `onclick`, `oninput`, `onchange`, `onsubmit`, `pp.state(...)`, `pp-for`, refs, effects, and `pp.rpc(...)` instead of starting with `id` attributes plus `document.querySelector(...)` or `addEventListener(...)`.
-
-For AI-generated route templates, treat `src/app/**/index.html` the same way you would a React component body: return one parent node that contains the entire route markup. This includes any owned script.
+Route templates follow the same authored-vs-runtime contract documented in [pulsepoint.md](./pulsepoint.md) and the same single-root discipline documented in [components.md](./components.md): keep one authored parent node, keep any `<!-- @import ... -->` directives above that root, use a plain `<script>` inside that root when needed, and do not handwrite `pp-component` or `type="text/pp"`. That root may be a native HTML element or a single imported `x-*` component tag, but after expansion it must resolve to one final HTML root.
+
+When a route needs button clicks, form submits, input changes, filters, tabs, menus, uploads, polling, or reactive list updates, author those interactions as PulsePoint behavior in `index.html`. Use `onclick`, `oninput`, `onchange`, `onsubmit`, `pp.state(...)`, `pp-for`, refs, effects, and `pp.rpc(...)` instead of starting with `id` attributes plus `document.querySelector(...)` or `addEventListener(...)`. For simple form submits, prefer `onsubmit="{submitForm(event)}"` and `Object.fromEntries(new FormData(event.currentTarget).entries())` over per-input `pp-ref` payload collection.
+
+For AI-generated route templates, treat `src/app/**/index.html` the same way you would a React component body: return one parent node that contains the entire route markup. This includes any owned script.
 
 Good:
 
@@ -260,16 +260,16 @@ Use this pattern when the route needs to fetch data, compute metadata, or do oth
 `page()` may also return a 2-item tuple: `(page_html, layout_props_dict)`.
 
 - The first item is the rendered page HTML, usually `render_page(__file__, page_context)`.
-- The second item must be a dict. Its keys are merged into the wrapping layout context and become available to parent layouts as `[[ layout.* ]]`.
+- The second item must be a dict. Its keys are merged into the wrapping layout context and become available to parent layouts as `{{ layout.* }}`.
 
 Use that tuple form when one route needs to influence a wrapper without turning that value into a section-wide default. A common example is a dashboard page that needs to lock the root body with `overflow-hidden` while the rest of the app keeps normal scrolling.
 
 Example root layout:
 
 ```html
-<body class="[[ layout.dashboard_body_class | default('') ]]">
-  [[ children | safe ]]
-</body>
+<body class="{{ layout.dashboard_body_class | default('') }}">
+  <slot />
+</body>
 ```
 
 Example route:
@@ -284,7 +284,7 @@ async def page():
   )
 ```
 
-The key name is arbitrary, but it must match exactly between the dict returned from `page()` and the `[[ layout.some_key ]]` lookup in `layout.html`.
+The key name is arbitrary, but it must match exactly between the dict returned from `page()` and the `{{ layout.some_key }}` lookup in `layout.html`.
 
 Use distinct names for those layout props. In the current router, the second dict is merged into the full layout context after path params and `request`, so a key such as `slug` or `request` can shadow an existing value.
 
@@ -366,15 +366,17 @@ In practice, this means a dashboard is usually a folder-level layout, not a sing
 
 When a layout imports components, keep each `<!-- @import ... -->` comment above the layout's authored wrapper element, such as the root `<section>` in a nested layout or the root `<html>` in the app layout.
 
-Resolved SEO fields are exposed to layouts as `[[ metadata.* ]]`, while values returned from `layout.py` are exposed separately as `[[ layout.* ]]`.
+Resolved SEO fields are exposed to layouts as `{{ metadata.* }}`, while values returned from `layout.py` are exposed separately as `{{ layout.* }}`.
 
 ### `layout.html`
 
 Use `layout.html` for the shared wrapper markup of a subtree. Keep the visible shell here, not in `layout.py`.
 
-Follow the same authoring contract used by route templates: one authored parent node, top-of-file `<!-- @import ... -->` directives above that root, plain `<script>` inside the root when needed, and no handwritten `pp-component` or `type="text/pp"`. See [pulsepoint.md](./pulsepoint.md) for the canonical authored-vs-runtime explanation.
-
-For example, a page inside `/dashboard/settings` is wrapped by the root layout first and then by the dashboard layout.
+Follow the same authoring contract used by route templates: one authored parent node, top-of-file `<!-- @import ... -->` directives above that root, plain `<script>` inside the root when needed, and no handwritten `pp-component` or `type="text/pp"`. See [pulsepoint.md](./pulsepoint.md) for the canonical authored-vs-runtime explanation.
+
+Place child routes with a plain HTML `<slot />` tag. Caspian replaces that layout slot with the current child route or nested layout while rendering.
+
+For example, a page inside `/dashboard/settings` is wrapped by the root layout first and then by the dashboard layout.
 
 Example root layout:
 
@@ -382,19 +384,19 @@ Example root layout:
 <!DOCTYPE html>
 <html>
   <head>
-    <title>[[ metadata.title ]]</title>
-    <meta name="description" content="[[ metadata.description ]]" />
+    <title>{{ metadata.title }}</title>
+    <meta name="description" content="{{ metadata.description }}" />
   </head>
-  <body>
-    <NavBar />
-    [[ children | safe ]]
-  </body>
-</html>
+  <body>
+    <NavBar />
+    <slot />
+  </body>
+</html>
 ```
 
 ### `layout.py`
 
-If a layout needs shared synchronous props or metadata, add a `layout.py` file next to the HTML layout. Treat it as the backend companion for the layout, not as the place to author visible wrapper markup.
+If a layout needs shared props or metadata, add a `layout.py` file next to the HTML layout. Treat it as the backend companion for the layout, not as the place to author visible wrapper markup.
 
 When `layout()` calls `render_layout(__file__, ...)`, root-validation errors are attributed to the sibling `layout.html` because that file is the authored template. If `layout()` returns a raw HTML string directly, Caspian treats that value as a runtime fragment instead of an authored template and wraps it in a runtime host root when needed.
 
@@ -415,16 +417,16 @@ def layout(context_data):
 
 `context_data` includes URL parameters such as dynamic route values.
 
-In the common case, return a dict and let the sibling `layout.html` read those values through `[[ layout.* ]]`.
+In the common case, return a dict and let the sibling `layout.html` read those values through `{{ layout.* }}`.
 
 `layout()` currently supports these result shapes:
 
-- `dict`: load the sibling `layout.html` and expose the dict as `[[ layout.* ]]`
+- `dict`: load the sibling `layout.html` and expose the dict as `{{ layout.* }}`
 - `str`: use that string as the layout content
-- `(layout_html, props_dict)`: use the first item as the layout content and expose the second dict as `[[ layout.* ]]`
+- `(layout_html, props_dict)`: use the first item as the layout content and expose the second dict as `{{ layout.* }}`
 - `None`: fall back to the sibling `layout.html` with no extra layout props
 
-If you intentionally want to render `layout.html` immediately with direct local variables instead of the `layout.*` namespace, call `render_layout(__file__, {...})` and reference those keys directly in the template.
+If you intentionally want to render `layout.html` immediately with direct local variables instead of the `layout.*` namespace, call `render_layout(__file__, {...})` and reference those keys directly in the template. `render_layout(...)` does not create a hidden child outlet; the layout template must still author the real `<slot />` element where child routes should render.
 
 Example:
 
@@ -435,9 +437,9 @@ def layout():
   return render_layout(__file__, {"my_class": "size-8"})
 ```
 
-In that pattern, the matching `layout.html` reads `[[ my_class ]]`, not `[[ layout.my_class ]]`, because the template string was already rendered before the nested layout pipeline continues.
+In that pattern, the matching `layout.html` reads `{{ my_class }}`, not `{{ layout.my_class }}`, because the template string was already rendered before the nested layout pipeline continues.
 
-If you need both a custom layout string and standard `[[ layout.* ]]` props, return a tuple:
+If you need both a custom layout string and standard `{{ layout.* }}` props, return a tuple:
 
 ```python
 from casp.layout import render_layout
@@ -449,7 +451,7 @@ def layout():
   )
 ```
 
-`layout()` currently runs synchronously in `casp.layout`. If you need async I/O, load it in `page()` instead of `layout.py`.
+`layout()` may be synchronous or async in the installed runtime. Keep async layout work focused on shared subtree props or metadata; use `page()` or `@rpc()` when the work belongs to one route or a browser-triggered user action.
 
 Use [metadata.md](./metadata.md) when a layout also needs SEO defaults. Return dictionaries from `layout()` for visual or template props, and use `Metadata(...)` for title, description, and social tags.
 
@@ -504,15 +506,15 @@ If an AI agent is choosing where to add or update route code, apply these rules
 - Use folder names to model URL segments.
 - If a route renders UI, create or update `index.html` for the markup.
 - Add `index.py` only when the same route needs metadata or server behavior; do not place route HTML in `index.py`.
-- Keep visible page markup in `index.html` and shared subtree shells in `layout.html`; do not place route HTML in `index.py` or layout HTML in `layout.py`.
-- Use PulsePoint as the first-party interaction model for route and layout HTML. Avoid custom DOM wiring for normal events and reactivity.
-- When the user asks for a dashboard, admin area, account section, or any grouped subtree of child routes, create a parent folder with `layout.html` and place the child routes beneath it. Follow the same mental model as the Next.js App Router.
+- Keep visible page markup in `index.html` and shared subtree shells in `layout.html`; do not place route HTML in `index.py` or layout HTML in `layout.py`.
+- Use PulsePoint as the first-party interaction model for route and layout HTML. Avoid custom DOM wiring for normal events and reactivity.
+- When the user asks for a dashboard, admin area, account section, or any grouped subtree of child routes, create a parent folder with `layout.html` and place the child routes beneath it. Follow the same mental model as the Next.js App Router.
 - Use a normal folder such as `dashboard/` when the segment should appear in the URL. Use `(group)/` only when the folder should organize or wrap child routes without adding a path segment.
 - Use [cache.md](./cache.md) when an `index.py` route should opt into page-level HTML caching.
-- Use `layout.html` for shared wrappers and `layout.py` for layout-level synchronous props or metadata.
+- Use `layout.html` for shared wrappers and `layout.py` for layout-level props or metadata.
 - For grouped shells with separate shell and content scrolling, put `pp-reset-scroll="true"` on the content pane instead of the whole shell when only the page content should reset between child routes.
-- When one route needs to change a parent layout, return `(render_page(__file__, ...), {"dashboard_body_class": ...})` from `page()` and read that value as `[[ layout.dashboard_body_class ]]` in the wrapping `layout.html`.
-- Use `layout.py` for layout props that should apply across an entire subtree. Use `render_layout(__file__, {...})` only when the layout should consume direct local variables such as `[[ my_class ]]` instead of the standard `[[ layout.* ]]` namespace.
+- When one route needs to change a parent layout, return `(render_page(__file__, ...), {"dashboard_body_class": ...})` from `page()` and read that value as `{{ layout.dashboard_body_class }}` in the wrapping `layout.html`.
+- Use `layout.py` for layout props that should apply across an entire subtree. Use `render_layout(__file__, {...})` only when the layout should consume direct local variables such as `{{ my_class }}` instead of the standard `{{ layout.* }}` namespace.
 - Keep `<!-- @import ... -->` directives at the top of `index.html` and `layout.html`, above the single authored parent node.
 - Use [metadata.md](./metadata.md) when a route or layout needs SEO fields.
 - Use `[segment]` for single dynamic parameters.

package/package.json

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