create-caspian-app 1.0.21 → 1.1.0

package/README.md

@@ -50,13 +50,25 @@ npm run dev
 
 ## What "Reactive Python" looks like
 
-A route is a folder. The markup lives in `index.html`, the server logic in `index.py`. Templates are **plain HTML** with `{expression}` interpolation and a small `<script>` for state.
+A route is a folder with one file: `index.py`. The markup lives inline as a template handed to `html(...)`, next to the server logic. Templates are **plain HTML** with `{expression}` interpolation and a small `<script>` for state.
 
-### Route template — `src/app/todos/index.html`
+### The route — `src/app/todos/index.py`
 
-```html
-<!-- @import { Badge } from "../../components/ui/Badge.py" -->
+```python
+from casp.component_decorator import html
+from casp.layout import Metadata
+from casp.rpc import rpc
+from casp.validate import Rule, Validate
+from src.components.ui.Badge import Badge
+
+metadata = Metadata(
+    title="Todos",
+    description="A tiny Caspian todo list.",
+)
 
+
+async def page():
+    return html(r"""
 <section>
   <x-badge variant="default">Tasks: {todos.length}</x-badge>
 
@@ -105,24 +117,7 @@ A route is a folder. The markup lives in `index.html`, the server logic in `inde
     }
   </script>
 </section>
-```
-
-### Backend — `src/app/todos/index.py`
-
-```python
-from casp.layout import Metadata, render_page
-from casp.rpc import rpc
-from casp.validate import Rule, Validate
-from src.lib.prisma import prisma
-
-metadata = Metadata(
-    title="Todos",
-    description="A tiny Caspian todo list.",
-)
-
-
-async def page():
-    return render_page(__file__)
+""")
 
 
 @rpc()
@@ -157,35 +152,31 @@ That is the whole loop: no API routes, no client, no serializer. `pp.rpc("create
 
 Your directory structure under `src/app` is your URL structure.
 
-| File                            | URL           |
-| ------------------------------- | ------------- |
-| `src/app/index.html`            | `/`           |
-| `src/app/about/index.html`      | `/about`      |
-| `src/app/blog/posts/index.html` | `/blog/posts` |
+| File                          | URL           |
+| ----------------------------- | ------------- |
+| `src/app/index.py`            | `/`           |
+| `src/app/about/index.py`      | `/about`      |
+| `src/app/blog/posts/index.py` | `/blog/posts` |
 
 ```
