caspian-utils 0.0.34 → 0.1.0

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

@@ -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,7 +46,7 @@ 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.
@@ -81,7 +81,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/`.
 
@@ -294,7 +294,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 +326,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,132 @@
----
-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.
-- 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
-
-Context provider:
-
-```html
-<section>
-  <script>
-    const ThemeContext = pp.createContext("light");
-    const [theme, setTheme] = pp.state("dark");
-  </script>
-
-  <ThemeContext.Provider value="{theme}">
-    <button onclick="setTheme(theme === 'dark' ? 'light' : 'dark')">
-      Theme: {theme}
-    </button>
-  </ThemeContext.Provider>
-</section>
-```
-
-Upload progress:
-
-```html
-<section>
-  <input type="file" onchange="{uploadFile(event.target.files?.[0])}" />
-  <p>{progress}%</p>
-
-  <script>
-    const [progress, setProgress] = pp.state(0);
-
-    async function uploadFile(file) {
-      if (!file) return;
-
-      await pp.rpc("upload_asset", { file }, {
-        onUploadProgress: (event) => setProgress(event.percentage ?? 0),
-      });
-    }
-  </script>
-</section>
-```
-
-Grouped shell scroll reset:
-
-```html
-<section class="dashboard-shell">
+---
+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.
+- 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
+
+Context provider:
+
+```html
+<section>
+  <script>
+    const ThemeContext = pp.createContext("light");
+    const [theme, setTheme] = pp.state("dark");
+  </script>
+
+  <ThemeContext.Provider value="{theme}">
+    <button onclick="setTheme(theme === 'dark' ? 'light' : 'dark')">
+      Theme: {theme}
+    </button>
+  </ThemeContext.Provider>
+</section>
+```
+
+Upload progress:
+
+```html
+<section>
+  <input type="file" onchange="{uploadFile(event.target.files?.[0])}" />
+  <p>{progress}%</p>
+
+  <script>
+    const [progress, setProgress] = pp.state(0);
+
+    async function uploadFile(file) {
+      if (!file) return;
+
+      await pp.rpc("upload_asset", { file }, {
+        onUploadProgress: (event) => setProgress(event.percentage ?? 0),
+      });
+    }
+  </script>
+</section>
+```
+
+Grouped shell scroll reset:
+
+```html
+<section class="dashboard-shell">
   <aside class="dashboard-sidebar">...</aside>
   <main class="dashboard-content" pp-reset-scroll="true">
-    [[ children | safe ]]
+    <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/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 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.0",
   "description": "Caspian tooling",
   "main": "index.js",
   "scripts": {