caspian-utils 0.0.3 → 0.0.4

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

@@ -37,8 +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 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>`.
+- 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
 
@@ -56,11 +57,12 @@ 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 `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.
-- Component HTML templates must have exactly one top-level lowercase HTML root because the compiler injects `pp-component` onto that root during render.
+- 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.
@@ -88,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);
 
@@ -99,7 +101,7 @@ 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 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
 
@@ -332,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`.
@@ -356,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
 
@@ -365,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

@@ -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.4",
   "description": "Caspian tooling",
   "main": "index.js",
   "scripts": {