caspian-utils 0.0.2 → 0.0.4

package/dist/docs/components.md

@@ -0,0 +1,269 @@
+---
+title: Components
+description: Create reusable Caspian components as `@component` Python functions, import them into templates as `<MyComponent />`, and split interactive UI into same-name HTML templates when PulsePoint logic is involved.
+related:
+  title: Related docs
+  description: Use the structure guide for file placement, the routing guide for route templates, the PulsePoint guide for browser-side scripts, and the data guide for component-owned RPC flows.
+  links:
+    - /docs/project-structure
+    - /docs/routing
+    - /docs/pulsepoint
+    - /docs/fetch-data
+    - /docs/index
+---
+
+Components in Caspian are Python functions decorated with `@component`.
+
+Import them into a template with an `@import` comment, then render them with JSX-style tags such as `<MyComponent />` or `<MyComponent>...</MyComponent>`.
+
+For the current workspace, component tooling scans Python files under the paths listed in `caspian.config.json`. Right now that means `src/`, so `src/components/` is the clean default location for reusable UI, even though any scanned path under `src/` can work.
+
+## Mental Model
+
+- Use a Python component when you want a reusable server-rendered UI building block.
+- Return an HTML string directly for small presentational components.
+- Use `render_html(...)` with a same-name `.html` file when the component has more markup, PulsePoint behavior, or clearer separation between Python logic and UI.
+- Keep page-level workflows in `src/app/`, and move reusable UI into components.
+
+## Basic Component
+
+This is the simplest pattern: accept props, merge classes or attributes, and return HTML.
+
+```python
+from casp.component_decorator import component
+from casp.html_attrs import get_attributes, merge_classes
+
+@component
+def Container(children: str = "", **props) -> str:
+    incoming_class = props.pop("class", "")
+    final_class = merge_classes("mx-auto max-w-7xl px-4", incoming_class)
+
+    attributes = get_attributes({
+        "class": final_class,
+    }, props)
+
+    return f'<div {attributes}>{children}</div>'
+```
+
+Notes:
+
+- `children` receives the inner content passed between opening and closing tags.
+- `**props` lets the component accept additional HTML attributes such as `id`, `data-*`, and `aria-*`.
+- The runtime normalizes `class`, `className`, and `class_name` into a merged `class` value before the component is called.
+
+## Import And Use Components
+
+Import components inside the HTML template where they are used.
+
+```html
+<!-- @import Container from "../components" -->
+
+<Container class="py-10">
+  <h1>Dashboard</h1>
+</Container>
+```
+
+The import comment is the bridge between the Python component file and the JSX-style tag.
+
+- `<!-- @import Container from "../components" -->` resolves `Container.py` from that folder.
+- The component function name should match the tag name you render, such as `Container` for `<Container />`.
+- Grouped imports and aliases are also supported, for example `<!-- @import { Button, Card as UserCard } from "../components/ui" -->`.
+
+## Template-Backed Components
+
+When a component includes richer UI or PulsePoint behavior, keep the Python file focused on props or server-side preparation and move the markup into a same-name HTML file.
+
+`Counter.py`
+
+```python
+from casp.component_decorator import component, render_html
+
+@component
+def Counter(label: str = "Clicks") -> str:
+    return render_html(__file__, {
+        "label": label,
+    })
+```
+
+`Counter.html`
+
+```html
+<div>
+  <h3>[[ label ]]</h3>
+  <button onclick="setCount(count + 1)">
+    {count}
+  </button>
+
+  <script>
+    const [count, setCount] = pp.state(0);
+  </script>
+</div>
+```
+
+Use this split when:
+
+- Python is shaping props, loading data, or exposing server-side helpers.
+- The template has enough markup that returning a raw f-string becomes noisy.
+- PulsePoint state, effects, refs, or event handlers belong next to the component markup.
+
+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 Script Type
+
+Treat `pp-component="componentName"` and `type="text/pp"` as framework output, not authored source.
+
+- 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.
+- `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` and `type="text/pp"`. That is the final output shape, not the normal authoring pattern.
+
+### Authored Source vs Rendered Output
+
+Author this:
+
+`Counter.html`
+
+```html
+<div>
+  <h3>[[ label ]]</h3>
+  <button onclick="setCount(count + 1)">
+    {count}
+  </button>
+
+  <script>
+    const [count, setCount] = pp.state(0);
+  </script>
+</div>
+```
+
+Do not author this by hand:
+
+```html
+<div pp-component="counter_ab12cd34">
+  <h3>Clicks</h3>
+  <button onclick="setCount(count + 1)">0</button>
+
+  <script type="text/pp">
+    const [count, setCount] = pp.state(0);
+  </script>
+</div>
+```
+
+The second example is the runtime shape after the Python side injects `pp-component` onto the component root.
+
+## Single-Root Rule
+
+Every component HTML template must render exactly one top-level lowercase HTML element.
+
+The same rule applies to route templates such as `src/app/**/index.html`: one root element, no sibling roots, and no manual `pp-component` authoring.
+
+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.
+
+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>
+```
+
+Bad:
+
+```html
+<div class="card">
+  <h2>Title</h2>
+</div>
+
+<script>
+  const [open, setOpen] = pp.state(false);
+</script>
+```
+
+Also bad:
+
+```html
+<h2>Title</h2>
+<p>Body</p>
+```
+
+Also avoid making another component tag the root of the HTML file. The root must be a normal lowercase HTML element such as `<div>`, `<section>`, or `<article>`.
+
+Think about this rule the same way you would in a React component: one parent element per template root. In Caspian, that requirement exists so the Python renderer has exactly one place to attach `pp-component`.
+
+## Props, Types, And Children
+
+Props come from the attributes on the component tag.
+
+```python
+from typing import Any, Literal
+
+from casp.component_decorator import component
+from casp.html_attrs import get_attributes, merge_classes
+
+ButtonVariant = Literal["default", "outline", "destructive"]
+
+@component
+def Button(
+    children: Any = "",
+    variant: ButtonVariant = "default",
+    **props,
+) -> str:
+    classes = {
+        "default": "btn btn-primary",
+        "outline": "btn btn-outline",
+        "destructive": "btn btn-danger",
+    }
+
+    incoming_class = props.pop("class", "")
+    attrs = get_attributes({
+        "class": merge_classes(classes[variant], incoming_class),
+    }, props)
+
+    return f'<button {attrs}>{children}</button>'
+```
+
+Use typed parameters when you want better editor hints and stricter component APIs. `Literal[...]` is a good fit for variants, sizes, or other closed sets of values.
+
+## Async Components
+
+Components can also be async. Use this only when the component render contract really depends on awaited work such as a database query, service call, or file read.
+
+```python
+from casp.component_decorator import component, render_html
+
+@component
+async def ProfileCard(user_id: str) -> str:
+    user = await get_user_by_id(user_id)
+
+    return render_html(__file__, {
+        "user": user,
+    })
+```
+
+Keep synchronous components as the default. Switch to `async def` only when the component itself needs awaited I/O.
+
+## Best Practices
+
+- Put reusable components in `src/components/` and keep route files in `src/app/`.
+- If the component includes PulsePoint behavior, prefer a thin Python wrapper plus a same-name `.html` template.
+- Keep the component file name, exported function name, and tag name aligned, such as `Button.py`, `def Button(...)`, and `<Button />`.
+- Accept `children` or `**props` when the component should support nested content.
+- Keep page-level data loading in `page()` when the data is not intrinsic to the component itself.
+- If you add `@rpc()` functions inside a component file, keep their names globally unique because component RPCs are not route-scoped.
+
+## Related Reading
+
+- Read [project-structure.md](./project-structure.md) for where reusable components should live.
+- Read [routing.md](./routing.md) when importing components into route templates.
+- Read [pulsepoint.md](./pulsepoint.md) for the runtime contract of `pp-component`, `script[type="text/pp"]`, props, and browser-side reactivity.
+- Read [fetch-data.md](./fetch-data.md) when a component needs browser-triggered `pp.rpc()` calls or component-owned server actions.

package/dist/docs/index.md

@@ -1,17 +1,20 @@
 ---
 title: Caspian Docs
-description: Caspian documentation with AI-aware routing to the right local docs before framework-specific code generation or project setup changes, with PulsePoint, RPC, and Validate as the default app stack.
+description: Caspian documentation with AI-aware routing to the right local docs before framework-specific code generation or project setup changes, with components, PulsePoint, RPC, and Validate as the default app stack.
 related:
   title: Next Steps
-  description: Start with installation, review the CLI commands, then use the structure guide to place Caspian files correctly.
+  description: Start with installation, review the CLI commands, then use the structure and component guides to place Caspian files correctly.
   links:
     - /docs/installation
     - /docs/commands
     - /docs/project-structure
+    - /docs/components
 ---
 
 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:
@@ -36,13 +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 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
@@ -52,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, `pulsepoint.md` for reactive frontend work, `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

