caspian-utils 0.0.3 → 0.0.5

package/dist/docs/components.md

@@ -94,7 +94,7 @@ def Counter(label: str = "Clicks") -> str:
     {count}
   </button>
 
-  <script type="text/pp">
+  <script>
     const [count, setCount] = pp.state(0);
   </script>
 </div>
@@ -108,16 +108,18 @@ Use this split when:
 
 This keeps the component easy to read: Python owns the server-side logic and template context, while the HTML file owns the rendered UI and browser behavior.
 
-## Auto-Injected `pp-component` And PulsePoint Scripts
+## Auto-Injected `pp-component` And PulsePoint Script Type
 
-Treat `pp-component="componentName"` as framework output, not authored source.
+Treat `pp-component="componentName"` and `type="text/pp"` as framework output, not authored source.
 
-- Do not manually add `pp-component` to route templates or component HTML files.
+- Do not manually add `pp-component="..."` to route templates, layout templates, or component HTML files.
+- Do not manually add `type="text/pp"` to authored PulsePoint scripts.
 - The Python render pipeline injects `pp-component` onto the single root element during render.
-- Add `<script type="text/pp">` only when the route or component actually needs PulsePoint logic.
+- `main.py` runs `transform_scripts(...)`, which rewrites authored body `<script>` tags to `<script type="text/pp">` before the browser runtime mounts.
+- Add a plain `<script>` only when the route or component actually needs PulsePoint logic.
 - When you do add a PulsePoint script, keep it inside that single root element.
 
-Examples in runtime docs often show rendered HTML that already contains `pp-component`. That is the final output shape, not the normal authoring pattern.
+Examples in runtime docs often show rendered HTML that already contains `pp-component` and `type="text/pp"`. That is the final output shape, not the normal authoring pattern.
 
 ### Authored Source vs Rendered Output
 
@@ -132,7 +134,7 @@ Author this:
     {count}
   </button>
 
-  <script type="text/pp">
+  <script>
     const [count, setCount] = pp.state(0);
   </script>
 </div>
@@ -161,15 +163,33 @@ The same rule applies to route templates such as `src/app/**/index.html`: one ro
 
 This is not just style guidance. The installed compiler injects `pp-component` onto the root element, and it raises an error when the template has no root, multiple sibling roots, stray top-level text, or a component tag as the root.
 
-Valid:
+For AI-generated templates, treat this as a hard authoring rule: write the HTML the same way a React component returns one parent element. If the template needs a PulsePoint script, keep that script inside the same parent root.
+
+Good:
 
 ```html
 <div class="card">
   <h2>Title</h2>
+
+  <script>
+    const [open, setOpen] = pp.state(false);
+  </script>
 </div>
 ```
 
