caspian-utils 0.0.17 → 0.0.18

package/dist/docs/fetch-data.md

@@ -17,9 +17,9 @@ related:
     - /docs/index
 ---
 
-This page explains how data fetching works in Caspian. Use route functions for initial page data and use RPC actions for browser-triggered reads, writes, streams, and uploads.
+This page explains how data fetching works in Caspian. Use route functions for initial page data and use RPC actions for browser-triggered reads, writes, streams, uploads, and normal CRUD work.
 
-Treat RPC as the default way for browser code to talk to Python in Caspian. Do not reach for ad hoc fetch calls to custom JSON endpoints, alternate transport layers, or older helper names unless the task explicitly requires that shape.
+Treat RPC as the default way for browser code to talk to Python in Caspian. For CRUD operations and any browser-initiated backend reads after first render, default to `@rpc()` on the server and `pp.rpc()` in PulsePoint code. Do not reach for ad hoc fetch calls to custom JSON endpoints, alternate transport layers, or older helper names unless the task explicitly requires that shape.
 
 MCP is a separate integration surface. Do not place app-owned FastMCP tools in route `index.py` files or treat `@rpc()` actions as a replacement for MCP tools. Use `mcp.md` and `src/lib/mcp/` only when `caspian.config.json` has `mcp: true`. If `mcp` is false, do not assume those files exist.
 
@@ -36,15 +36,18 @@ In practice, most pages use both:
 2. Render that data into `index.html`.
 3. Call `pp.rpc()` for refreshes, form submits, toggles, infinite scroll, or streamed updates.
 
+If a route only needs UI and does not need first-render data, metadata, or other backend behavior, skip `index.py` and keep the page in `index.html` alone.
+
 ## Default Data Rule
 
 - Use `page()` for async or route-level data required before HTML renders, and use `layout()` only for synchronous shared props or metadata.
-- Use `@rpc()` on the server and `pp.rpc()` in PulsePoint code for all browser-triggered data work after first render.
+- When a route renders UI and also needs backend work, keep the HTML in the sibling `index.html`; `index.py` should prepare data and call `render_page(__file__, ...)`, not inline the route markup.
+- Use `@rpc()` on the server and `pp.rpc()` in PulsePoint code for all browser-triggered data work after first render, including CRUD operations and follow-up reads.
 - Keep custom REST or other endpoint patterns as explicit exceptions, not the baseline Caspian approach.
 
 ## Initial Data In `index.py`
 
-Use the route's backend file for data that should exist before the template is rendered.
+Use the route's backend file for data that should exist before the template is rendered. Keep the rendered page markup in the sibling `index.html`; if no backend data or logic is needed, omit `index.py` entirely.
 
 Example:
 
@@ -120,6 +123,7 @@ Call it from the client with `pp.rpc()`:
 
 Use RPC for:
 
+- CRUD reads and writes after the initial render
 - Button-triggered refreshes
 - Form submissions and mutations
 - Polling or background refreshes
@@ -292,7 +296,7 @@ If an AI agent is choosing how to load data in Caspian, apply these rules first.
 - Put first-render data loading in `src/app/**/index.py`.
 - Put shared section props in `layout.py` only when multiple child routes need the same synchronous data.
 - Keep async I/O in `page()` or `@rpc()` because the current layout engine does not await `layout()`.
-- Treat RPC as the default read and write layer between PulsePoint code and Python route logic.
+- Treat RPC as the default read and write layer between PulsePoint code and Python route logic, especially for CRUD and interactive backend reads.
 - Use `@rpc()` for backend functions that should be callable from the browser.
 - Use `pp.rpc()` for client-side calls; do not prefer older `pp.fetchFunction()` wording.
 - Prefer route-render data plus RPC over inventing parallel REST endpoints for normal Caspian page interactions.

package/dist/docs/metadata.md

