caspian-utils 0.0.1 → 0.0.2

package/dist/docs/commands.md

@@ -16,6 +16,8 @@ This page summarizes the main Caspian CLI workflows for creating projects, gener
 
 ## Overview
 
+The current workspace includes a local `prisma` binary, but it does not include local `create-caspian-app`, `casp`, or `ppy` binaries under `node_modules/.bin`. Treat the scaffold and project-update commands below as external `npx` workflows rather than project-local executables.
+
 Use Caspian CLI commands for three main tasks:
 
 - Create a new application.
@@ -52,21 +54,21 @@ Common scaffold flags include:
 
 - `--backend-only` for API-only projects without frontend assets
 - `--tailwindcss` to install Tailwind CSS support
-- `--typescript` to add TypeScript and Vite support
+- `--typescript` to add TypeScript support and any scaffold-specific TypeScript build/config files
 - `--mcp` to initialize a Model Context Protocol server for AI agents
 - `--prisma` to initialize Prisma ORM support
 
 ## Code Generation
 
-When your Prisma schema changes, use the generation command shown in the Caspian CLI docs:
+When your Prisma schema changes in this workspace, regenerate the client with the local Prisma CLI:
 
 ```bash
-npx ppy generate
+npx prisma generate
 ```
 
-This flow regenerates the Python Prisma client based on `prisma/schema.prisma`.
+This flow regenerates the Prisma client defined by `generator client` in `prisma/schema.prisma`. In the current workspace, that generator uses `prisma-client-js`.
 
-In Prisma-enabled Caspian apps, this is the step that keeps the shared imports under `src/lib/prisma/` aligned with the schema.
+This workspace already includes an app-owned Python database layer in `src/lib/prisma/`, so reuse that package for Python-side database access instead of creating a second helper.
 
 See `database.md` for the full Prisma workflow, including `.env`, `prisma.config.ts`, migrations, and async usage patterns.
 
@@ -78,7 +80,7 @@ Use the project update command for existing Caspian apps:
 npx casp update project
 ```
 
-This command updates framework-managed project files and can overwrite entry points, styles, or configuration files if they are not protected.
+This command updates framework-managed project files and can overwrite entry points, styles, or configuration files if they are not protected. The `casp` binary is not bundled locally in this workspace, so verify the external CLI package before automating this command.
 
 ## Configuration
 
@@ -111,7 +113,7 @@ If an AI agent is deciding which command flow to use, apply these rules first.
 - Use `npx create-caspian-app@latest` when the user is creating a new project.
 - Use `npx casp update project` only for an existing Caspian project.
 - Read `caspian.config.json` before running update commands.
-- Use `npx ppy generate` after Prisma schema changes.
-- Check `database.md` when the task involves Prisma setup, schema updates, or generated client files under `src/lib/prisma/`.
+- Use `npx prisma generate` after Prisma schema changes in this workspace.
+- Check `database.md` when the task involves Prisma setup, schema updates, or the current workspace's schema, migration, and seed tooling.
 - Check [routing.md](./routing.md) before generating or modifying route folders under `src/app/`.
 - Check [project-structure.md](./project-structure.md) before placing generated files into the project.

package/dist/docs/database.md

@@ -1,6 +1,6 @@
 ---
 title: Database
-description: Use Prisma in Caspian with the generated async Python client, schema-first workflow, and the shared imports under `src/lib/prisma/`.
+description: Use Prisma in this workspace through `prisma/schema.prisma`, `prisma.config.ts`, migrations, seeding, and the generated client defined by the local schema.
 related:
   title: Related docs
   description: Use the project structure guide to place database files correctly, then use the fetch-data guide when Prisma calls need to power route rendering or RPC actions.
@@ -12,9 +12,9 @@ related:
     - /docs/index
 ---
 
-This page documents the default Caspian database workflow with Prisma ORM.
+This page documents the Prisma workflow present in this workspace.
 
-Treat Prisma as the default persistence layer when a Caspian app includes database support. The Prisma schema is the source of truth, the generated Python client is the runtime interface, and route code should import the shared client from `src.lib.prisma` instead of constructing ad hoc database connections inside each page or RPC action.
+This repo currently uses Prisma for schema management, migrations, and seed tooling on the Node side. The local `prisma/schema.prisma` uses `generator client { provider = "prisma-client-js" }`, `prisma.config.ts` seeds through `tsx prisma/seed.ts`, and this workspace already includes an app-owned Python database layer under `src/lib/prisma/`. If Python routes or RPC actions need database access, reuse that package instead of creating another helper.
 
 ## Overview
 
@@ -22,9 +22,9 @@ The standard Prisma flow in Caspian is:
 
 1. Define models in `prisma/schema.prisma`.
 2. Configure `DATABASE_URL` in `.env`.
-3. Run `npx ppy generate` after schema changes.
-4. Import the generated async client from `src.lib.prisma.db` or `src.lib.prisma`.
-5. Use Prisma calls inside `page()`, `layout()`, or `@rpc()` actions.
+3. Run `npx prisma generate` after schema changes.
+4. Use the generated client from Node-side tooling such as `prisma/seed.ts`.
+5. Reuse the shared Python database layer in `src/lib/prisma/` when Python route or RPC code needs database access.
 
 Use this workflow instead of writing raw SQL first. Drop to raw SQL only when a query cannot be expressed clearly with the generated client.
 
@@ -68,7 +68,7 @@ Keep schema in `prisma/schema.prisma`, connection secrets in `.env`, and generat
 
 ## Define Your Schema
 
-Model your data in `prisma/schema.prisma`. This file is the source of truth for both the database structure and the generated Python client API.
+Model your data in `prisma/schema.prisma`. This file is the source of truth for the database structure used by both the generated Node Prisma client and the app-owned Python layer in `src/lib/prisma/`.
 
 Example:
 
@@ -79,7 +79,7 @@ datasource db {
 }
 
 generator client {
-  provider = "prisma-client-py"
+    provider = "prisma-client-js"
 }
 
 model User {
@@ -99,13 +99,13 @@ model Post {
 }
 ```
 