-Invalid:
+Bad:
+
+```html
+<div class="card">
+  <h2>Title</h2>
+</div>
+
+<script>
+  const [open, setOpen] = pp.state(false);
+</script>
+```
+
+Also bad:
 
 ```html
 <h2>Title</h2>

package/dist/docs/index.md

@@ -13,6 +13,8 @@ related:
 
 This directory contains the local Caspian documentation set for quick reference and AI-aware routing.
 
+Before making feature, tooling, or file-placement decisions in a Caspian workspace, read `./caspian.config.json` almost immediately. That file is the project feature gate and tells you which capabilities are enabled, such as Prisma, MCP, TypeScript, Tailwind, backend-only mode, and component scan directories.
+
 ## Default Stack
 
 When generating or editing a Caspian app, treat these as the default choices unless the task explicitly requires something else:
@@ -37,14 +39,14 @@ The packaged Caspian docs distributed by the current toolchain also live here:
 - `commands.md` - Main Caspian CLI workflows for project creation, generation, updates, and config-aware maintenance
 - `database.md` - Prisma schema, migration, seed, and client-generation workflow for the current workspace, plus Python-side helper caveats
 - `auth.md` - Session-backed authentication with `casp.auth`, centralized `auth_config.py`, decorators, RBAC, and OAuth provider helpers
-- `components.md` - Create reusable Python components, template-backed UI, JSX-style imports, and single-root component templates
+- `components.md` - Create reusable Python components, template-backed UI, JSX-style imports, and the single-parent root rule for component HTML files
 - `pulsepoint.md` - Default reactive frontend runtime contract for component scripts, state, effects, directives, and client-side behaviors
 - `fetch-data.md` - Initial server-side data loading and browser-triggered RPC flows with `pp.rpc()`, streaming, uploads, and auth-aware actions
 - `state.md` - Request-scoped server state with `StateManager`, session-backed JSON persistence, and listener callbacks for transient flows
 - `cache.md` - Route-level HTML caching with `Cache`, `CacheHandler`, TTL behavior, file-system storage, and invalidation patterns
 - `validation.md` - Input validation and sanitization with `Validate`, `Rule`, direct field checks, and multi-rule workflows for routes and RPC actions
 - `metadata.md` - Static and dynamic metadata, SEO inheritance, and Open Graph or Twitter card tags
-- `routing.md` - Next.js App Router-style file-based routing with `src/app`, dynamic segments, route groups, and nested layouts
+- `routing.md` - Next.js App Router-style file-based routing with `src/app`, dynamic segments, route groups, nested layouts, and single-root route templates
 - `project-structure.md` - Default Caspian layout and where routes, templates, shared code, and database files belong
 
 ## AI Awareness Notes
@@ -54,10 +56,12 @@ If an AI tool needs Caspian project documentation, start with this directory and
 Preferred lookup order:
 
 1. Read `node_modules/caspian-utils/dist/docs/index.md` to discover available local docs.
-2. Read `database.md` for Prisma setup and ORM usage, `auth.md` for session auth and route protection, `components.md` for reusable UI authoring, `pulsepoint.md` for browser-side reactive runtime behavior, `fetch-data.md` for data flows, `state.md` for transient request-scoped state, `cache.md` for page caching, and `validation.md` for input boundaries.
-3. Prefer local docs before generating code, commands, or migration guidance.
-4. Check `node_modules/caspian-utils/dist/docs/` for packaged Caspian docs when local docs need more detail.
-5. Only fall back to upstream documentation when local and packaged markdown do not cover the topic.
+2. Read `./caspian.config.json` before making any feature assumption. Use it to confirm which project capabilities are enabled and which directories or tooling rules apply.
+3. Read `database.md` for Prisma setup and ORM usage, `auth.md` for session auth and route protection, `components.md` for reusable UI authoring, `pulsepoint.md` for browser-side reactive runtime behavior, `fetch-data.md` for data flows, `state.md` for transient request-scoped state, `cache.md` for page caching, and `validation.md` for input boundaries.
+4. For authored component, route, and layout HTML files, generate exactly one top-level lowercase HTML element. Think React-style single parent wrapper: keep any owned PulsePoint logic in a plain `<script>` inside that root, and do not handwrite `pp-component="..."` or `type="text/pp"` because Caspian injects those runtime attributes automatically.
+5. Prefer local docs before generating code, commands, or migration guidance.
+6. Check `node_modules/caspian-utils/dist/docs/` for packaged Caspian docs when local docs need more detail.
+7. Only fall back to upstream documentation when local and packaged markdown do not cover the topic.
 
 ## Maintenance
 

package/dist/docs/project-structure.md

@@ -24,6 +24,8 @@ In that layout, the default stack is Python components for reusable UI, PulsePoi
 
 For public pages that can safely reuse rendered HTML, Caspian also supports route-level page caching through `casp.cache_handler`.
 
+Before an AI agent decides which Caspian features are available in a workspace, it should read `./caspian.config.json` almost immediately. That file is the feature gate for project capabilities such as `backendOnly`, `tailwindcss`, `mcp`, `prisma`, `typescript`, and `componentScanDirs`.
+
 ## Top-Level Areas
 
 - `src/` contains routes, page templates, styles, and shared libraries.
@@ -84,6 +86,10 @@ 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.
 
+When authoring a route HTML file such as `src/app/**/index.html`, keep the whole template inside exactly one top-level lowercase HTML element. Treat it the same way you would a React component returning one parent element: wrap the route markup and any owned PulsePoint script in the same root.
+
+Do not handwrite `pp-component="..."` or `type="text/pp"` in those source templates. Author a plain `<script>` inside the root when you need PulsePoint logic, and let Caspian add the runtime attributes during render.
+
 See `routing.md` for the full App Router-style rules for dynamic segments, route groups, and nested layouts.
 
 ### `src/components/`
@@ -92,6 +98,10 @@ Use this folder for reusable UI components that should be imported into route te
 
 The common Caspian pattern is a Python file such as `Button.py` with `@component`, optionally paired with a same-name HTML file such as `Button.html` when the component has richer markup or PulsePoint behavior.
 
+For component HTML files, follow the same one-parent rule as route HTML files: one top-level lowercase HTML element only, with no sibling roots and no top-level script sitting outside that root.
+
+Do not handwrite `pp-component="..."` or `type="text/pp"` in component source templates either. Write plain `<script>` inside the single root and let the render pipeline inject the runtime shape.
+
 This workspace's component tooling scans `src/` based on `caspian.config.json`, so `src/components/` is a conventionally clean location, not a hard-coded runtime requirement.
 
 ### `src/lib/`
@@ -139,6 +149,10 @@ Use `main.py` for auth bootstrap and middleware-order changes. Use `src/lib/auth
 
 The core feature configuration file for the application.
 