@@ -31,6 +31,8 @@ Metadata is typically defined in one of two files:
 - `layout.py` for defaults shared by everything below that folder
 - `index.py` for route-specific metadata
 
+On routes that render UI, keep the page markup in the sibling `index.html`. `index.py` is the metadata and backend companion, not the place to store route HTML. If a route needs no metadata or backend behavior, omit `index.py` and keep the page as `index.html` only.
+
 The current `Metadata` implementation supports three fields:
 
 - `title`

package/dist/docs/project-structure.md

@@ -26,7 +26,7 @@ Caspian uses a lean project layout that keeps application code in `src`, databas
 
 As an app grows, keep reusable rendered UI in `src/components/`, keep reusable non-UI support code in `src/lib/`, and keep route-owned files in `src/app/`. That split keeps page composition separate from shared component and service code.
 
-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.
+In that layout, the default stack is Python components for reusable UI, PulsePoint in templates for reactive browser behavior, RPC for CRUD operations and browser-triggered backend reads, 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`.
 
@@ -105,6 +105,8 @@ This is the main application area. It contains route files, templates, styles, a
 
 This directory handles file-based routing. Route templates and route-specific backend logic live here.
 
+For any route that renders UI, keep that markup in `src/app/**/index.html`. If the route is UI-only, `index.html` alone is enough. Add `src/app/**/index.py` only as a companion when the same route needs metadata, `page()`, `@rpc()` actions, auth checks, caching, redirects, or other server-side behavior. Use a lone `index.py` only for non-visual routes such as redirect-only or action-only handlers.
+
 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.
@@ -227,7 +229,9 @@ If this layout imports reusable components, place each `<!-- @import ... -->` co
 
 ### `src/app/index.py`
 
-The backend logic for the route. This is where route behavior can load first-render data, expose `@rpc()` actions, and import framework features such as auth helpers, `casp.validate`, and route-level `Cache(...)` declarations.
+The backend logic companion for the route. Use this file when the same route needs first-render data, metadata, `@rpc()` actions, auth helpers, `casp.validate`, route-level `Cache(...)` declarations, redirects, or other server behavior.
+
+If the route renders UI, keep the markup in the sibling `index.html` and let `index.py` call `render_page(__file__, ...)` with whatever context the template needs. Do not store route HTML in `index.py`. A lone `index.py` should be reserved for non-visual routes.
 
 When a route owns a file manager or upload UI, keep the owning upload and delete `@rpc()` actions in that route's `index.py` and move reusable filesystem or Prisma helpers into `src/lib/`. Do not move ordinary upload behavior into `main.py`.
 
@@ -235,6 +239,8 @@ When a route owns a file manager or upload UI, keep the owning upload and delete
 
 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.
 
+If a route renders UI and needs no backend behavior, this file alone is sufficient. If the route also has an `index.py` companion, keep the visible page markup here.
+
 Treat import comments as top-of-file directives that belong above the route's single authored root element.
 
 Use `components.md` when the task involves authoring reusable `<MyComponent />` tags backed by Python files.
@@ -281,7 +287,7 @@ If an AI agent is deciding where to make changes, use these rules first.
 - Use `settings/bs-config.ts` when uploaded public assets should not trigger BrowserSync reloads during the local stack.
 - Put app-owned FastMCP code in `src/lib/mcp/` only when `caspian.config.json` enables MCP.
 - 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.
+- Use `@rpc()` in route/backend code and `pp.rpc()` in client code for browser-triggered data flows, especially CRUD operations and interactive backend reads.
 - 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, migrations, seed logic, or project-specific database helper conventions.

package/dist/docs/pulsepoint.md

@@ -44,6 +44,8 @@ If docs, generated examples, or older notes disagree with `public/js/pp-reactive
 When a Caspian page needs reactive browser behavior, use PulsePoint.
 
 - Use PulsePoint component roots, scripts, directives, and runtime helpers for interactive UI.