@@ -1,11 +1,12 @@
 ---
 title: Project Structure
-description: Understand the default Caspian project layout so AI agents place files in the correct directories before generating PulsePoint templates, RPC actions, validation helpers, auth code, configuration, or database changes.
+description: Understand the default Caspian project layout so AI agents place routes, reusable components, PulsePoint templates, RPC actions, validation helpers, auth code, configuration, and database changes in the correct directories.
 related:
   title: Related docs
-  description: Start with installation for new apps, then use the auth guide for bootstrap and session wiring, the routing guide to map URLs correctly, and the cache guide when route HTML should be reused safely.
+  description: Start with installation for new apps, then use the component guide for reusable UI, the auth guide for bootstrap and session wiring, the routing guide to map URLs correctly, and the cache guide when route HTML should be reused safely.
   links:
     - /docs/installation
+    - /docs/components
     - /docs/auth
     - /docs/routing
     - /docs/cache
@@ -19,13 +20,16 @@ This page explains the default layout of a Caspian application, where Caspian co
 
 Caspian uses a lean project layout that keeps application code in `src`, database files in `prisma`, static assets in `public`, configuration in `caspian.config.json`, and framework internals in the installed package.
 
-In that layout, the default stack is PulsePoint in route templates, RPC for browser-triggered server calls, and `casp.validate` for input validation at route and action boundaries.
+In that layout, the default stack is Python components for reusable UI, PulsePoint in templates for reactive browser behavior, RPC for browser-triggered server calls, and `casp.validate` for input validation at route and action boundaries.
 
 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.