+AI agents should read this file before making almost any feature-level decision. Use it to confirm which capabilities are enabled, which code generation paths make sense, and which directories should be scanned for components or other project assets.
+
+In the current workspace, `caspian.config.json` shows `backendOnly: false`, `tailwindcss: true`, `mcp: false`, `prisma: true`, `typescript: false`, and `componentScanDirs: ["src"]`.
+
 ### `src/lib/auth/auth_config.py`
 
 The project auth configuration file. Use this path when changing authentication behavior.
@@ -180,9 +194,11 @@ The packaged Caspian documentation location distributed with the current toolcha
 
 If an AI agent is deciding where to make changes, use these rules first.
 
+- Read `caspian.config.json` almost immediately before making feature, tooling, or file-placement decisions. It tells you which Caspian features are enabled in the current workspace.
 - Put route templates and route-specific backend logic in `src/app/`.
 - Check [routing.md](./routing.md) when you need URL segment rules, layout nesting behavior, or dynamic route conventions.
 - Put reusable component files in `src/components/` and check [components.md](./components.md) for `@component`, `render_html(__file__)`, import comments, and single-root template rules.
+- For route and component HTML files, always emit one top-level lowercase HTML element. Good: one wrapper containing the content and a plain `<script>` when needed. Bad: a wrapper element followed by a sibling top-level `<script>`, or handwritten `pp-component="..."` and `type="text/pp"` attributes in source.
 - Put shared helpers and reusable libraries in `src/lib/`.
 - Use PulsePoint conventions in route templates for reactive frontend behavior.
 - Use `@rpc()` in route/backend code and `pp.rpc()` in client code for browser-triggered data flows.

package/dist/docs/pulsepoint.md

@@ -1,6 +1,6 @@
 ---
 title: PulsePoint Runtime Guide
-description: Learn how AI agents should use PulsePoint as the default reactive frontend contract in Caspian, including the bundled runtime loaded from `public/js/main.js` and implemented in `public/js/pp-reactive-v2.js`, component script rules, and supported directives.
+description: Learn how AI agents should author PulsePoint against the shipped browser runtime in `public/js/pp-reactive-v2.js` and the Caspian render pipeline that injects runtime attributes automatically.
 related:
   title: Related docs
   description: Read the components, routing, data-fetching, and project-structure docs alongside the PulsePoint runtime contract.
@@ -14,16 +14,31 @@ related:
 
 ## Purpose
 