-src/app/users/[id]/index.html        ->  /users/123          (dynamic segment)
-src/app/docs/[...slug]/index.html    ->  /docs/a/b/c         (catch-all)
-src/app/(auth)/login/index.html      ->  /login              (route group, no URL segment)
-src/app/dashboard/layout.html        ->  wraps every /dashboard/* page
+src/app/users/[id]/index.py        ->  /users/123          (dynamic segment)
+src/app/docs/[...slug]/index.py    ->  /docs/a/b/c         (catch-all)
+src/app/(auth)/login/index.py      ->  /login              (route group, no URL segment)
+src/app/dashboard/layout.py        ->  wraps every /dashboard/* page
 ```
 
 #### Route file conventions
 
-| File             | Owns                                                                             |
-| ---------------- | -------------------------------------------------------------------------------- |
-| `index.html`     | The page's authored markup (single root element)                                 |
-| `index.py`       | `metadata`, `page()`, route-owned `@rpc()` actions, redirects, first-render data |
-| `layout.html`    | A section wrapper containing `<slot />`                                          |
-| `layout.py`      | Layout-level props and server logic                                              |
-| `loading.html`   | Navigation loading state for the route                                           |
-| `not-found.html` | 404 UI                                                                           |
-| `error.html`     | Error UI                                                                         |
-
-`page()` renders the sibling template with `render_page(__file__, context)`. It can also return a
-`(page_html, layout_props)` tuple, whose dict keys become `{{ layout.* }}` in a parent layout.
+| File             | Owns                                                                                                          |
+| ---------------- | ------------------------------------------------------------------------------------------------------------- |
+| `index.py`       | The page: `page()` returning `html(...)` markup, `metadata`, route-owned `@rpc()` actions, redirects, first-render data |
+| `layout.py`      | The section wrapper: `layout()` returning the shell template (with `<slot />`) plus optional props and server logic |
+| `loading.html`   | Navigation loading state for the route                                                                         |
+| `not-found.html` | 404 UI                                                                                                         |
+| `error.html`     | Error UI                                                                                                       |
 
-> **Rule:** `index.py` never inlines page HTML. Markup belongs in `index.html`.
+`page()` returns `html(r"""...""", **context)`. It can also return a
+`(page_html, layout_props)` tuple, whose dict keys become `{{ layout.* }}` in a parent layout.
 
 ---
 
@@ -237,7 +228,7 @@ Never handwrite runtime-managed attributes (`pp-component`, `pp-owner`, `pp-ref-
 
 #### The single-root rule
 
-Every route, layout, and component template must have **exactly one** top-level element (or one imported `x-*` root), with any owned `<script>` **inside** that root. Caspian injects `pp-component` on the final root and errors if it cannot find one. `<!-- @import ... -->` comments sit above the root and do not count as content.
+Every route, layout, and component template must have **exactly one** top-level element (or one imported `x-*` root), with any owned `<script>` **inside** that root. Caspian injects `pp-component` on the final root and errors if it cannot find one.
 
 ---
 
@@ -264,7 +255,7 @@ Component `<script>` blocks are plain JavaScript. The `pp` object mirrors React
 | `pp.optimistic(passthrough, reducer?)`        | Optimistic UI that reconciles against a confirmed value                |
 | `pp.props`                                    | Props bag derived from the rendered root's attributes                  |
 
-Runtime utilities: `pp.createContext`, `pp.mount`, `pp.redirect`, `pp.rpc`, `pp.enablePerf`, `pp.disablePerf`, `pp.getPerfStats`, `pp.resetPerfStats`.
+Runtime utilities: `pp.createContext`, `pp.mount`, `pp.redirect`, `pp.rpc`, `pp.socket`, `pp.enablePerf`, `pp.disablePerf`, `pp.getPerfStats`, `pp.resetPerfStats`.
 
 React APIs with **no** PulsePoint equivalent: `forwardRef`, `memo()` as a wrapper, `lazy`, `Suspense`, `useInsertionEffect`, `useActionState`, `useFormStatus`, free-function `startTransition`.
 
@@ -342,47 +333,27 @@ def UserCard(user=None, **props):
 
 > Use a raw string (`r"""…"""`) when the inline `<script>` contains backslashes (regex, `\n`).
 
-#### Template-backed (`render_html`) — for large markup
-
-`Counter.py`:
+#### Importing and rendering
 
 ```python
-from casp.component_decorator import component, render_html
-
-@component
-def Counter(label: str = "Clicks") -> str:
-    return render_html(__file__, {"label": label})
-```
-
-`Counter.html`:
+from casp.component_decorator import html
+from src.components.Container import Container
+from src.components.ui.Button import Button
+from src.components.Breadcrumb import Breadcrumb, BreadcrumbItem, BreadcrumbLink
 
-```html
-<div>
-  <h3>{{ label }}</h3>
-  <button onclick="setCount(count + 1)">{count}</button>
-
-  <script>
-    const [count, setCount] = pp.state(0);
-  </script>
-</div>
-```
-
-#### Importing and rendering
-
-```html
-<!-- @import Container from "../components" -->
-<!-- @import { Button, Card as UserCard } from "../components/ui" -->
-<!-- @import { Breadcrumb, BreadcrumbItem, BreadcrumbLink } from "../components/Breadcrumb.py" -->
 
+def page():
+    return html(r"""
 <x-container class="py-10">
   <x-button variant="outline">Continue</x-button>
 </x-container>
+""")
 ```
 
 - `Container` → `<x-container />`, `CommandDialog` → `<x-command-dialog />`.
-- If one Python file exports several components, import them **from that file path**, not from the folder.
-- `@import` is a file-level directive: it must sit **above** the authored root, never inside it.
-- For component-to-component composition, prefer real Python imports inside the component module; a component's own `x-*` tags resolve from its module imports.
+- A module's `x-*` tags resolve from the Component objects imported into that module — the Python import **is** the registration.
+- If one Python file exports several components, import them **from that module**, not from per-name modules that do not exist.
+- Slot content resolves in the scope where it was authored, so the module that writes an `x-*` tag must import that component.
 
 #### Props: every prop the template reads must be re-emitted on the root
 
@@ -557,15 +528,59 @@ Every optional capability is gated by one flag in `caspian.config.json`. **That
 | `typescript`  | TypeScript frontend tooling and the Vite build path                  |
 | `prisma`      | Prisma schema, migrations, and the generated Python ORM              |
 | `mcp`         | A FastMCP server mounted into the same app (`/mcp`)                  |
-| `websocket`   | App-owned FastAPI `@app.websocket(...)` endpoints and socket helpers |
+| `websocket`   | Named sockets — `@socket()` in Python, `pp.socket()` in the browser  |
+
+#### WebSockets — named sockets
+
+Use RPC for ordinary reads, writes, uploads, and SSE streams. Reach for a socket only for **long-lived bidirectional** channels: chat, collaboration, presence, multiplayer state.
+
+An rpc is a question with one answer, and an rpc stream is an answer that arrives in pieces. A **named socket** is the third shape — both sides may speak, at any time, for as long as the page is open. It is the socket counterpart of `@rpc()`/`pp.rpc()`: one decorated Python function, one browser call.
+
+```python
+from src.lib.websocket.sockets import Socket, socket
+
+@socket()
+async def echo(label: str, socket: Socket):
+    while (text := await socket.recv()) is not None:
+        if not await socket.send(f"{label}: {text}"):
+            break  # The browser is gone.
+```
+
+```html
+<script>
+  const sock = pp.ref(null);
+
+  pp.effect(() => {
+    sock.current = pp.socket(
+      "echo",
+      { label: "you" },
+      {
+        onMessage: (value) => append(value),
+        onError: (error) => setStatus(error.message),
+      },
+    );
+    return () => sock.current.close();
+  }, []);
+</script>
+```
+
+Open the socket inside `pp.effect(..., [])`, keep the handle in `pp.ref(...)`, and close it in the effect's cleanup. The handle exposes `send(value)`, `close(code?, reason?)`, and `readyState`; handlers are `onOpen`, `onMessage(value)`, `onError(error)`, `onClose({ code, reason, wasClean })`.
 
-#### WebSockets
+**The wire:**
 
-Use RPC for ordinary reads, writes, uploads, and SSE streams. Reach for WebSockets only for **long-lived bidirectional** channels: chat, collaboration, presence, multiplayer state.
+- Every socket connects to **one endpoint**, wired once in `main.py` and gated by the flag. The function is named in a query parameter, so socket names are **application-wide** — the function's own name, and a duplicate is refused at registration.
+- Arguments do **not** travel in the URL (a URL is logged by every proxy on the way) but as the connection's **first frame**: one JSON object, exactly the payload `pp.rpc` would have posted. The client sends it automatically on open. Keys are filtered against the handler's signature, like RPC.
+- Every frame after that is one JSON value, in either direction.
+- There is no status line inside an open connection, so **failure is a frame**: `{"error": "..."}` — that key alone — followed by a close. The client routes it to `onError`, never `onMessage`, and the server refuses to send that shape as an ordinary message.
+- A handler that returns is a conversation that ends: the connection closes. `await socket.send(...)` returning `False` means the browser is gone — a signal to stop, not an error to report.
 
-Endpoints are app-owned in `main.py`; reusable session/auth/broadcast helpers live in `src/lib/websocket/`. In the browser, use PulsePoint for state and lifecycle but the **native** `WebSocket` for the transport — keep the socket in `pp.ref(...)` and close it in a cleanup effect.
+**Broadcast:** `socket.sender()` returns a `SocketSender` — the sending half, detached from the conversation and safe to hold in shared state. A room is a `SocketPool` of senders, which prunes connections whose browser has left as it broadcasts. Keep authenticated and guest traffic in **separate pools** so a private broadcast can never fan out to a guest connection.
 
-**Sockets authorize themselves.** The HTTP middleware stack early-returns on `scope["type"] == "websocket"`, so `AuthMiddleware` does not protect them. Every endpoint must run its own origin + auth guard, and authenticated and guest traffic belong in separate broadcast pools.
+**Auth is declared per socket, not per endpoint.** `@socket()` is public, `@socket(require_auth=True)` needs a session, `@socket(allowed_roles=[...])` adds RBAC — all delegating to Caspian's `Auth`. This matters because the HTTP middleware stack early-returns on `scope["type"] == "websocket"`: `AuthMiddleware` never sees a handshake, so the socket endpoint authorizes each connection itself, alongside the anti-CSWSH origin check, connection ceiling, message-size limit, per-connection message rate, and idle timeout. The socket session is read-only — mutations are not persisted back to the cookie over a WebSocket.
+
+A hand-written `@app.websocket(...)` route with a native browser `WebSocket` remains the escape hatch for wires the JSON-frame contract cannot carry (binary frames, non-JSON protocols) — and then the app owns every one of those checks itself.
+
+A socket declared in a route's `index.py` registers when that route first renders, which is necessarily before the browser can open it. A socket shared by several routes belongs in `src/lib/**`.
 
 #### MCP
 
@@ -583,8 +598,9 @@ Caspian ships fail-closed defaults. Things worth knowing before you change them:
 - **RPC payload keys are filtered against the function signature.**
 - **`/uploads` serves user content in attachment mode**; only real image types render inline. First-party `/css`, `/js`, and `/assets` stay inline.
 - **CSRF protection, strict Origin validation, HttpOnly cookies, security headers, and page rate limiting** are on by default.
+- **Sockets authorize themselves.** The HTTP middleware stack early-returns on `scope["type"] == "websocket"`, so `AuthMiddleware` never sees a handshake. The named-socket endpoint runs the origin check, connection cap, and per-socket auth itself — HTTP route privacy does not extend to a socket.
 
-Security-relevant environment variables: `MCP_AUTH_TOKEN`, `RATE_LIMIT_PAGES` (default `200/minute`), `CONTENT_SECURITY_POLICY` (replaces the default policy wholesale), `MAX_WEBSOCKET_CONNECTIONS`, `MAX_WEBSOCKET_MESSAGES_PER_WINDOW`, `WEBSOCKET_RATE_WINDOW_SECONDS`, and `WEBSOCKET_ALLOWED_ORIGINS` (**required in production** — the same-origin fallback is derived from the client-supplied `Host` header and is development-only).
+Security-relevant environment variables: `MCP_AUTH_TOKEN`, `RATE_LIMIT_PAGES` (default `200/minute`), `CONTENT_SECURITY_POLICY` (replaces the default policy wholesale), `MAX_WEBSOCKET_CONNECTIONS`, `MAX_WEBSOCKET_MESSAGE_BYTES`, `MAX_WEBSOCKET_MESSAGES_PER_WINDOW`, `WEBSOCKET_RATE_WINDOW_SECONDS`, `WEBSOCKET_IDLE_TIMEOUT_SECONDS`, and `WEBSOCKET_ALLOWED_ORIGINS` (**required in production** — the same-origin fallback is derived from the client-supplied `Host` header and is development-only).
 
 ---
 
@@ -601,21 +617,18 @@ my-app/
 │   └── seed.ts
 ├── src/
 │   ├── app/                     # File-system routes
-│   │   ├── layout.html          # Root layout
-│   │   ├── layout.py
-│   │   ├── index.html           # Home page
-│   │   ├── index.py
+│   │   ├── layout.py            # Root layout (template + props from layout())
+│   │   ├── index.py             # Home page (markup + logic in one file)
 │   │   ├── globals.css
 │   │   ├── error.html
 │   │   ├── not-found.html
 │   │   └── users/[id]/
-│   │       ├── index.html       # /users/:id
-│   │       └── index.py
+│   │       └── index.py         # /users/:id
 │   ├── components/              # Reusable UI (@component)
 │   └── lib/                     # Non-UI code
 │       ├── auth/auth_config.py
 │       ├── prisma/              # Generated Python ORM — do not edit
-│       ├── websocket/           # Socket helpers (when websocket: true)
+│       ├── websocket/           # Named sockets: @socket(), Socket, SocketPool
 │       └── mcp/                 # FastMCP server (when mcp: true)
 ├── public/                      # Static assets, incl. the PulsePoint runtime and uploads
 └── settings/                    # Dev stack config and generated indexes
@@ -625,7 +638,7 @@ my-app/
 
 - **Route-owned** logic (first-render query, route `@rpc()` actions, redirects, route validation) stays in that route's `index.py`. Move it to `src/lib/**` only when it is genuinely shared.
 - **Reusable UI** goes in `src/components/`; **helpers, services, adapters** go in `src/lib/`.
-- **Compose pages from components.** A route's `index.html` should read as a short assembly of `x-*` chunks (topbar, sidebar, header, sections, forms, footer), not a wall of markup. Plan the breakdown before writing the route.
+- **Compose pages from components.** A route's page template should read as a short assembly of `x-*` chunks (topbar, sidebar, header, sections, forms, footer), not a wall of markup. Plan the breakdown before writing the route.
 - **Generated, never hand-edited:** `src/lib/prisma/**`, `settings/prisma-schema.json`, `settings/files-list.json`, `settings/component-map.json`, `public/css/styles.css`, `__pycache__/`.
 
 ---
@@ -697,8 +710,11 @@ Policy is **warn & skip**: dynamic routes are pre-rendered only when their `inde
 npx ppicons add Rocket
 ```
 
+```python
+from src.lib.ppicons.Rocket import Rocket
+```
+
 ```html
-<!-- @import { Rocket, ChevronDown } from "../lib/ppicons" -->
 <x-rocket class="w-6 h-6 text-primary" />
 ```
 
@@ -708,8 +724,11 @@ npx ppicons add Rocket
 npx maddex add button card dialog
 ```
 
+```python
+from src.lib.maddex.Button import Button
+```
+
 ```html
-<!-- @import { Button } from "../lib/maddex/Button.py" -->
 <x-button variant="outline">Continue</x-button>
 ```
 

package/dist/.github/copilot-instructions.md

@@ -14,12 +14,12 @@
 
 This is the top architectural requirement for this workspace. Treat it as a hard rule that outranks convenience, and apply it before writing any route, layout, or page markup.
 
-- Build pages from components, not from one large block of HTML. A route's `src/app/**/index.html` should read like a short composition of `x-*` component tags, not a wall of markup. When a page would otherwise carry a long stretch of HTML, that markup must move into a component instead of living in the page.
+- Build pages from components, not from one large block of HTML. A route's page template (the `html(r"""...""")` string in `src/app/**/index.py`) should read like a short composition of `x-*` component tags, not a wall of markup. When a page would otherwise carry a long stretch of HTML, that markup must move into a component instead of living in the page.
 - Separate every page into meaningful chunks and give each chunk its own component. Typical chunks are a top menu / topbar, header, sidebar / nav rail, hero, toolbar, content sections, cards, lists, forms, footer, and any repeated block. Each chunk owns its own long markup inside its component file, so the page content stays small and readable.
 - Default to single-file Python components authored with inline `html(...)` (import `html` from `casp.component_decorator`, return `html("""...""", **context)`) for each focused chunk. Single-file means the component's Python, markup, and small PulsePoint script live together; it does not mean the whole page, full dashboard, or every tab panel should be collapsed into one Python file.
 - Split component files by responsibility the way you would split React components. If a page has tabs, create focused components such as `OverviewTab.py`, `ActivityTab.py`, and `SettingsTab.py` instead of one oversized `DashboardTabs.py` that contains every panel. If a section has its own form, table, toolbar, or card list, make that section a component and pass data, flags, callbacks, or labels as props.
-- Put these page-chunk components in `src/components/` (or a route-local component folder when they are truly single-route), import them into the route with top-of-file `<!-- @import ... -->` directives above the route root, and render them as kebab-cased `x-*` tags. Keep the single-root contract in both the page and each component.
-- When the user asks to build or extend a page, plan the chunk breakdown first (for example: top menu component, sidebar component, content section component), create those components, then assemble them in the route. Do not start by pasting a full HTML page into `index.html` and only later consider extraction; component-first is the starting point, not a cleanup step.
+- Put these page-chunk components in `src/components/` (or a route-local component folder when they are truly single-route), import them into the route's `index.py` with normal Python imports, and render them as kebab-cased `x-*` tags. Keep the single-root contract in both the page and each component.
+- When the user asks to build or extend a page, plan the chunk breakdown first (for example: top menu component, sidebar component, content section component), create those components, then assemble them in the route. Do not start by pasting a full HTML page into the route template and only later consider extraction; component-first is the starting point, not a cleanup step.
 - If you find an existing page or single-file component with multiple unrelated responsibilities, prefer splitting it into focused chunk components as part of the work rather than adding more markup to it.
 
 ## Global Rules
@@ -66,21 +66,21 @@ This is the top architectural requirement for this workspace. Treat it as a hard
 - For normal forms, treat the HTML submit event as the first choice: bind `onsubmit="{submitForm(event)}"` on the `<form>`, call `event.preventDefault()` in the handler when staying on the page, and build the RPC payload with `Object.fromEntries(new FormData(event.currentTarget).entries())`. Let input `name` attributes define the payload keys and let Python validate, normalize, and decide what to persist. Do not add `pp-ref` to every input or attach an effect-managed submit listener just to build an RPC payload.
 - Treat imperative DOM APIs and `pp-ref` element reads as narrow escape hatches for third-party widgets, browser APIs that require direct DOM access, focus/measurement/media/canvas behavior, or one-off integration code. When they are needed, keep them inside the owning PulsePoint component script, usually behind `pp.ref(...)` and `pp.effect(...)`, so PulsePoint still owns the component state and event flow.
 - When `caspian.config.json` has `tailwindcss: true`, treat Python `merge_classes(...)` plus browser `twMerge(...)` as the only Tailwind class-merging contract: `merge_classes(...)` emits frontend-ready `{twMerge(...)}` expressions, and authored PulsePoint attribute expressions or scripts may call global `twMerge(...)` directly.
-- Treat Caspian component usage as HTML-first in the current runtime: import Python components with `<!-- @import ... -->` and render them as kebab-cased `x-*` tags such as `<x-button />` or `<x-command-dialog />`.
-- Components may be authored single-file. Return `html("""...""", **context)` (import `html` from `casp.component_decorator`) to keep markup, server interpolation, and a PulsePoint `<script>` inline instead of a same-name `.html` via `render_html(...)`. Inside `html(...)`, `{{ ... }}` is server-side Jinja and `{ ... }` is left for PulsePoint; never use a Python f-string for the markup. Autoescaping is on, so `{{ value }}` is safe for user text and trusted HTML needs `Markup(...)` or `| safe`; a `children` value is auto-safe. Prefer single-file `html(...)` for small and medium components, but keep each file focused on one responsibility. Split multiple panels, tabs, forms, tables, cards, and toolbars into separate components instead of making one giant single-file component.
+- Treat Caspian component usage as HTML-first: import Python components with normal Python imports and render them as kebab-cased `x-*` tags such as `<x-button />` or `<x-command-dialog />`. The Python import is what makes the tag resolve.
+- Components are authored single-file. Return `html(r"""...""", **context)` (import `html` from `casp.component_decorator`) to keep markup, server interpolation, and a PulsePoint `<script>` inline. Inside `html(...)`, `{{ ... }}` is server-side Jinja and `{ ... }` is left for PulsePoint; never use a Python f-string for the markup. Autoescaping is on, so `{{ value }}` is safe for user text and trusted HTML needs `Markup(...)` or `| safe`; a `children` value is auto-safe. Keep each file focused on one responsibility. Split multiple panels, tabs, forms, tables, cards, and toolbars into separate components instead of making one giant single-file component.
 - For single-file Python components that receive browser props, treat the Python render as an explicit bridge. Attributes on the parent `x-*` tag arrive as raw string kwargs, including unevaluated PulsePoint expressions such as `"{permOpen}"`; they do not reach `pp.props` merely because the Python signature accepts them. Re-emit browser-facing values on the component's single native root with `attributes = get_attributes({...}, props)`, `<root {{ attributes }}>`, and `html(..., attributes=attributes)`. Otherwise `pp.props` is silently empty or missing those keys with no error or warning. Forwarded props are real DOM attributes, so avoid accidental native behavior such as a `title` tooltip by choosing a non-native API name such as `user-name` when appropriate. Follow the full helper and prop-passing contract in `node_modules/caspian-utils/dist/docs/components.md`.
-- Inside single-file components, use real Python imports instead of `<!-- @import ... -->` comments for child components: a component's own `x-*` tags resolve from the components imported into its Python module, which disambiguates same-name components across directories. Do not put an import comment inside the `html("""...""")` string. Runtime resolution precedence is inherited ancestor components, then the component's own Python imports, then a local `@import`, but the authoring pattern for single-file components is Python imports. Slot content resolves in the scope where it was authored, so the template that writes an `x-*` tag must import that component.
+- Use real Python imports for child components everywhere: a module's `x-*` tags resolve from the Components imported into that module (pages and layouts included), which disambiguates same-name components across directories. Runtime resolution precedence is inherited ancestor components, then the module's own Python imports. Slot content resolves in the scope where it was authored, so the module that writes an `x-*` tag must import that component. For directories whose names are not valid identifiers (hyphens, `(group)`), bind via `importlib.import_module(...)` assignment.
 - For CRUD operations and any browser-initiated reads from the backend, use route or backend `@rpc()` actions on the server and `pp.rpc(...)` from PulsePoint code on the client unless the user explicitly asks for another integration pattern.
 - Google and GitHub OAuth ship pre-registered in this starter: `main.py` already calls `Auth.set_providers(GithubProvider(), GoogleProvider())`, and `AuthMiddleware` already handles the `signin/{google,github}` and `callback/{google,github}` paths under `api_auth_prefix` (default `/api/auth`). To add social sign-in, point a link or button at `/api/auth/signin/google` or `/api/auth/signin/github` and set the provider credentials in `.env` (`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GOOGLE_REDIRECT_URI`, `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`). Do not hand-roll an OAuth flow, manual `httpx2`/`authlib` token exchange, or custom callback routes; reuse the shipped providers and let `auth.auth_providers(...)` own redirect, callback, and sign-in.
 - For one-way streaming output, including AI/LLM/chat token streams, use Caspian's shipped RPC streaming: write a generator `@rpc()` action that `yield`s chunks (the runtime wraps generators as SSE via `casp.streaming.SSE`) and consume it with `pp.rpc(name, args, { onStream, onStreamComplete, onStreamError })`. When bridging a Python LLM/SDK stream, `async for` over the provider's stream inside the `@rpc()` action and `yield` each token. Do not reinvent one-way streaming with raw `fetch`/`ReadableStream`, `EventSource`, or a WebSocket; reserve WebSockets for genuinely bidirectional channels per the WebSocket rules above.
 - For live bidirectional channels, first confirm `caspian.config.json` has `websocket: true`, then use app-owned FastAPI WebSocket endpoints in `main.py` plus native browser `WebSocket` clients inside the owning PulsePoint route template. Do not replace normal CRUD, form submits, uploads, or one-way progress streams with WebSockets.
 - When `caspian.config.json` has `websocket: true`, WebSocket endpoint paths are project-defined in `main.py`; do not assume any default socket path or route folder exists in every Caspian project. Keep shared socket helpers under `src/lib/websocket/**` when session extraction, auth payload validation, connection tracking, or broadcast behavior is reused.
-- For route creation, keep page markup in `src/app/**/index.html`. If a route is UI-only, `index.html` alone is sufficient. 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. Keep shared section wrappers in `layout.html` and use `layout.py` only for shared props or metadata. Do not place route HTML in `index.py` or layout HTML in `layout.py`; use a lone `index.py` only for non-visual routes such as redirect-only or action-only handlers.
+- For route creation, every route is one `src/app/**/index.py`: `page()` returns the page markup via `html(...)`, and the same module owns metadata, `@rpc()` actions, auth checks, caching, and redirects. Shared section wrappers live in `layout.py`, whose `layout()` returns the wrapper template (optionally with a props dict). Non-visual routes (redirect-only or action-only) are `index.py` files whose `page()` returns a `Response`.
 - Keep route-specific logic in that route's `index.py`. Move code into `src/lib/**` only when it is genuinely reusable across routes, components, integrations, or features; do not extract one-route orchestration just to make it look generic.
 - Treat the single-root template contract as a hard requirement, not a style preference: every authored route, layout, and component HTML file must have exactly one parent HTML element or one imported `x-*` component tag as its root. Do not leave sibling top-level markup, and do not place a `<script>` after the root element. If a script is needed, keep it inside that same root.
-- When the user asks for a dashboard, admin area, account area, or any grouped child-route section, follow the same mental model as the Next.js App Router: create a parent folder with `layout.html`, add `layout.py` only when that section needs shared props or metadata, and place the child routes beneath it. Use a normal folder such as `dashboard/` when the segment should appear in the URL, and use `(group)/` only when it should not.
+- When the user asks for a dashboard, admin area, account area, or any grouped child-route section, follow the same mental model as the Next.js App Router: create a parent folder with `layout.py` and place the child routes beneath it. Use a normal folder such as `dashboard/` when the segment should appear in the URL, and use `(group)/` only when it should not.
 - In grouped section layouts with separate shell and content scrolling, put `pp-reset-scroll="true"` on the content scroll container that should reset on child-route navigation, usually the main pane. Leave persistent shell scrollers such as sidebars or rails unmarked so SPA navigation can preserve their scroll position.
-- When a single route needs to affect a wrapping layout, have `page()` return `(render_page(__file__, page_context), {"dashboard_body_class": ...})` and consume that value as `{{ layout.dashboard_body_class }}` in `layout.html`. Use `layout.py` when the same prop should apply across a whole subtree.
+- When a single route needs to affect a wrapping layout, have `page()` return `(html(...), {"dashboard_body_class": ...})` and consume that value as `{{ layout.dashboard_body_class }}` in the wrapping layout template. Return the prop from `layout()` when the same value should apply across a whole subtree.
 - For file uploads and file-manager flows, keep browser interaction in route templates, keep upload and delete `@rpc()` actions in the owning `src/app/**/index.py`, keep shared storage and persistence helpers in `src/lib/**`, store metadata in Prisma, and store browser-accessible blobs under `public/uploads/**` when the files should be served directly.
 - `public/uploads/**` is protected because `main.py` maps the top-level `uploads` directory to `INLINE_SAFE_UPLOAD_MEDIA_TYPES` in `PublicFilesMiddleware.inline_safe_subdirectories`. Before writing untrusted runtime uploads into any other top-level public directory, add that directory to the same restricted-inline mapping; otherwise trusted first-party public-file behavior would serve executable HTML or SVG inline.
 - Local upload helpers should create `public/uploads` on demand when it does not exist yet; do not assume the folder is committed ahead of time.
@@ -90,9 +90,9 @@ This is the top architectural requirement for this workspace. Treat it as a hard
 - Treat `pp-component` on routes, layouts, and components as compiler-injected by the Python side; do not add it manually in authored templates unless the task is explicitly about runtime internals. Author owned PulsePoint logic as a plain `<script>` inside the component root.
 - `layout()` can be synchronous or async in the installed runtime. Keep async layout work focused on shared layout props or metadata; use `page()` or `@rpc()` when the work belongs to a specific route or user action.
 - Dynamic route params currently reach `page()` as a single positional `dict`, with query params injected by name and `request` injected by keyword when declared.
-- In `layout.py`, return a dict for standard `{{ layout.* }}` props. Use `render_layout(__file__, {...})` only when that layout should consume direct local variables such as `{{ my_class }}` instead of `{{ layout.my_class }}`.
+- In `layout.py`, `layout()` returns the raw wrapper template string (compiled later with `children`/`layout`/`metadata` in scope), `(template, props_dict)`, a props dict alone (passthrough `<slot />` shell), or `None`.
 - Do not assume `StateManager` survives across requests unless `request.state.session` is explicitly bridged from `request.session`.
-- Route, layout, and component HTML templates must keep exactly one authored top-level parent node so Caspian can inject `pp-component` after component expansion. In source, that parent may be a native HTML element or a single imported `x-*` component tag, but it must resolve to one final HTML root. Keep any owned PulsePoint script inside that same parent, and keep top-of-file `<!-- @import ... -->` directives above it.
+- Route, layout, and component templates must keep exactly one authored top-level parent node so Caspian can inject `pp-component` after component expansion. In source, that parent may be a native HTML element or a single imported `x-*` component tag, but it must resolve to one final HTML root. Keep any owned PulsePoint script inside that same parent.
 
 ## BrowserSync URL Source Of Truth
 
@@ -113,8 +113,8 @@ This is the top architectural requirement for this workspace. Treat it as a hard
 - Do not move normal file upload or file-manager behavior into `main.py`; keep those actions in the owning route `index.py` and shared helpers in `src/lib/**`.
 - Document route param behavior exactly as implemented here.
 - Do not use `main.py` alone to infer whether optional features are enabled; confirm that in `caspian.config.json` first.
-- Before changing WebSocket behavior, verify `cfg.websocket`, the app's endpoint registration, the `authorize_websocket(...)` guard in `src/lib/websocket/websocket_security.py`, idle timeout, maximum message size, close codes, and connection cleanup. HTTP-only middleware does not automatically protect `scope["type"] == "websocket"` connections, so socket auth lives in that guard, not `AuthMiddleware`.
-- Authorize sockets with the single `authorize_websocket(...)` guard, which runs the origin check then delegates to Caspian `Auth` (`Auth.set_request(websocket)` + `is_authenticated`/`get_payload`/`check_role`). Add channels by calling that guard with `require_auth=`/`roles=`; do not re-implement session/`exp`/payload parsing per endpoint. Keep authenticated and guest broadcast pools separate, and treat the socket session as read-only.
+- Before changing WebSocket behavior, verify `cfg.websocket`, the single named-socket endpoint in `main.py` (`SOCKET_PATH`, `/__pulsepoint/ws`), and the layer in `src/lib/websocket/sockets.py`: auth delegation, idle timeout, message-size limit, per-connection message rate, connection cap, and the error-frame-then-close failure shape. HTTP-only middleware does not automatically protect `scope["type"] == "websocket"` connections, so socket auth lives in that layer, not `AuthMiddleware`.
+- Add live channels as `@socket()` functions consumed by `pp.socket(...)`, gating each with `require_auth=`/`allowed_roles=` (delegated to Caspian `Auth` via `Auth.set_request(websocket)` + `is_authenticated`/`get_payload`/`check_role`). Do not re-implement session/`exp`/payload parsing per endpoint, and do not reintroduce the removed public/private channel endpoints, `authorize_websocket(...)`, or `WebSocketConnectionManager`. Keep authenticated and guest traffic in separate `SocketPool`s, and treat the socket session as read-only.
 
 ### `src/lib/**/*.py`
 
@@ -125,21 +125,21 @@ This is the top architectural requirement for this workspace. Treat it as a hard
 - When `caspian.config.json` has `mcp: true`, keep app-owned MCP tools in `src/lib/mcp/mcp_server.py` and keep the default FastMCP config in `src/lib/mcp/fastmcp.json`. If those locations change, update `settings/restart-mcp.ts` and the MCP docs together.
 - Keep auth policy in `src/lib/auth/auth_config.py`. Keep auth bootstrap and middleware order changes in `main.py`.
 - Do not recreate or customize `src/lib/security/runtime_security.py` for normal application work. Runtime security helpers are package-owned in `casp.runtime_security`; app-specific policy should live in app-owned config or route/helper code instead.
-- Keep reusable WebSocket helpers under `src/lib/websocket/**` when they are shared across socket endpoints or route clients. Common shared helpers include the `authorize_websocket(...)` guard (origin + `Auth`-delegated auth), origin utilities, connection managers, payload normalization, and broadcast fan-out.
+- Keep the named-socket layer in `src/lib/websocket/sockets.py`: the `@socket()` registry, `Socket`/`SocketSender`/`SocketPool`, the endpoint handler, and the handshake security (origin check, connection ceiling). Sockets shared by several routes also live under `src/lib/websocket/**`; route-owned sockets stay in the route's `index.py`.
 
 ### `src/components/**/*.py`
 
 - Keep `src/components/` as the default home for reusable application UI components and for the page chunks produced by component-first composition (top menus, sidebars, headers, content sections, cards, lists, forms, footers).
 - Move shared cards, forms, shells, navigation, and other reusable rendered building blocks here once they are used across routes or features.
 - Keep route-owned markup in `src/app/**`, and keep non-UI helpers or services in `src/lib/**`.
-- Author components as a single Python file with inline `html(...)` by default for small and medium UI, or as a `.py` plus same-name `.html` via `render_html(...)` for large markup or long scripts. Keep the single-root rule in both forms. Resolve child `x-*` tags from real Python imports in single-file components rather than `<!-- @import ... -->`. Prefer one focused component per file unless a file intentionally exports tiny, tightly coupled subcomponents. See `node_modules/caspian-utils/dist/docs/components.md`.
+- Author every component as a single Python file with inline `html(...)`. Keep the single-root rule. Resolve child `x-*` tags from real Python imports. Prefer one focused component per file unless a file intentionally exports tiny, tightly coupled subcomponents. See `node_modules/caspian-utils/dist/docs/components.md`.
 
 ### `tests/**/*.py` and `settings/check.py`
 
 - This is the app's own testing and static-analysis layer, added on top of Caspian; the framework ships no test runner, so treat it as a workspace convention documented here and in `AGENTS.md`, not as a packaged Caspian feature.
 - Run the whole gate with the single command `npm run check` (or `uv run python settings/check.py`). It runs `pyright` (type check), `ruff` (lint), and `pytest` (tests) against `main.py`, `src/**`, and `settings/*.py`, prints each problem as `path:line:col [tool:code] message`, and exits non-zero when any check fails. For debugging one tool, use `uv run python settings/check.py --only pyright` (or `ruff` / `pytest`).
 - `npm run check` only reports. Auto-fix with `npm run check:fix`, which runs `settings/fix.py` (safe ruff fixes, then the gate). pyright and pytest failures are never auto-fixed.
-- Unused-import (`F401`) removal is handled carefully because component imports look unused to ruff. Single-file components import children used only as `<x-*>` tags in `html(...)`/`render_html(...)` templates (`from .Dialog import DialogContent` → `<x-dialog-content>`); ruff cannot see that, and Caspian resolves the tag from module globals at render time, so deleting the import breaks rendering. Two layers keep it safe: `F401` is `unfixable` in `[tool.ruff.lint]` so a raw `ruff check --fix` never deletes any import; and `settings/fix.py` removes dead imports only from files that contain no `<x-*>`-tag import (component-guarded files are skipped whole and left for the gate). `settings/check.py` likewise suppresses the `F401` reports whose symbol is used as an `x-{camel_to_kebab(name)}` tag, so the gate fails only on genuinely dead imports. The tag detection is shared in `settings/_component_imports.py`. Do not blanket-ignore `F401` or re-enable its autofix globally. See `node_modules/caspian-utils/dist/docs/testing.md`.
+- Unused-import (`F401`) removal is handled carefully because component imports look unused to ruff. Single-file components import children used only as `<x-*>` tags in `html(...)` templates (`from .Dialog import DialogContent` → `<x-dialog-content>`); ruff cannot see that, and Caspian resolves the tag from module globals at render time, so deleting the import breaks rendering. Two layers keep it safe: `F401` is `unfixable` in `[tool.ruff.lint]` so a raw `ruff check --fix` never deletes any import; and `settings/fix.py` removes dead imports only from files that contain no `<x-*>`-tag import (component-guarded files are skipped whole and left for the gate). `settings/check.py` likewise suppresses the `F401` reports whose symbol is used as an `x-{camel_to_kebab(name)}` tag, so the gate fails only on genuinely dead imports. The tag detection is shared in `settings/_component_imports.py`. Do not blanket-ignore `F401` or re-enable its autofix globally. See `node_modules/caspian-utils/dist/docs/testing.md`.
 - Keep tests in `tests/` app-focused: `main.py` helpers and route behavior (via `starlette.testclient.TestClient` against `main.app`), and `src/lib/**` policy such as `auth_config.py`. Do not test framework internals under `.venv/Lib/site-packages/casp/**`.
 - `tests/conftest.py` puts the project root on `sys.path` and sets safe dev env defaults (`APP_ENV`, `AUTH_SECRET`) so importing `main` never fails during tests; extend it rather than duplicating that setup per test file.
 - When adding or changing app-owned Python, add or extend the matching test and keep `npm run check` green before finishing. New tests follow `tests/test_*.py`.
@@ -171,12 +171,12 @@ This is the top architectural requirement for this workspace. Treat it as a hard
 ### `public/js/main.js`
 
 - Treat `public/js/main.js` as the thin browser bootstrap entry point.
-- Keep it minimal and point it at the runtime shipped in `public/js/pp-reactive-v2.js`.
+- Keep it minimal and point it at the runtime shipped in `public/js/pp-reactive-v2.min.js`.
 - Do not duplicate PulsePoint runtime logic here.
 
-### `public/js/pp-reactive-v2.js`
+### `public/js/pp-reactive-v2.min.js`
 
-- Treat `public/js/pp-reactive-v2.js` as the browser-side PulsePoint runtime source of truth for component execution, hooks, refs, directives, SPA navigation, and `pp.rpc(...)` behavior.
+- Treat `public/js/pp-reactive-v2.min.js` as the browser-side PulsePoint runtime source of truth for component execution, hooks, refs, directives, SPA navigation, scroll restoration, `pp.rpc(...)`, and `pp.socket(...)` behavior. It is the single minified bundle the app ships; anything else under `public/js/` is development-only build output and must never be cited as the runtime.
 - Only the built, minified runtime ships to the application. Do not document, reference, or route AI to a TypeScript authoring tree as if the application consumed it.
 - Preserve the current public runtime contract unless the task explicitly changes Caspian frontend behavior.
 - At runtime, component logic is discovered from a plain, untyped `<script>` inside each `pp-component` root. PulsePoint captures the source before materialization or morph insertion, prevents native execution, and evaluates it in component scope.
@@ -184,11 +184,10 @@ This is the top architectural requirement for this workspace. Treat it as a hard
 
 ### `src/app/**/*.html`
 
-- Compose pages from components first (see "Component-First Page Composition"). Keep `index.html` a short assembly of `x-*` chunk components (top menu, sidebar, content sections, cards, forms, footer, and other repeated blocks) instead of a long inline HTML body. When a route would carry a long stretch of markup, move that markup into a single-file `html(...)` component and render it as an `x-*` tag here.
+- Compose pages from components first (see "Component-First Page Composition"). Keep the page template a short assembly of `x-*` chunk components (top menu, sidebar, content sections, cards, forms, footer, and other repeated blocks) instead of a long inline HTML body. When a route would carry a long stretch of markup, move that markup into a single-file `html(...)` component and render it as an `x-*` tag here.
 - Keep route templates and layouts server-rendered first, with PulsePoint enhancement as the default interactive layer.
-- Keep visible page and layout markup in `index.html` and `layout.html`. Treat `index.py` and `layout.py` as backend companions for metadata, `page()` or `layout()`, `@rpc()` actions, auth checks, caching, redirects, and other server-side preparation, not as places to author visible HTML.
-- When a route renders UI, author that markup in the route's `index.html` even if the route also has an `index.py` companion.
-- When route templates import reusable Python components, render them as kebab-cased `x-*` tags such as `<x-button />` after top-of-file `<!-- @import Button from "..." -->` directives. The import comments belong above the single route root, not inside it.
+- The page markup lives inline in `index.py` (returned from `page()` via `html(...)`) and the layout template lives inline in `layout.py` (returned from `layout()`). The same modules own metadata, `@rpc()` actions, auth checks, caching, and redirects.
+- When route templates render reusable Python components as kebab-cased `x-*` tags such as `<x-button />`, import those components with Python imports at the top of the module.
 - For route-level reactivity, prefer PulsePoint state, effects, refs, and template directives together with `pp.rpc(...)` instead of manual DOM mutation or ad hoc browser fetch code.
 - For route-level buttons, forms, inputs, toggles, menus, filters, uploads, and list updates, bind events directly in the authored HTML with native PulsePoint-handled `on*` attributes such as `onclick`, `oninput`, `onchange`, and `onsubmit`. Avoid id-driven `querySelector`/`addEventListener` setup for first-party UI because it duplicates the PulsePoint event and rerender model.
 - For simple route-level form submissions, collect the submitted fields with `Object.fromEntries(new FormData(event.currentTarget).entries())` inside the `onsubmit` handler and pass that object directly to `pp.rpc(...)`. Use `pp.state(...)` for pending/error/success UI and controlled non-native widgets; use `pp-ref` only when the handler needs imperative element access such as focus, measurement, file input reset, or third-party integration.
@@ -196,7 +195,7 @@ This is the top architectural requirement for this workspace. Treat it as a hard
 - Do not author `pp-component="..."` manually in route or layout templates; the Python render pipeline injects it onto the single root element.
 - Use a plain `<script>` inside the single route or layout root when it owns PulsePoint logic; no custom script type is required.
 - Keep authored route and layout templates to exactly one top-level parent node, the same constraint used for component templates. In source, that parent may be a native HTML element or a single imported `x-*` component tag. If a script is needed, keep it inside that parent instead of as a sibling top-level node. AI must follow this the same way React components return one parent node, otherwise Caspian raises `must have exactly one top-level HTML element so Caspian can inject pp-component`.
-- For dashboard, admin, or grouped sections with multiple child routes, prefer folder-level `layout.html` wrappers in `src/app/**` instead of repeating the same shell in each child route.
+- For dashboard, admin, or grouped sections with multiple child routes, prefer folder-level `layout.py` wrappers in `src/app/**` instead of repeating the same shell in each child route.
 - For grouped shells with independent sidebar and content scrolling, mark the content pane with `pp-reset-scroll="true"` when that pane should start at the top on each child-route navigation. Do not put the attribute on the whole shell when the sidebar or rail should retain its own scroll.
 - For upload managers and similar interactive lists, prefer `pp.state(...)` plus `pp-for` over manual DOM painting so rerenders keep the list stable.
 - For route-owned WebSocket clients, use PulsePoint state, refs, and cleanup effects around the native `WebSocket`. Keep the socket object in `pp.ref(...)`, close it on component disposal, and keep socket event listeners inside the owning route template script.
@@ -232,7 +231,7 @@ This is the top architectural requirement for this workspace. Treat it as a hard
 
 - These files are the packaged Caspian documentation layer, not the runtime and not the source of current workspace state.
 - Use them to help AI answer three questions: which Caspian feature applies, which project files should be inspected next, and which workflow is appropriate once the feature is confirmed as enabled.
-- Use `node_modules/caspian-utils/dist/docs/file-conventions.md` when deciding what belongs in `index.html`, `index.py`, `layout.html`, `layout.py`, `loading.html`, `not-found.html`, or `error.html`.
+- Use `node_modules/caspian-utils/dist/docs/file-conventions.md` when deciding what belongs in `index.py`, `layout.py`, `loading.html`, `not-found.html`, or `error.html`.
 - Use `node_modules/caspian-utils/dist/docs/websockets.md` when deciding how to document or implement app-owned FastAPI WebSockets, browser `WebSocket` clients, origin checks, auth/session checks, message contracts, and the choice between WebSockets, RPC, and SSE.
 - Verify behavior claims in this order:
   1.  `caspian.config.json`, then `main.py`, `src/lib/**`, `public/js/**`, `prisma/**`, `src/app/**`