+- `src/components/` contains reusable Python components and optional same-name HTML templates.
 - `src/lib/auth/auth_config.py` contains auth-specific configuration for the app.
 - `prisma/` contains the Prisma schema and seed scripts.
 - `public/` contains static assets served directly.
@@ -50,6 +54,11 @@ my-app/
       index.py
       index.html
       globals.css
+    components/
+      Container.py
+      ui/
+        Button.py
+        Button.html
     lib/
       auth/
         auth_config.py
@@ -77,8 +86,24 @@ 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/`
+
+Use this folder for reusable UI components that should be imported into route templates or other component templates.
+
+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/`
 
 Use this folder for shared helpers, reusable validators, RPC-facing service wrappers, reusable UI utilities, and app-level support code.
@@ -124,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.
@@ -138,7 +167,9 @@ The backend logic for the route. This is where route behavior can load first-ren
 
 ### `src/app/index.html`
 
-The route template. It supports standard HTML, PulsePoint directives, and component imports, and it should be the default place for reactive frontend behavior in Caspian.
+The route template. It supports standard HTML, `<!-- @import ... -->` component imports, and PulsePoint directives, and it should be the default place for reactive frontend behavior in Caspian.
+
+Use `components.md` when the task involves authoring reusable `<MyComponent />` tags backed by Python files.
 
 ### `src/app/globals.css`
 
@@ -163,8 +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

@@ -3,8 +3,9 @@ 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.
 related:
   title: Related docs
-  description: Read the routing, data-fetching, and project-structure docs alongside the PulsePoint runtime contract.
+  description: Read the components, routing, data-fetching, and project-structure docs alongside the PulsePoint runtime contract.
   links:
+    - /docs/components
     - /docs/routing
     - /docs/fetch-data
     - /docs/project-structure