-This file documents the PulsePoint runtime that is currently shipped in `public/js/pp-reactive-v2.js` and loaded by `public/js/main.js`. Treat it as the working contract for AI-generated code.
+This file documents the current PulsePoint contract for this workspace. Treat it as the AI-facing source of truth when generating or reviewing interactive Caspian UI.
 
 If a task involves `pp.state`, `pp.effect`, `pp.layoutEffect`, `pp-ref`, `pp-spread`, `pp-for`, context, portals, SPA navigation, or component boundary behavior, read this page first and keep generated code aligned with the runtime implemented in this repo.
 
-Use `components.md` for authoring Python `@component` files and same-name HTML templates. Use this page for the browser-side `pp-component` contract and `script[type="text/pp"]` behavior after those templates are rendered.
+Use `components.md` for authoring Python `@component` files and same-name HTML templates. Use this page for the browser-side PulsePoint contract, the authoring rules that feed it, and the React-style mental model used by the current runtime.
 
-PulsePoint is the default reactive frontend layer for Caspian.
+PulsePoint is the default reactive frontend layer for Caspian. In this workspace it follows a React-like component pattern, but it is HTML-first rather than JSX-first.
 
 Do not assume React, Vue, Svelte, JSX, Alpine, HTMX, or older PulsePoint docs unless the task explicitly asks for a different frontend contract.
 
+## Source Of Truth
+
+For the current workspace, follow this order when documenting or generating PulsePoint code:
+
+- `public/js/pp-reactive-v2.js` is the shipped browser runtime contract AI should follow.
+- `main.py` is the render-pipeline source of truth for how Caspian injects runtime attributes and rewrites scripts before the browser sees the HTML.
+- If you are working inside PulsePoint or Caspian runtime development code and there is an authoring source tree behind the shipped files, use it only as an implementation detail. Do not assume that source tree exists in generated apps or shipped framework output.
+
+Important current facts:
+
+- `public/js/pp-reactive-v2.js` exposes the global `pp` runtime and auto-mounts on DOM ready.
+- `main.py` renders the final HTML, runs `transform_components(...)`, then runs `transform_scripts(...)` before returning the response.
+
+If docs, generated examples, or older notes disagree with `public/js/pp-reactive-v2.js` plus `main.py`, follow the code that actually runs.
+
 ## Default Frontend Rule
 
 When a Caspian page needs reactive browser behavior, use PulsePoint.
@@ -32,13 +47,46 @@ When a Caspian page needs reactive browser behavior, use PulsePoint.
 - Keep server-rendered HTML plus PulsePoint enhancement as the baseline architecture.
 - Only introduce another frontend runtime when the user explicitly asks for it or the project already depends on one.
 
-## Source layer vs raw runtime
+## Authoring Model
+
+PulsePoint authoring in this repo is split into two layers:
+
+- The authored layer: route, layout, and component templates under `src/` with plain HTML plus a plain `<script>`.
+- The runtime layer: the browser sees `pp-component` roots and `script[type="text/pp"]` after Caspian transforms the HTML.
+
+For authored Caspian templates:
+
+- Keep exactly one top-level lowercase HTML root element.
+- Put the component logic inside a plain `<script>` inside that same root.
+- Do not handwrite `pp-component="..."`.
+- Do not handwrite `type="text/pp"`.
+
+Caspian already handles those details for you during render.
+
+That means AI-generated examples should default to authored template source, not raw runtime HTML.
+
+Authored example:
+
+```html
+<section>
+  <h2>{title}</h2>
+  <p>Count: {count}</p>
+
+  <button onclick="setCount(count + 1)">Increment</button>
+  <button onclick="reset()">Reset</button>
+
+  <script>
+    const { title = "Counter" } = pp.props;
+    const [count, setCount] = pp.state(0);
+
+    function reset() {
+      setCount(0);
+    }
+  </script>
+</section>
+```
 