-After changing the schema, regenerate the Python client before using new models or fields in app code.
+After changing the schema, run `npx prisma generate` so the generated Node Prisma client stays in sync with the schema. If the Python layer in `src/lib/prisma/` depends on the updated shape, regenerate or refresh that application-owned code too.
 
 ## Command Reference
 
 Use these commands for the normal Prisma lifecycle in Caspian:
 
-- `npx ppy generate` compiles `schema.prisma` into the generated Python client. Run this after every schema change.
+- `npx prisma generate` compiles `schema.prisma` into the generated Prisma client. Run this after every schema change.
 - `npx prisma migrate dev` creates and applies a development migration.
 - `npx prisma migrate deploy` applies pending migrations in deployment environments.
 - `npx prisma db push` syncs schema changes without creating a migration file, which is useful for prototyping.
@@ -114,69 +114,45 @@ Use these commands for the normal Prisma lifecycle in Caspian:
 
 Default rule:
 
-- Use `npx ppy generate` every time the schema changes.
+- Use `npx prisma generate` every time the schema changes.
 - Use migrations for tracked application changes.
 - Use `db push` only when you intentionally want a faster, migration-free prototype loop.
 
-## Generated Python Client Files
+## Prisma Files In This Workspace
 
-In a Prisma-enabled Caspian app, the generated and shared Python imports live under `src/lib/prisma/`.
+The current repo ships Prisma files in these locations:
 
-### `src/lib/prisma/db.py`
+### `prisma/schema.prisma`
 
-This module exposes the shared Prisma client instance used by route code and RPC actions.
+This file is the schema source of truth. It currently defines a `prisma-client-js` generator.
 
-Typical usage:
+### `prisma.config.ts`
 
-```python
-from src.lib.prisma.db import prisma
-
-users = await prisma.user.find_many()
-```
+This file configures the schema path, migrations path, and the seed entry point. In this workspace it runs seeds through `tsx prisma/seed.ts`.
 
-Use this import as the default way to access the database. Do not instantiate new Prisma clients inside each request handler unless you are solving a very specific lifecycle problem.
+### `prisma/seed.ts`
 