@@ -17,6 +18,8 @@ This file documents the PulsePoint runtime that is currently shipped in `public/
 
 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.
+
 PulsePoint is the default reactive frontend layer for Caspian.
 
 Do not assume React, Vue, Svelte, JSX, Alpine, HTMX, or older PulsePoint docs unless the task explicitly asks for a different frontend contract.
@@ -34,7 +37,9 @@ When a Caspian page needs reactive browser behavior, use PulsePoint.
 - 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 a `pp-component` root, component logic must live in `<script>`, not plain `<script>`.
+- In authored route, layout, and component templates, do not add `pp-component` manually. The Python side injects it onto the template root during render.
+- In authored templates, write PulsePoint logic in a plain `<script>` inside that root. `main.py` runs `transform_scripts(...)`, so the runtime receives `script[type="text/pp"]`.
+- When reading or debugging runtime HTML, look for `pp-component` roots and `script[type="text/pp"]`.
 
 ## Runtime shape
 
@@ -45,16 +50,19 @@ A component root is any element with `pp-component`.
 Important:
 
 - `pp-component` is the instance id used for the component registry, saved state, cached template, parent tracking, and instance lookup.
+- In normal Caspian authoring, `pp-component` arrives from the Python render pipeline on route, layout, and component roots rather than being handwritten in source templates.
 - Reusing the same `pp-component` value for multiple live roots will destroy the previous registered instance and replace it with the new one.
 - If a root is manually constructed with an empty `pp-component`, the runtime will assign an anonymous id. AI-generated markup should still use stable unique ids.
 - `pp.mount()` bootstraps every `[pp-component]` in the document, so do not manually instantiate `Component` in authored app code.
 
 ## 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 `script[type="text/pp"]` block.
+- The runtime only treats `script[type="text/pp"]` as component logic.
 - 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.
+- Authored component and route HTML templates must have exactly one top-level lowercase HTML root because the compiler injects `pp-component` onto that root during render. Think React-style single parent wrapper, not sibling top-level tags.
+- In authored Caspian templates, write plain `<script>` inside the single root and let the render pipeline rewrite it before mount.
 - 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.
@@ -82,7 +90,7 @@ Example:
   <p>Count: {count}</p>
   <button onclick="setCount(count + 1)">Increment</button>
 
-  <script>
+  <script type="text/pp">
     const { title } = pp.props;
     const [count, setCount] = pp.state(0);
 
@@ -93,6 +101,8 @@ 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 keep the logic in a plain `<script>` so the Python render path can inject both runtime attributes before the browser runtime sees the HTML.
+
 ## Hooks and runtime API
 
 Hooks exposed inside component scripts through `pp`:
@@ -324,8 +334,9 @@ 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.
+- 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`.
 - Keep `pp-for` on `<template>` and use plain `key`.
@@ -348,7 +359,7 @@ Do not generate these unless the current source explicitly adds support:
 - `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
 
@@ -357,7 +368,7 @@ 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.
+- 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.

package/dist/docs/routing.md

@@ -1,11 +1,12 @@
 ---
 title: Routing
-description: Understand Caspian's Next.js App Router-style file-based routing, including src/app conventions, index files, dynamic segments, route groups, and nested layouts.
+description: Understand Caspian's Next.js App Router-style file-based routing, including src/app conventions, index files, dynamic segments, route groups, nested layouts, and component-friendly route templates.
 related:
   title: Related docs
-  description: Read the structure guide first, then use the metadata guide for SEO fields, the cache guide for route-level HTML reuse, and the PulsePoint runtime guide for interactive route templates.
+  description: Read the structure guide first, then use the components guide for reusable UI, the metadata guide for SEO fields, the cache guide for route-level HTML reuse, and the PulsePoint runtime guide for interactive route templates.
   links:
     - /docs/project-structure
+    - /docs/components
     - /docs/cache
     - /docs/metadata
     - /docs/pulsepoint
@@ -73,6 +74,70 @@ Examples:
 
 Use `index.html` for the route template. This is the route's view layer.
 
+Route templates can import reusable Python components with `<!-- @import ... -->` comments and render them with JSX-style tags such as `<Button />`. Use [components.md](./components.md) for the component authoring rules.
+
+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
+<!-- @import StatsCard from "../components" -->
+
+<section class="dashboard-shell">
+  <StatsCard title="Users" value="42" />
+
+  <script>
+    const [filter, setFilter] = pp.state("all");
+  </script>
+</section>
+```
+
+Rendered shape at runtime:
+
+```html
+<section pp-component="page_a1b2c3d4" class="dashboard-shell">
+  <div pp-component="statscard_e5f6g7h8" title="Users" value="42">
+    ...
+  </div>
+
+  <script type="text/pp">
+    const [filter, setFilter] = pp.state("all");
+  </script>
+</section>
+```
+
+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`
 
 Use `index.py` when the route needs metadata or async server-side logic. Because Caspian runs on FastAPI, the page entry should be async.

package/package.json

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