-- Source authoring under `src/` may use convenience syntax that is transformed before it reaches the browser.
-- This page describes the bundled browser runtime shipped in `public/js/pp-reactive-v2.js`.
-- When source-layer examples conflict with the bundled runtime, follow the bundled runtime.
-- In authored route and component templates, do not add `pp-component` manually. The Python side injects it onto the template root during render.
-- In a `pp-component` root, component logic must live in `<script>`, not plain `<script>`.
+When that template reaches the browser, Caspian will already have injected the component id and rewritten the owned script to `type="text/pp"`. Those runtime attributes are for the rendered output, not for authored source examples.
 
 ## Runtime shape
 
@@ -56,16 +104,16 @@ Important:
 
 ## Component roots and scripts
 
-- Each runtime component root should have at most one `<script>` block.
-- The runtime only treats `script` as component logic.
+- Each runtime component root should have at most one owned script.
+- At runtime, the owned script is `script[type="text/pp"]`.
 - The script lookup walks the current root and skips nested `pp-component` boundaries, so a parent does not consume a child component's script.
-- If multiple matching scripts exist in the same root, the first matching owned script wins. Generate one script per root.
-- Component HTML templates must have exactly one top-level lowercase HTML root because the compiler injects `pp-component` onto that root during render.
+- If multiple matching runtime scripts exist in the same root, the first matching owned script wins. Generate one script per root.
+- Authored route, layout, and component templates still need one top-level lowercase HTML root so Caspian can inject the component boundary correctly.
 - A scriptless component root still mounts and can receive props, refs, events, and nested children, but it has no local runtime scope beyond its props.
 - Component scripts are plain JavaScript executed with `new Function(...)`. Do not use `import`, `export`, or top-level `await` inside them.
 - The runtime auto-returns supported top-level bindings from the script. Do not rely on manual `return { ... }` objects.
 - `pp.props` contains the current prop bag for the component.
-- `pp.props.children` contains the root's initial inner HTML before the owning `script` block is removed from the render template.
+- `pp.props.children` contains the root's initial inner HTML before the owned script is removed from the render template.
 
 Bindings exported to the template:
 
@@ -83,7 +131,7 @@ Bindings that should not be assumed:
 Example:
 
 ```html
-<div pp-component="counter-card-1">
+<div>
   <h2>{title}</h2>
   <p>Count: {count}</p>
   <button onclick="setCount(count + 1)">Increment</button>
@@ -99,10 +147,12 @@ Example:
 </div>
 ```
 
-That example shows runtime HTML after mountable roots already exist. In authored Caspian templates, you normally write the root without `pp-component` and let the Python renderer inject it before the browser runtime sees the HTML.
+That is the authored form. In browser-inspected runtime HTML, Caspian will already have added the component id and the owned script type.
 
 ## Hooks and runtime API
 
+PulsePoint uses a React-style mental model inside each component script: stateful render scope, dependency-based effects, refs, reducer-style updates, context consumption, and portals.
+
 Hooks exposed inside component scripts through `pp`:
 
 - `pp.state(initial)` returns `[value, setValue]`.
@@ -113,11 +163,10 @@ Hooks exposed inside component scripts through `pp`:
 - `pp.callback(callback, deps)` memoizes a function.
 - `pp.reducer(reducer, initialState)` returns `[state, dispatch]`.
 - `pp.context(token)` resolves a provided context value from ancestor components.
-- `pp.provideContext(token, value)` provides a context value to descendant components.
 - `pp.portal(ref, target?)` registers a ref-managed element for portal rendering and returns an object that includes `sourceParent`.
 - `pp.props` exposes the current props.
 
-Global helpers exposed on the `pp` singleton:
+Global helpers exposed through the `pp` singleton and also merged into the component runtime:
 
 - `pp.createContext(defaultValue)` creates a context token.
 - `pp.mount()` bootstraps the runtime. It is idempotent.
@@ -130,21 +179,22 @@ Global helpers exposed on the `pp` singleton:
 
 Notes:
 