+- Use PulsePoint state, effects, refs, and template directives as the default reactivity model in authored Caspian templates.
+- When the browser needs CRUD operations or follow-up reads from the backend, call `pp.rpc()` from PulsePoint code and back it with route or backend `@rpc()` actions.
 - Keep server-rendered HTML plus PulsePoint enhancement as the baseline architecture.
 - Only introduce another frontend runtime when the user explicitly asks for it or the project already depends on one.
 
@@ -413,10 +415,12 @@ These are runtime details.
 Use these rules when generating or editing PulsePoint runtime code:
 
 - Treat PulsePoint as the default reactive frontend for Caspian app code.
+- Treat `pp.rpc()` as the default browser-to-server path for CRUD operations and interactive backend reads.
 - Use `public/js/pp-reactive-v2.js` as the shipped runtime contract AI should follow.
 - Keep `main.py` in view because it injects the runtime-facing attributes and rewrites authored scripts before the browser sees them.
 - If a development-only source tree exists behind the shipped runtime, treat it as optional implementation detail rather than something generated apps are guaranteed to contain.
 - In authored Caspian templates, do not handwrite `pp-component` or `type="text/pp"`; let the render pipeline inject them.
+- Prefer PulsePoint state and template directives over manual DOM mutation for reactive updates.
 - 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.

package/dist/docs/routing.md

@@ -25,8 +25,10 @@ Caspian uses a high-performance file-system router built on top of FastAPI. Your
 Start with these rules:
 
 - Put application routes in `src/app/`.
-- Use `index.html` for a template-only route.
-- Use `index.py` when the route needs metadata or async server-side logic.
+- For any route that renders a page, put the markup in `index.html`.
+- If a route is UI-only, `index.html` by itself is enough.
+- Add `index.py` only when the same route needs metadata, `page()`, `@rpc()` actions, auth checks, caching, redirects, or other server-side logic.
+- Use a standalone `index.py` only for non-visual routes such as redirects or action-only handlers.
 - Use `layout.html` to wrap child routes.
 - Use `layout.py` when a layout needs shared synchronous props or metadata before rendering.
 
@@ -46,7 +48,7 @@ If you already know the Next.js App Router, use this translation layer:
 | Next.js concept | Caspian equivalent |
 | --- | --- |
 | `app/` | `src/app/` |
-| `page.tsx` | `index.html` or `index.py` |
+| `page.tsx` | `index.html` plus optional `index.py` companion |
 | `layout.tsx` | `layout.html` and optional `layout.py` |
 | `[id]` | `[id]` |
 | `[...slug]` | `[...slug]` |
@@ -61,20 +63,32 @@ This means most App Router habits carry over directly:
 
 ## Core Concepts
 
-Every route lives inside `src/app`. A route is a folder that contains either an `index.html` file, an `index.py` file, or both as part of the route implementation.
+Every route lives inside `src/app`. For routes that render UI, `index.html` owns the markup and `index.py` is only an optional companion for server logic or metadata.
+
+Use this decision rule when creating routes:
+
+| Route shape | Files |
+| --- | --- |
+| UI only | `index.html` |
+| UI plus backend logic or metadata | `index.html` and `index.py` |
+| No rendered page, backend only | `index.py` |
 
 Examples:
 
-| File | URL |
+| Files | URL |
 | --- | --- |
 | `src/app/index.html` | `/` |
-| `src/app/about/index.py` | `/about` |
+| `src/app/about/index.html` | `/about` |
+| `src/app/dashboard/index.html` and `src/app/dashboard/index.py` | `/dashboard` |
 | `src/app/blog/posts/index.html` | `/blog/posts` |
+| `src/app/(auth)/signout/index.py` | `/signout` |
 
 ### `index.html`
 
 Use `index.html` for the route template. This is the route's view layer.
 
+If a route renders visible page content, that content belongs here even when the route also has an `index.py` companion.
+
 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.
 
 Place those import comments at the top of the file, above the authored root element. They are file-level directives, not children of the route root.