-### `src/lib/prisma/models.py`
+This file is the current example of code that imports and uses the generated Prisma client.
 
-This module contains the generated Python model types derived from `prisma/schema.prisma`.
+### `node_modules/@prisma/client/`
 
-Use it when you need explicit model imports for typing, serialization, or helper code that works with generated record objects.
+After `npx prisma generate`, Prisma writes the generated JavaScript client into the normal `@prisma/client` package location.
 
-Typical usage pattern:
-
-```python
-from src.lib.prisma import models
-
-def as_public_user(user: models.User) -> dict:
-    return {
-        "id": user.id,
-        "email": user.email,
-        "name": user.name,
-    }
-```
+### `src/lib/prisma/`
 
-Treat these classes as generated artifacts. Change the schema, then regenerate, instead of editing model definitions by hand.
+This workspace already includes an app-owned async Python database package that exports `prisma`, `PrismaClient`, generated models, and helper types.
 
-### `src/lib/prisma/__init__.py`
+If Python route or RPC code needs database access, import from `src.lib.prisma` and keep that import path explicit in application code.
 
-This module is the package entry point for Prisma imports.
+## Python Route Usage
 
-If it re-exports the shared client and generated model helpers, application code can use a shorter import shape such as:
-
-```python
-from src.lib.prisma import prisma, models
-```
-
-Prefer this package-level import when it keeps route code clearer. Prefer direct imports from `db.py` when you want to make the client source explicit.
-
-## Async Client Usage
-
-The Prisma client in Caspian should be treated as async-first. Use `await` for database operations.
+This workspace already ships an app-owned Python Prisma-style layer under `src/lib/prisma/`. Treat it as async-first and reuse it from route and RPC code.
 
 Example:
 
 ```python
-from src.lib.prisma.db import prisma
+from casp.layout import render_page
+from src.lib.prisma import prisma
 
 async def page():
     users = await prisma.user.find_many()
@@ -189,9 +165,10 @@ async def page():
 Prisma calls fit naturally in:
 
 - `async def page()` for first-render data
-- `async def layout()` for shared section 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.
+
 See `fetch-data.md` for the recommended route-render versus RPC split.
 
 ## CRUD Examples
@@ -301,7 +278,7 @@ print(stats["_count"]["_all"])
 ### Transactions
 
 ```python