-- The global `pp` singleton auto-mounts once `public/js/main.js` loads the bundled runtime and the DOM is ready. Manual `pp.mount()` is still safe because it short-circuits after the first mount.
+- The global `pp` singleton auto-mounts once the runtime is loaded and the DOM is ready. Manual `pp.mount()` is still safe because it short-circuits after the first mount.
 - `pp.state` setters accept either a value or an updater function.
 - `pp.effect` and `pp.layoutEffect` are cleanup-style hooks. Returned promises are not awaited.
 - `pp.portal(ref)` defaults to `document.body` when no target is provided.
 - Older docs may call the RPC helper `pp.fetchFunction()`. In the current bundled runtime the implemented global API is `pp.rpc()`.
 - Keep template-facing bindings at the top level so the AST-based exporter can see them.
+- For predictable code generation, prefer passing an explicit dependency array to `pp.effect`, `pp.layoutEffect`, `pp.memo`, and `pp.callback`.
 
 ## Context
 
-Context is implemented in the current runtime.
+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.
 
 How it works:
 
 - Create a token with `pp.createContext(defaultValue)`.
-- Provide a value from a component with `pp.provideContext(token, value)`.
+- Provide a value with `Context.Provider`.
 - 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.
@@ -157,30 +207,39 @@ Important:
 - The same token object must be shared between provider and consumer.
 - 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 global/outer state.
+- 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.
 
-Example:
+Provider example:
 
 ```html
-<section pp-component="theme-provider-1">
-  <div pp-component="theme-label-1" theme-token="{ThemeContext}">
-    <p>{theme}</p>
-
-    <script>
-      const { themeToken } = pp.props;
-      const theme = pp.context(themeToken);
-    </script>
-  </div>
-
+<section>
   <script>
     const ThemeContext = pp.createContext("light");
     const [theme] = pp.state("dark");
-
-    pp.provideContext(ThemeContext, theme);
   </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:
+
+```html
+<div>
+  <p>{theme}</p>
+
+  <script>
+    const theme = pp.context(pp.props.themeToken);
+  </script>
+</div>
+```
+
+When a child component needs the same token object, pass it from the provider scope as a prop such as `theme-token="{ThemeContext}"`.
+
 ## Props and nested components
 
 - Child component props are derived from DOM attributes.
@@ -215,7 +274,7 @@ Nested components:
 Example:
 
 ```html
-<div pp-component="profile-card-1">
+<div>
   <button pp-spread="{...buttonAttrs}" hidden="{isLoading}">Save</button>
 
   <script>
@@ -244,7 +303,7 @@ Example:
 Example:
 
 ```html
-<div pp-component="focus-box-1">
+<div>
   <input pp-ref="nameInput" />
   <button onclick="nameInput.current?.focus()">Focus</button>
 
@@ -268,7 +327,7 @@ Example:
 Example:
 
 ```html
-<div pp-component="todo-list-1">
+<div>
   <ul>
     <template pp-for="(todo, index) in todos">
       <li key="{todo.id}">
@@ -326,22 +385,43 @@ Notes:
 - Root-layout mismatches during SPA navigation trigger a hard reload.
 - `pp.mount()` bootstraps every `[pp-component]` it finds, so generated code should call it only through the global runtime if you are manually mounting at all.
 
+## Runtime Output And Debugging
+
+When you inspect rendered HTML in the browser, you should expect to see runtime-managed attributes and elements that are not part of authored source.
+
+Normal runtime output includes:
+
+- `pp-component="..."` on mounted roots.
+- `script[type="text/pp"]` for owned component scripts.
+- internal attributes such as captured ref tokens and event-owner bookkeeping.
+
+These are runtime details.
+
+- Mention them in docs when explaining how the browser runtime works.
+- Do not use them as the default form in authored examples.
+- Do not tell AI to handwrite them in route, layout, or component templates unless the task is explicitly about raw runtime HTML or runtime internals.
+
 ## AI rules
 
 Use these rules when generating or editing PulsePoint runtime code:
 
 - Treat PulsePoint as the default reactive frontend for Caspian app code.