@@ -152,7 +166,9 @@ Write the first form. Caspian produces the second form by injecting `pp-componen
 
 ### `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.
+Use `index.py` as the backend companion when a route needs metadata or async server-side logic. For routes that render UI, keep the markup in the sibling `index.html` and let `page()` call `render_page(__file__, ...)`. Do not inline route HTML inside `index.py`.
+
+Use `index.py` by itself only for non-visual routes such as redirects or action-only handlers. Because Caspian runs on FastAPI, the page entry should be async when it performs async work.
 
 Example:
 
@@ -168,7 +184,7 @@ async def page():
     return render_page(__file__)
 ```
 
-Use this pattern when the route needs to fetch data, compute metadata, or do other non-blocking server work before rendering.
+Use this pattern when the route needs to fetch data, compute metadata, or do other non-blocking server work before rendering the sibling `index.html`.
 
 When a route owns a file manager or upload UI, keep the owning upload and delete `@rpc()` actions in that same `index.py` and move reusable filesystem or Prisma helpers into `src/lib/`. Do not move ordinary upload behavior into `main.py`. See [file-uploads.md](./file-uploads.md).
 
@@ -186,10 +202,12 @@ Wrap a folder name in brackets to make it variable.
 
 | File | Example URL |
 | --- | --- |
-| `src/app/users/[id]/index.py` | `/users/123` |
+| `src/app/users/[id]/index.html` | `/users/123` |
 
 These segments are compiled into FastAPI path parameters for efficient route matching.
 
+Add a sibling `index.py` when the dynamic route needs params during render, metadata, or other backend logic.
+
 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:
@@ -208,20 +226,22 @@ Use an ellipsis inside brackets to match multiple path parts.
 
 | File | Example URL |
 | --- | --- |
-| `src/app/docs/[...slug]/index.py` | `/docs/getting-started/setup` |
+| `src/app/docs/[...slug]/index.html` | `/docs/getting-started/setup` |
 
 Use catch-all routes when the number of path segments is not fixed ahead of time.
 
+Add a sibling `index.py` when that catch-all route also needs backend logic or metadata.
+
 ## Route Groups
 
 Wrap a folder name in parentheses to organize code without adding that segment to the URL.
 
 Examples:
 
-| File | URL |
+| Files | URL |
 | --- | --- |
-| `src/app/(auth)/login/index.py` | `/login` |
-| `src/app/(auth)/register/index.py` | `/register` |
+| `src/app/(auth)/signin/index.html` and `src/app/(auth)/signin/index.py` | `/signin` |
+| `src/app/(auth)/signup/index.html` and `src/app/(auth)/signup/index.py` | `/signup` |
 
 Route groups are useful when you want to:
 
@@ -292,18 +312,25 @@ src/
       index.html
     users/
       [id]/
+        index.html
         index.py
     docs/
       [...slug]/
+        index.html
         index.py
     (auth)/
       login/
+        index.html
         index.py
       register/
+        index.html
+        index.py
+      signout/
         index.py
     dashboard/
       layout.html
       settings/
+        index.html
         index.py
 ```
 
@@ -313,7 +340,8 @@ If an AI agent is choosing where to add or update route code, apply these rules
 
 - Treat `src/app/` as the routing source of truth.
 - Use folder names to model URL segments.
-- Use `index.html` for route templates and `index.py` for route-level async logic.
+- If a route renders UI, create or update `index.html` for the markup.
+- Add `index.py` only when the same route needs metadata or server behavior; do not place route HTML in `index.py`.
 - Use [cache.md](./cache.md) when an `index.py` route should opt into page-level HTML caching.
 - Use `layout.html` for shared wrappers and `layout.py` for layout-level synchronous props or metadata.
 - Keep `<!-- @import ... -->` directives at the top of `index.html` and `layout.html`, above the single authored root element.

package/package.json

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