-async with prisma.tx() as tx:
+async with prisma.transaction() as tx:
     user = await tx.user.create(
         data={
             "email": "alice@example.com",
@@ -330,7 +307,7 @@ Use raw SQL sparingly. Prefer the generated Prisma API when the query can be exp
 ## Recommended Project Rules
 
 - Keep the schema in `prisma/schema.prisma` and regenerate the client after changes.
-- Import the shared client from `src.lib.prisma.db` or `src.lib.prisma`, not from ad hoc connection code scattered across routes.
+- Reuse `src/lib/prisma/` for Python-side database access instead of creating a second bridge.
 - Keep reusable database helpers in `src/lib/`, and keep route-specific orchestration in `src/app/`.
 - Use `await` with Prisma operations.
 - Convert Prisma objects to template-safe dictionaries when rendering HTML.
@@ -343,9 +320,9 @@ If an AI agent is working on a Caspian app with Prisma enabled, apply these rule
 
 - Treat Prisma as the default ORM and persistence layer.
 - Read `prisma/schema.prisma` before proposing model, relation, or field changes.
-- Run `npx ppy generate` after schema changes so the Python client matches the schema.
-- Import the shared client from `src.lib.prisma.db` or the `src.lib.prisma` package entry point.
-- Treat `src/lib/prisma/models.py` as generated model output, not hand-authored business logic.
+- Run `npx prisma generate` after schema changes.
+- Read `prisma.config.ts` and `prisma/seed.ts` when you need the current workspace's Prisma tooling examples.
+- Reuse the existing `src/lib/prisma/` package when the Python app needs database access.
 - Put reusable database helpers in `src/lib/`; keep route and RPC orchestration in `src/app/`.
-- Use `page()` or `layout()` for first-render reads and `@rpc()` plus `pp.rpc()` for browser-triggered reads and writes.
+- 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.
 - Check `fetch-data.md` for route versus RPC guidance and `validation.md` before writing public mutations.

package/dist/docs/fetch-data.md

@@ -23,7 +23,7 @@ Treat RPC as the default way for browser code to talk to Python in Caspian. Do n
 
 Caspian has two main data-loading paths:
 
-- `page()` or `layout()` for server-side data needed during the initial render
+- `page()` for initial-render data, plus `layout()` for synchronous 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:
@@ -34,7 +34,7 @@ In practice, most pages use both:
 
 ## Default Data Rule
 
-- Use `page()` or `layout()` for data required before HTML renders.
+- Use `page()` for async or route-level data required before HTML renders, and use `layout()` only for synchronous shared props or metadata.
 - Use `@rpc()` on the server and `pp.rpc()` in PulsePoint code for all browser-triggered data work after first render.
 - Keep custom REST or other endpoint patterns as explicit exceptions, not the baseline Caspian approach.
 
@@ -67,10 +67,10 @@ 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 data in `layout.py` when multiple child routes need the same payload.
+- 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()`.
 - Keep reusable database or API clients under `src/lib/`; keep route-specific orchestration in `src/app/`.
 
-If the data source is Prisma, see `database.md` for schema, generation, and shared client import conventions.
+If the data source is Prisma, see `database.md` for the current workspace's schema, migration, and generation workflow. This scaffold does not generate Python-side Prisma helpers under `src/lib/` by default.
 
 ## Interactive Data With RPC
 
@@ -231,7 +231,7 @@ For initial route rendering with `render_page(...)`, prefer passing plain templa
 
 ## Recommended Decision Rule
 
-Use `page()` or `layout()` when the data is part of the page render. 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 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.
 
 A common pattern is:
 
@@ -246,7 +246,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 data in `layout.py` when multiple child routes need it.
+- 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()`.
 - Treat RPC as the default read and write layer between PulsePoint code and Python route logic.
 - Use `@rpc()` for backend functions that should be callable from the browser.
 - Use `pp.rpc()` for client-side calls; do not prefer older `pp.fetchFunction()` wording.

package/dist/docs/index.md

@@ -24,17 +24,17 @@ When generating or editing a Caspian app, treat these as the default choices unl
 
 The local AI-aware docs for this workspace live here:
 
-- `dist/docs/`
+- `node_modules/caspian-utils/dist/docs/`
 
-The packaged Caspian docs distributed by the framework live here:
+The packaged Caspian docs distributed by the current toolchain also live here:
 
-- `node_modules/caspian/dist/docs/`
+- `node_modules/caspian-utils/dist/docs/`
 
 ## Available Documents
 
 - `installation.md` - First-time setup flow for creating a new Caspian application
 - `commands.md` - Main Caspian CLI workflows for project creation, generation, updates, and config-aware maintenance
-- `database.md` - Prisma ORM setup, generated async Python client usage, and the shared `src/lib/prisma/` imports
+- `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
 - `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
@@ -51,10 +51,10 @@ If an AI tool needs Caspian project documentation, start with this directory and
 
 Preferred lookup order:
 
-1. Read `dist/docs/index.md` to discover available local docs.
+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/dist/docs/` for packaged Caspian docs when local docs need more detail.
+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.
 
 ## Maintenance

package/dist/docs/installation.md

@@ -14,7 +14,9 @@ This page documents the first-time Caspian setup flow for new applications.
 
 ## Overview
 
-Caspian provides a CLI that scaffolds a production-ready project with a FastAPI backend and a PulsePoint-based reactive frontend workflow.
+Caspian provides a scaffold flow for new apps with a FastAPI backend and a PulsePoint-based reactive frontend workflow.
+
+In this workspace, the local `caspian-utils` package ships documentation only, so scaffold commands are resolved through external `npx` packages rather than project-local binaries.
 
 ## Default App Stack
 
@@ -28,8 +30,8 @@ The scaffolded Caspian baseline is:
 
 Install the supported runtimes before creating a project.
 
-- Node.js `v24.14.0` or newer
-- Python `v3.14.0` or newer
+- Node.js with `npm` and `npx` available
+- Python `v3.11.0` or newer
 
 You can verify your environment with:
 
@@ -49,9 +51,8 @@ npx create-caspian-app@latest
 The interactive wizard walks through the main project options, including:
 
 - Project name
-- Tailwind CSS support
-- Prisma ORM setup
-- Swagger API documentation
+- Feature toggles such as backend-only mode, Tailwind CSS, Prisma, MCP, and TypeScript
+- Other scaffold options exposed by the current CLI version
 
 ## Recommended VS Code Setup
 
@@ -75,6 +76,8 @@ cd my-app
 npm run dev
 ```
 
+In this workspace, `npm run dev` is backed by BrowserSync plus PostCSS watchers, not a Vite dev server.
+
 ## After Setup
 
 Once the project is scaffolded:

package/dist/docs/metadata.md

@@ -84,7 +84,8 @@ Example:
 ```python
 from casp.layout import Metadata, render_page
 
-async def page(slug: str):
+async def page(params: dict):
+    slug = params["slug"]
     product_name = f"Product {slug.capitalize()}"
 
     Metadata(
@@ -99,6 +100,8 @@ async def page(slug: str):
     return render_page(__file__, {"name": product_name})
 ```
 
+In the current router, dynamic path params arrive as a single `params` dict passed to `page()`.
+
 Set dynamic metadata before calling `render_page(...)` so the route renders with the correct head values.
 
 Inside the same module, runtime `Metadata(...)` overrides matching keys from the module-level static `metadata` object.

package/dist/docs/project-structure.md

@@ -32,7 +32,7 @@ For public pages that can safely reuse rendered HTML, Caspian also supports rout
 - `main.py` is the application entry point.
 - `caspian.config.json` is the core feature configuration file.
 - `.venv/Lib/site-packages/casp/` contains the installed Caspian framework core.
-- `node_modules/caspian/dist/docs/` contains the packaged Caspian docs.
+- `node_modules/caspian-utils/dist/docs/` contains the packaged Caspian docs.
 
 ## Example Layout
 
@@ -62,7 +62,7 @@ my-app/
       site-packages/
         casp/
   node_modules/
-    caspian/
+    caspian-utils/
       dist/
         docs/
 ```
@@ -83,19 +83,13 @@ See `routing.md` for the full App Router-style rules for dynamic segments, route
 
 Use this folder for shared helpers, reusable validators, RPC-facing service wrappers, reusable UI utilities, and app-level support code.
 
-When Prisma ORM is enabled, this folder also contains the shared database client imports under `src/lib/prisma/`.
+This workspace already includes an app-owned Python database layer under `src/lib/prisma/`. Reuse that package for Python-side data access and keep any additional shared database helpers in `src/lib/`.
 
-### `src/lib/prisma/`
+### Shared Database Helpers
 
-When a Caspian app includes Prisma support, this folder contains the shared ORM imports used by route code and RPC actions.
+If your Python routes or RPC actions need reusable database access code, keep that helper layer under `src/lib/` and extend the existing `src/lib/prisma/` package.
 
-Typical files include:
-
-- `src/lib/prisma/db.py` for the shared Prisma client instance
-- `src/lib/prisma/models.py` for generated Python model types
-- `src/lib/prisma/__init__.py` for package-level re-exports such as `prisma` and `models`
-
-See `database.md` for the Prisma-specific workflow, generation step, and usage patterns.
+In this workspace, Prisma schema and seed files live under `prisma/`, while the Python-side adapter is application-owned code under `src/lib/prisma/`.
 
 ### `src/lib/auth/`
 
@@ -161,9 +155,9 @@ Notable internal files include:
 - `.venv/Lib/site-packages/casp/cache_handler.py` for route-level cache declarations, cache manifest handling, disk-backed HTML writes, and invalidation internals
 - `.venv/Lib/site-packages/casp/validate.py` for direct validators, rule-based validation, sanitization, and file-validation internals
 
-### `node_modules/caspian/dist/docs/`
+### `node_modules/caspian-utils/dist/docs/`
 
-The packaged Caspian documentation location distributed with the framework.
+The packaged Caspian documentation location distributed with the current toolchain.
 
 ## AI Routing Notes
 
@@ -176,7 +170,7 @@ If an AI agent is deciding where to make changes, use these rules first.
 - Use `@rpc()` in route/backend code and `pp.rpc()` in client code for browser-triggered data flows.
 - Use `casp.cache_handler` when a route's first-render HTML should be reused safely across requests.
 - Use `casp.validate` at route and RPC boundaries, and move reusable validators into `src/lib/` when multiple routes share them.
-- Use `database.md` when the task involves Prisma schema changes, generated client usage, or the shared files under `src/lib/prisma/`.
+- Use `database.md` when the task involves Prisma schema changes, migrations, seed logic, or workspace-specific database helper conventions.
 - Put authentication configuration in `src/lib/auth/auth_config.py`.
 - Put auth bootstrap, session middleware, and provider registration changes in `main.py`.
 - Put database models and seed logic in `prisma/`.
@@ -188,6 +182,6 @@ If an AI agent is deciding where to make changes, use these rules first.
 - Use `.venv/Lib/site-packages/casp/layout.py` when investigating or documenting Caspian routing, layout, or metadata internals.
 - Use `.venv/Lib/site-packages/casp/cache_handler.py` when investigating or documenting Caspian page-caching internals.
 - Use `.venv/Lib/site-packages/casp/validate.py` when investigating or documenting Caspian validation internals.
-- Look in `node_modules/caspian/dist/docs/` when you need the packaged framework docs.
+- Look in `node_modules/caspian-utils/dist/docs/` when you need the packaged framework docs.
 
 Check [index.md](./index.md) first if you need to choose between local Caspian docs.

package/dist/docs/pulsepoint.md

@@ -1,19 +1,19 @@
 ---
 title: PulsePoint Runtime Guide
-description: Learn how AI agents should use PulsePoint as the default reactive frontend contract in Caspian, including the current TypeScript runtime, component script rules, and supported directives.
+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 route, component, data-fetching, and TypeScript docs alongside the PulsePoint runtime contract.
+  description: Read the routing, data-fetching, and project-structure docs alongside the PulsePoint runtime contract.
   links:
-    - /docs/pages-and-layouts
-    - /docs/import-component
+    - /docs/routing
     - /docs/fetch-data
-    - /docs/typescript
+    - /docs/project-structure
+    - /docs/index
 ---
 
 ## Purpose
 
-This file documents the PulsePoint runtime that is actually implemented in the current TypeScript source under `ts/` and verified by `ts/__tests__/`. Treat it as the working contract for AI-generated code.
+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.
 
 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.
 
@@ -32,9 +32,9 @@ When a Caspian page needs reactive browser behavior, use PulsePoint.
 ## Source layer vs raw runtime
 
 - Source authoring under `src/` may use convenience syntax that is transformed before it reaches the browser.
-- This page describes the raw browser runtime implemented in `ts/`.
-- When source-layer examples conflict with the TypeScript runtime, follow the TypeScript runtime.
-- In the raw runtime, component logic uses `<script>`, not plain `<script>`.
+- 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>`.
 
 ## Runtime shape
 
@@ -51,15 +51,15 @@ Important:
 
 ## Component roots and scripts
 
-- Each runtime component root should have at most one component script.
-- The runtime only treats `<script>` as component logic.
+- Each runtime component root should have at most one `<script>` block.
+- The runtime only treats `script` 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.
 - 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` is removed from the render template.
+- `pp.props.children` contains the root's initial inner HTML before the owning `script` block is removed from the render template.
 
 Bindings exported to the template:
 
@@ -122,11 +122,11 @@ Global helpers exposed on the `pp` singleton:
 
 Notes:
 
-- The global `pp` singleton auto-mounts once `pp-utilities.js` is loaded 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 `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.
 - `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 TypeScript runtime the implemented global API is `pp.rpc()`.
+- 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.
 
 ## Context
@@ -188,8 +188,8 @@ Nested components:
 
 - Nested `pp-component` roots are treated as component boundaries during DOM reconciliation.
 - Parent prop interpolation still runs on nested child root attributes before the child refreshes.
-- Nested roots that contain their own `script` are masked during parent template compilation.
-- Scriptless nested component roots are not fully masked during parent template compilation in the current source. Avoid generating child-local interpolations inside a nested root unless that child has its own `script`.
+- Nested roots that contain their own `script` block are masked during parent template compilation.
+- Scriptless nested component roots are not fully masked during parent template compilation in the current source. Avoid generating child-local interpolations inside a nested root unless that child has its own `script` block.
 
 ## Template expressions and attributes
 
@@ -323,15 +323,15 @@ Notes:
 Use these rules when generating or editing PulsePoint runtime code:
 
 - Treat PulsePoint as the default reactive frontend for Caspian app code.
-- Use the current TypeScript runtime under `ts/` when it is available.
+- Use the bundled runtime contract in `public/js/pp-reactive-v2.js`.
 - Generate unique `pp-component` values per live instance.
-- Use only `<script>` for raw runtime component logic.
+- Use only `<script>` for component logic inside a `pp-component` root.
 - 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`.
 - Use native `on*` attributes, not framework-specific event syntax.
 - Use refs and portals only through the implemented `pp` APIs.
-- Use `pp.rpc()` for the raw TypeScript runtime API instead of older `pp.fetchFunction()` wording.
+- 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.
 
@@ -348,16 +348,16 @@ Do not generate these unless the current source explicitly adds support:
 - `pp-dynamic-script`
 - `pp-dynamic-meta`
 - `pp-dynamic-link`
-- plain `<script>` for raw runtime component logic inside a component root
+- plain `<script>` for component logic inside a `pp-component` root
 - `pp.fetchFunction()` as the current raw runtime helper name
-- made-up hooks, directives, or globals not present in the current TypeScript source
+- made-up hooks, directives, or globals not present in the current bundled runtime
 
 ## Review notes
 
 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` are not fully isolated during parent template compilation.
+- Nested roots without their own `script` 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.
@@ -365,4 +365,4 @@ These are current runtime caveats that matter for authors and AI tools:
 
 ## Final reminder
 
-If a feature is not implemented in the current TypeScript runtime source, do not invent it.
+If a feature is not implemented in the current bundled runtime, do not invent it.

package/dist/docs/routing.md

@@ -14,7 +14,7 @@ related:
 
 Caspian follows the same mental model as the Next.js App Router: routes live under `src/app`, folders define URL segments, layouts nest automatically, and special folder names control grouping and dynamic matching.
 
-The main difference is the file types. Instead of `page.tsx` and `layout.tsx`, Caspian uses `index.html`, `index.py`, `layout.html`, and optional Python companions for async server-side logic.
+The main difference is the file types. Instead of `page.tsx` and `layout.tsx`, Caspian uses `index.html`, `index.py`, `layout.html`, and optional Python companions for server-side logic.
 
 ## Overview
 
@@ -26,7 +26,7 @@ Start with these rules:
 - Use `index.html` for a template-only route.
 - Use `index.py` when the route needs metadata or async server-side logic.
 - Use `layout.html` to wrap child routes.
-- Use `layout.py` when a layout needs async data before rendering.
+- Use `layout.py` when a layout needs shared synchronous props or metadata before rendering.
 
 Use [cache.md](./cache.md) when an `index.py` route also needs declarative page caching via `Cache(...)`.
 
@@ -111,6 +111,18 @@ Wrap a folder name in brackets to make it variable.
 
 These segments are compiled into FastAPI path parameters for efficient route matching.
 
+In the current `main.py` router, path params are collected into a single dict and passed as the first positional argument to `page()`. Matching query params can still be injected by name, and `request` is passed by keyword when declared.
+
+Example:
+
+```python
+from casp.layout import render_page
+
+async def page(params: dict):
+    user_id = params["id"]
+    return render_page(__file__, {"user_id": user_id})
+```
+
 ### Catch-all Segments
 
 Use an ellipsis inside brackets to match multiple path parts.
@@ -164,15 +176,15 @@ Example root layout:
 
 ### `layout.py`
 
-If a layout needs async data, add a `layout.py` file next to the HTML layout.
+If a layout needs shared synchronous props or metadata, add a `layout.py` file next to the HTML layout.
 
 Example:
 
 ```python
 from casp.auth import auth
 
-async def layout(context_data):
-  user = auth.get_payload()
+def layout(context_data):
+    user = auth.get_payload()
 
     return {
         "user": user,
@@ -182,6 +194,8 @@ async def layout(context_data):
 
 `context_data` includes URL parameters such as dynamic route values.
 
+`layout()` currently runs synchronously in `casp.layout`. If you need async I/O, load it in `page()` instead of `layout.py`.
+
 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.
 
 ## Recommended Structure
@@ -220,7 +234,7 @@ If an AI agent is choosing where to add or update route code, apply these rules
 - Use folder names to model URL segments.
 - Use `index.html` for route templates and `index.py` for route-level async logic.
 - 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 async data.
+- Use `layout.html` for shared wrappers and `layout.py` for layout-level synchronous props or metadata.
 - Use [metadata.md](./metadata.md) when a route or layout needs SEO fields.
 - Use `[segment]` for single dynamic parameters.
 - Use `[...segment]` for catch-all route matching.

package/dist/docs/state.md

@@ -64,6 +64,8 @@ Important implementation detail:
 
 In other words, cross-request persistence depends on the surrounding Caspian middleware keeping `request.state.session` available and in sync with session storage.
 
+In this workspace's current `main.py`, `SessionMiddleware` exposes `request.session`, but the middleware stack does not mirror that into `request.state.session`. Treat persistence as opt-in until you add that bridge explicitly.
+
 ## Request Lifecycle
 
 The current request lifecycle is:
@@ -76,7 +78,7 @@ The current request lifecycle is:
 
 That last step matters. In the current implementation, non-wire requests start by clearing the loaded state and writing the empty state back to the session bucket.
 
-Treat the current behavior as request-local state plus framework-managed transient persistence for wire-driven flows. If you expect full-page redirect flash semantics, verify the exact middleware and request path in your local Caspian version before depending on it.
+Treat the current behavior in this repo as request-local state plus partially wired transient persistence for wire-driven flows. If you expect full-page redirect flash semantics or cross-request state reuse, verify the exact middleware bridge in your local Caspian version before depending on it.
 
 You usually do not initialize this manually in route code. The current auth middleware docs already show `StateManager.init(request)` running during request setup.
 
@@ -219,6 +221,7 @@ The current implementation resets `_state_listeners` inside `StateManager.init(.
 - `AttributeDict.__getattr__` raises `AttributeError` for missing keys and `__setattr__` writes back into the dict.
 - Because persistence uses JSON, keep stored values simple: strings, numbers, booleans, lists, dicts, and `None`.
 - The current lifecycle resets loaded state on non-wire requests, so verify redirect and flash behavior against the actual request type you are using.
+- In this repo's current middleware stack, `request.state.session` is not populated from `request.session`, so saved state may not survive into a later request unless you add that bridge.
 
 ## Recommended Usage Pattern
 
@@ -259,6 +262,7 @@ If an AI agent is deciding how to use transient state in a Caspian app, apply th
 - Do not assume recursive `AttributeDict` wrapping for nested dicts.
 - Treat `subscribe(...)` listeners as request-local and short-lived.
 - Be careful with full-page redirect assumptions because `init(request)` clears loaded state on non-wire requests.
+- Do not assume cross-request persistence in this repo until middleware copies `request.session` into `request.state.session`.
 - Use PulsePoint state for client interactivity and `StateManager` for server request flows.
 - Check [auth.md](./auth.md) for middleware ordering and request initialization details.
 - Check [project-structure.md](./project-structure.md) before deciding whether a transient-state helper belongs next to a route or in `src/lib/`.

package/package.json

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