-- Use the bundled runtime contract in `public/js/pp-reactive-v2.js`.
-- Generate unique `pp-component` values per live instance.
-- Use only `<script>` for component logic inside a `pp-component` root.
+- Use `public/js/pp-reactive-v2.js` as the shipped runtime contract AI should follow.
+- Keep `main.py` in view because it injects the runtime-facing attributes and rewrites authored scripts before the browser sees them.
+- If a development-only source tree exists behind the shipped runtime, treat it as optional implementation detail rather than something generated apps are guaranteed to contain.
+- In authored Caspian templates, do not handwrite `pp-component` or `type="text/pp"`; let the render pipeline inject them.
+- 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.
-- Use `pp.createContext`, `pp.context`, and `pp.provideContext` for context. Do not invent `pp-context`.
+- Follow the React-style context pattern: `pp.createContext(...)`, `<Context.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.
 - Use refs and portals only through the implemented `pp` APIs.
 - Use `pp.rpc()` for the bundled runtime API instead of older `pp.fetchFunction()` wording.
 - Avoid generating internal runtime attributes.
 - Avoid scriptless nested components when the child template contains its own bindings.
+- Prefer authored-template examples over runtime-inspected HTML examples unless the doc is specifically explaining runtime internals.
 
 ## What to avoid
 
@@ -351,12 +431,13 @@ Do not generate these unless the current source explicitly adds support:
 - `pp-context`
 - `pp-key`
 - `data-pp-ref`
+- `pp-context-provider`
 - `pp-owner`
 - `pp-event-owner`
 - `pp-dynamic-script`
 - `pp-dynamic-meta`
 - `pp-dynamic-link`
-- plain `<script>` for component logic inside a `pp-component` root
+- handwritten `pp-component="..."` or `type="text/pp"` in authored route, layout, or component templates
 - `pp.fetchFunction()` as the current raw runtime helper name
 - made-up hooks, directives, or globals not present in the current bundled runtime
 
@@ -365,10 +446,13 @@ Do not generate these unless the current source explicitly adds support:
 These are current runtime caveats that matter for authors and AI tools:
 
 - `pp-component` is the registry key for instances, state, parent tracking, and templates. Treat it as unique per mounted root.
-- Nested roots without their own `script` block are not fully isolated during parent template compilation.
+- `public/js/pp-reactive-v2.js` is the runtime surface that ships and should be assumed to exist.
+- Caspian already injects `pp-component` and rewrites owned scripts to `type="text/pp"` during render.
+- Nested roots without their own `script[type="text/pp"]` block are not fully isolated during parent template compilation.
 - 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.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

@@ -78,8 +78,36 @@ Route templates can import reusable Python components with `<!-- @import ... -->
 
 Do not manually add `pp-component="..."` to the route root. The Python render pipeline injects that attribute onto the route's single top-level lowercase HTML element.
 
+Do not manually add `type="text/pp"` to a route-owned script either. In source templates, write a plain `<script>` inside the root and let `main.py` call `transform_scripts(...)` before the browser runtime sees the HTML.
+
 That means route templates follow the same single-root discipline as component templates: one root element, no sibling roots, and PulsePoint scripts kept inside that root when needed.
 
+For AI-generated route templates, treat `src/app/**/index.html` the same way you would a React component body: return one parent element that contains the entire route markup.
+
+Good:
+
+```html
+<section class="dashboard-shell">
+  <h1>Dashboard</h1>
+
+  <script>
+    const [filter, setFilter] = pp.state("all");
+  </script>
+</section>
+```
+
+Bad:
+
+```html
+<section class="dashboard-shell">
+  <h1>Dashboard</h1>
+</section>
+
+<script>
+  const [filter, setFilter] = pp.state("all");
+</script>
+```
+
 Example authored route template:
 
 ```html
@@ -88,7 +116,7 @@ Example authored route template:
 <section class="dashboard-shell">
   <StatsCard title="Users" value="42" />
 
-  <script type="text/pp">
+  <script>
     const [filter, setFilter] = pp.state("all");
   </script>
 </section>
@@ -108,7 +136,7 @@ Rendered shape at runtime:
 </section>
 ```
 
-Write the first form. Caspian produces the second form.
+Write the first form. Caspian produces the second form by injecting `pp-component` on the root and `type="text/pp"` on the owned script.
 
 ### `index.py`
 

package/package.json

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