create-caspian-app 1.1.0 → 1.3.0

package/README.md

@@ -171,9 +171,9 @@ src/app/dashboard/layout.py        ->  wraps every /dashboard/* page
 | ---------------- | ------------------------------------------------------------------------------------------------------------- |
 | `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                                                                                                       |
+| `loading.py`     | Route-scoped navigation loader: synchronous `loading()` returning `html(...)` markup                          |
+| `not_found.py`   | Global 404 page: `page()` returning `html(...)` markup and metadata                                           |
+| `error.py`       | Global 500 page: `page()` receiving safe error context and returning `html(...)` markup                       |
 
 `page()` returns `html(r"""...""", **context)`. It can also return a
 `(page_html, layout_props)` tuple, whose dict keys become `{{ layout.* }}` in a parent layout.
@@ -620,8 +620,9 @@ my-app/
 │   │   ├── layout.py            # Root layout (template + props from layout())
 │   │   ├── index.py             # Home page (markup + logic in one file)
 │   │   ├── globals.css
-│   │   ├── error.html
-│   │   ├── not-found.html
+│   │   ├── error.py             # Global 500 page
+│   │   ├── not_found.py         # Global 404 page
+│   │   ├── dashboard/loading.py # /dashboard navigation loading UI
 │   │   └── users/[id]/
 │   │       └── index.py         # /users/:id
 │   ├── components/              # Reusable UI (@component)

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

@@ -231,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.py`, `layout.py`, `loading.html`, `not-found.html`, or `error.html`.
+- Use `node_modules/caspian-utils/dist/docs/file-conventions.md` for the general special-file model, then verify the completed Python migration in `main.py` and `.venv/Lib/site-packages/casp/**`: navigation loading UI uses `loading.py`, and global fallback pages use `not_found.py` and `error.py`. This app has no authored `.html` special files.
 - 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/**`

package/dist/AGENTS.md

@@ -70,7 +70,7 @@ Use `.github/copilot-instructions.md` for the repo-wide implementation rules. Th
 - Treat `public/` as a URL-root mapping, not a directory registry: an existing `public/icons/app.png` is served as `/icons/app.png` without a per-directory route, mount, or prefix list in `main.py`. `PublicFilesMiddleware` handles only `GET`/`HEAD`, resolves paths beneath `public/`, rejects traversal and symlink escape, and falls through when no file exists. Keep it inside `SecurityHeadersMiddleware` and outside rate limiting, body parsing, sessions, CSRF, auth, RPC, and page routing.
 - Use `node_modules/caspian-utils/dist/docs/pulsepoint-runtime-map.md` when a behavior is controlled by the shipped PulsePoint browser runtime and the task names state, effects, refs, context, portals, directives, `pp.rpc`, uploads, streaming, SPA navigation, or scroll restoration.
 - Use `node_modules/caspian-utils/dist/docs/websockets.md` when the task names WebSockets, live bidirectional channels, socket origin checks, socket auth/session behavior, broadcast managers, or native browser `WebSocket` clients.
-- Use `node_modules/caspian-utils/dist/docs/file-conventions.md` when the task asks what belongs in `index.py`, `layout.py`, `loading.html`, `not-found.html`, or `error.html`.
+- Use `node_modules/caspian-utils/dist/docs/file-conventions.md` for the general special-file model, then verify the completed Python migration in `main.py` and `.venv/Lib/site-packages/casp/**`: routes use `index.py`, layouts use `layout.py`, loading UI uses `loading.py`, and global fallback pages use `not_found.py` and `error.py`. This app has no authored `.html` special files.
 - When `caspian.config.json` has `prisma: true`, database reads and writes from Python routes, layouts, RPC actions, upload flows, auth flows, and helpers must use the generated Prisma Python ORM in `src/lib/prisma/**`. Do not create a separate database fetch layer with raw drivers, hand-written SQL helpers, JSON manifests, app-specific HTTP fetches, or browser-side data fetches to replace the ORM. Use raw SQL only as a narrow Prisma ORM fallback when the generated client cannot express a query clearly.
 - Treat `npx prisma db seed` as a delicate, potentially destructive operation. In this workspace, seed scripts may clear tables before inserting fresh records. Before running that command, an AI agent must propose the exact command, warn that it can delete or overwrite database data including production data if the datasource is wrong, confirm the datasource when practical, and wait for explicit user approval.
 - Component-first page composition is the highest-priority authoring rule for this workspace (see `.github/copilot-instructions.md`). Build pages as a short assembly of `x-*` chunk components (top menu, sidebar, header, content sections, cards, forms, footer) and keep each chunk's long markup inside its own focused single-file `html(...)` component, so the page template in `src/app/**/index.py` stays small instead of holding a wall of HTML. Plan the chunk breakdown before writing the route, not as a later cleanup pass.

package/dist/main.py

@@ -48,7 +48,6 @@ from casp.auth import (
 from casp.rpc import register_rpc_routes, rpc_limiter
 from casp.layout import (
     render_with_nested_layouts,
-    compile_template,
     _finalize_page_region,
     _runtime_injections,
     _runtime_metadata,
@@ -1396,25 +1395,83 @@ if mcp_app is not None:
 # ====
 
 
+async def _render_special_page(
+    page_path: str,
+    request: Request,
+    default_metadata: dict[str, str],
+    context_data: dict[str, Any],
+) -> tuple[str, str]:
+    """Render an app-level Python page through the normal page/layout pipeline."""
+    _runtime_metadata.set(None)
+    _runtime_injections.set({"head": [], "body": []})
+
+    module = load_route_module(page_path)
+    if not hasattr(module, "page"):
+        raise AttributeError(f"Missing 'def page():' in {page_path}")
+
+    signature = get_page_signature(page_path, module.page)
+    accepts_kwargs = any(
+        parameter.kind is inspect.Parameter.VAR_KEYWORD
+        for parameter in signature.parameters.values()
+    )
+    call_context = {"request": request, **context_data}
+    call_kwargs = {
+        name: value
+        for name, value in call_context.items()
+        if accepts_kwargs or name in signature.parameters
+    }
+
+    result = module.page(**call_kwargs)
+    if inspect.isawaitable(result):
+        result = await result
+    if isinstance(result, Response):
+        raise TypeError(f"Special page {page_path} must return markup, not a Response")
+
+    page_layout_props: dict[str, Any] = {}
+    page_content = result
+    if isinstance(result, tuple):
+        page_content = result[0]
+        if len(result) >= 2 and isinstance(result[1], dict):
+            page_layout_props = result[1]
+
+    page_metadata = default_metadata.copy()
+    for metadata_obj in (getattr(module, "metadata", None), _runtime_metadata.get()):
+        if not metadata_obj:
+            continue
+        if metadata_obj.title:
+            page_metadata["title"] = metadata_obj.title
+        if metadata_obj.description:
+            page_metadata["description"] = metadata_obj.description
+        if metadata_obj.extra:
+            page_metadata.update(metadata_obj.extra)
+
+    page_source = getattr(page_content, "source_path", page_path)
+    html_output, root_layout_id = await render_with_nested_layouts(
+        children=str(page_content),
+        route_dir=os.path.dirname(page_path),
+        page_metadata=page_metadata,
+        page_layout_props=page_layout_props,
+        context_data={**call_context, **page_layout_props},
+        page_component_source=page_source,
+        control_mode=True,
+        component_compiler=transform_components,
+    )
+    return finalize_html(html_output), root_layout_id
+
+
 @app.exception_handler(StarletteHTTPException)
 async def custom_404_handler(request: Request, exc: StarletteHTTPException):
     if exc.status_code == 404:
-        not_found_path = os.path.join('src', 'app', 'not-found.html')
+        not_found_path = os.path.join('src', 'app', 'not_found.py')
         if os.path.exists(not_found_path):
-            with open(not_found_path, 'r', encoding='utf-8') as f:
-                content = f.read()
-            html_output, root_layout_id = await render_with_nested_layouts(
-                children=content,
-                route_dir='src/app',
-                page_metadata={
+            html_output, root_layout_id = await _render_special_page(
+                page_path=not_found_path,
+                request=request,
+                default_metadata={
                     'title': "Page Not Found",
                     'description': "The page you are looking for does not exist."
                 },
-                page_layout_props=None,
-                context_data={'request': request},
-                page_component_source=not_found_path,
-                control_mode=True,
-                transform_fn=finalize_html
+                context_data={},
             )
             resp = HTMLResponse(content=html_output, status_code=404)
             resp.headers['X-PP-Root-Layout'] = root_layout_id
@@ -1429,33 +1486,25 @@ async def custom_general_exception_handler(request: Request, exc: Exception):
     error_message = _client_error_message(exc)
     error_trace = full_trace if not IS_PRODUCTION else None
 
-    error_page_path = os.path.join('src', 'app', 'error.html')
+    error_page_path = os.path.join('src', 'app', 'error.py')
     if os.path.exists(error_page_path):
-        with open(error_page_path, 'r', encoding='utf-8') as f:
-            raw_content = f.read()
         context_data = {'request': request,
                         'error_message': error_message, 'error_trace': error_trace}
         try:
-            rendered_content = compile_template(
-                raw_content).render(**context_data)
-            html_output, root_layout_id = await render_with_nested_layouts(
-                children=rendered_content,
-                route_dir='src/app',
-                page_metadata={
+            html_output, root_layout_id = await _render_special_page(
+                page_path=error_page_path,
+                request=request,
+                default_metadata={
                     'title': 'Application Error',
                     'description': 'An unexpected error occurred.'
                 },
-                page_layout_props=None,
                 context_data=context_data,
-                page_component_source=error_page_path,
-                control_mode=True,
-                transform_fn=finalize_html
             )
             resp = HTMLResponse(content=html_output, status_code=500)
             resp.headers['X-PP-Root-Layout'] = root_layout_id
             return resp
         except Exception as render_exc:
-            print("Error rendering error.html:", render_exc)
+            print("Error rendering error.py:", render_exc)
     return HTMLResponse(
         content=f"<h1>500 - Internal Server Error</h1><p>{error_message}</p>",
         status_code=500

package/dist/src/app/error.py

@@ -0,0 +1,113 @@
+from typing import Optional
+
+from casp.component_decorator import html
+from casp.layout import Metadata
+
+
+metadata = Metadata(
+    title="Application Error",
+    description="An unexpected error occurred.",
+    extra={"robots": "noindex, nofollow"},
+)
+
+
+def page(error_message: str, error_trace: Optional[str] = None):
+    return html(r"""
+<main class="container py-10">
+  <div class="mx-auto max-w-2xl rounded bg-white p-6 shadow-sm">
+    <div class="flex items-start gap-4">
+      <svg class="h-10 w-10 text-red-600"
+           viewBox="0 0 24 24"
+           fill="none"
+           xmlns="http://www.w3.org/2000/svg"
+           aria-hidden="true">
+        <path d="M11.001 2a1 1 0 0 1 .998 0L21 7v9a3 3 0 0 1-3 3H6a3 3 0 0 1-3-3V7l8.001-5z"
+              stroke="currentColor"
+              stroke-width="1.5"
+              stroke-linecap="round"
+              stroke-linejoin="round" />
+        <path d="M12 8v4"
+              stroke="currentColor"
+              stroke-width="1.5"
+              stroke-linecap="round"
+              stroke-linejoin="round" />
+        <path d="M12 16h.01"
+              stroke="currentColor"
+              stroke-width="1.5"
+              stroke-linecap="round"
+              stroke-linejoin="round" />
+      </svg>
+
+      <div class="flex-1">
+        <h1 class="text-2xl font-semibold text-red-600">Something went wrong</h1>
+        <p class="mt-2 text-sm text-gray-600">
+          We're sorry—an unexpected error occurred. Try reloading or return to
+          the homepage.
+        </p>
+        <p class="mt-3 text-sm text-gray-700">{{ error_message }}</p>
+
+        <div class="mt-4 flex flex-wrap gap-2">
+          <a href="/"
+             class="inline-block rounded border border-gray-200 bg-gray-100 px-3 py-1.5 text-sm text-gray-800 hover:bg-gray-200">
+            Home
+          </a>
+          <button class="inline-block rounded bg-blue-600 px-3 py-1.5 text-sm text-white"
+                  onclick="window.location.reload()">
+            Reload
+          </button>
+          {% if error_trace %}
+          <button class="inline-block rounded border border-gray-200 bg-transparent px-3 py-1.5 text-sm text-black"
+                  onclick="setShowTrace(current => !current)">
+            {showTrace ? "Hide details" : "Show details"}
+          </button>
+          {% endif %}
+        </div>
+      </div>
+    </div>
+
+    {% if error_trace %}
+    <section class="mt-4" hidden="{!showTrace}">
+      <div class="mb-2 flex items-center justify-between">
+        <div class="text-xs text-gray-500">Error details (development only)</div>
+        <div class="flex gap-2">
+          <button class="rounded border bg-gray-100 px-2 py-1 text-xs text-black"
+                  onclick="copyTrace()">
+            {traceCopied ? "Copied" : "Copy"}
+          </button>
+          <button class="rounded border bg-gray-100 px-2 py-1 text-xs text-black"
+                  onclick="downloadTrace()">
+            Download
+          </button>
+        </div>
+      </div>
+      <pre pp-ref="{tracePre}"
+           class="overflow-auto rounded bg-gray-100 p-4 text-xs text-black">{{ error_trace }}</pre>
+    </section>
+    {% endif %}
+
+    <script>
+      const [showTrace, setShowTrace] = pp.state(false);
+      const [traceCopied, setTraceCopied] = pp.state(false);
+      const tracePre = pp.ref(null);
+
+      async function copyTrace() {
+        if (!tracePre.current) return;
+        await navigator.clipboard.writeText(tracePre.current.innerText);
+        setTraceCopied(true);
+        setTimeout(() => setTraceCopied(false), 2000);
+      }
+
+      function downloadTrace() {
+        if (!tracePre.current) return;
+        const blob = new Blob([tracePre.current.innerText], { type: "text/plain" });
+        const url = URL.createObjectURL(blob);
+        const link = document.createElement("a");
+        link.href = url;
+        link.download = "error_trace.txt";
+        link.click();
+        URL.revokeObjectURL(url);
+      }
+    </script>
+  </div>
+</main>
+""", error_message=error_message, error_trace=error_trace)

package/dist/src/app/{index.html → index.py}

@@ -1,3 +1,8 @@
+from casp.component_decorator import html
+
+
+def page():
+    return html(r"""
 <div
   class="min-h-screen bg-background text-foreground selection:bg-primary/30 flex flex-col items-center justify-between py-8 md:py-12 px-6 md:px-24 overflow-x-hidden relative"
 >
@@ -157,3 +162,4 @@
     </a>
   </div>
 </div>
+""")

package/dist/src/app/layout.py

@@ -0,0 +1,32 @@
+def layout():
+    return r"""
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{ metadata.title | default("Caspian App") }}</title>
+    <meta
+      name="description"
+      content="{{ metadata.description | default('Powered by Caspian Framework') }}"
+    />
+    {% if metadata.robots %}
+    <meta name="robots" content="{{ metadata.robots }}" />
+    {% endif %}
+    <link rel="icon" href="/favicon.ico" type="image/x-icon" sizes="16x16" />
+    <link href="/css/styles.css" rel="stylesheet" />
+    <script type="module" src="/js/main.js"></script>
+</head>
+
+  <body
+    style="
+      opacity: 0;
+      pointer-events: none;
+      user-select: none;
+      transition: opacity 0.18s ease-out;
+    "
+  >
+    <slot />
+  </body>
+</html>
+"""

package/dist/src/app/{not-found.html → not_found.py}

@@ -1,18 +1,32 @@
-<div class="bg-gray-50 flex h-screen items-center justify-center px-4">
-  <div class="text-center">
-    <h1 class="text-9xl font-black text-gray-200">404</h1>
-
-    <p class="text-2xl font-bold tracking-tight text-gray-900 sm:text-4xl">
-      Uh-oh!
-    </p>
-
-    <p class="mt-4 text-gray-500">We can't find that page.</p>
-
-    <a
-      href="/"
-      class="mt-6 inline-block rounded bg-indigo-600 px-5 py-3 text-sm font-medium text-white hover:bg-indigo-700 focus:outline-none focus:ring"
-    >
-      Go Back Home
-    </a>
-  </div>
-</div>
+from casp.component_decorator import html
+from casp.layout import Metadata
+
+
+metadata = Metadata(
+    title="Page Not Found",
+    description="The page you are looking for does not exist.",
+    extra={"robots": "noindex, nofollow"},
+)
+
+
+def page():
+    return html(r"""
+<main class="flex min-h-screen items-center justify-center bg-gray-50 px-4">
+  <div class="text-center">
+    <h1 class="text-9xl font-black text-gray-200">404</h1>
+
+    <p class="text-2xl font-bold tracking-tight text-gray-900 sm:text-4xl">
+      Uh-oh!
+    </p>
+
+    <p class="mt-4 text-gray-500">We can't find that page.</p>
+
+    <a
+      href="/"
+      class="mt-6 inline-block rounded bg-indigo-600 px-5 py-3 text-sm font-medium text-white hover:bg-indigo-700 focus:outline-none focus:ring"
+    >
+      Go Back Home
+    </a>
+  </div>
+</main>
+""")