create-caspian-app 0.4.0-rc.8 → 0.5.0-rc.0

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

@@ -95,6 +95,7 @@ This is the top architectural requirement for this workspace. Treat it as a hard
 ### `main.py`
 
 - Treat `main.py` as the repo source of truth for FastAPI setup, auth bootstrap, middleware wiring, route registration, cache defaults, and error handlers.
+- `main.py` finalizes every rendered page through `finalize_html(...)` = `transform_scripts(...)` then `defer_component_roots(...)`. `defer_component_roots(...)` wraps each outermost `pp-component` root in an inert `<template pp-component>` so the browser never parses raw `{...}` placeholders as live DOM; the PulsePoint `mount()` bootstrap materializes them back before scanning. Because of this deferral, `{...}` is safe in any attribute or position (SVG `d`/`viewBox`/`points`, `src`/`href`, form `value`/date/number/color, table/select text). Do not add per-tag workarounds to dodge browser first-paint validation (static-path `hidden` toggles, `data-*` URL holders, `hidden`-gated `<img src>`, or SSR-resolved initial values). Keep `pp-style` (source-file tooling) and the controlled form-field `value`/`checked`/`defaultvalue`/`<textarea>` rewrites (attribute-vs-property correctness); those exist for reasons deferral does not replace.
 - Treat `main.py` as the source of truth for app-owned WebSocket endpoints, origin validation, idle timeouts, maximum socket message size, JSON message handling, close codes, and broadcast-channel wiring.
 - When the app factors response-header hardening or safe static-file behavior into app-owned helpers, treat `main.py` plus those imported helpers as the runtime source of truth together.
 - Preserve the effective middleware execution order unless the task explicitly changes request semantics: `SecurityHeadersMiddleware -> SessionMiddleware -> CSRFMiddleware -> AuthMiddleware -> RPCMiddleware`.

package/dist/AGENTS.md

@@ -82,6 +82,7 @@ Use `.github/copilot-instructions.md` for the repo-wide implementation rules. Th
 - Before updating docs, verify runtime-specific claims such as middleware order, route param injection, `layout()` behavior, `StateManager` persistence, safe public-file serving, response header, or session-secret behavior against the current `main.py` and installed `casp` package, especially `.venv/Lib/site-packages/casp/runtime_security.py`, rather than copying older notes.
 - When generating or reviewing `src/app/**/index.html`, `src/app/**/layout.html`, or component HTML templates, treat the single-root rule as a hard requirement: exactly one authored top-level parent element or one imported `x-*` root, with any owned `<script>` kept inside that same root. Do not allow sibling top-level tags, sibling scripts, or stray top-level text, because Caspian injects `pp-component` on that final root and errors if it cannot.
 - When generating or reviewing sign-in flows, do not ask the sign-in page to decide redirect targets by re-implementing `next` support or post-login routing. In this stack, redirect behavior is already owned by the Caspian auth runtime plus `src/lib/auth/auth_config.py`; protected-route guest redirects, auth-route redirects, and the default destination are centralized there, with `default_signin_redirect` defaulting to `/dashboard`.
+- Component markup is server-deferred in an inert `<template>`. `main.py` finalizes every page through `finalize_html(...)` = `transform_scripts(...)` then `defer_component_roots(...)`, which wraps each outermost `pp-component` root in `<template pp-component="…">`. The browser never parses/validates/fetches `<template>` contents, so raw `{...}` placeholders never reach live DOM at first paint; the PulsePoint `mount()` bootstrap materializes `template[pp-component]` back into live DOM (via `OwnedTemplateManager.materializeTemplateComponentBoundaries(document.body)`, which also runs on every SPA navigation) before it scans for roots. Because of this, `{...}` is safe in ANY attribute or position — SVG geometry (`d`, `viewBox`, `points`, `transform`), URL attributes (`src`, `srcset`, `href`, `poster`), form `value`/date/number/color, and text placed directly inside `<table>`/`<select>`. Do NOT add per-tag workarounds to dodge browser first-paint validation: no static-path `hidden` toggles just to avoid binding `d`, no `data-*` URL holders, no gating `<img src>` behind `hidden`, and no SSR-resolving an initial value only to prevent a validation flash. Two compiler transforms still apply for different reasons and stay: `pp-style` (so `.html` source-file HTML/CSS tooling does not choke on `style="{...}"`) and the `<input>`/`<select>`/`checked`/`defaultvalue`/`<textarea>` value rewrites (attribute-vs-property correctness for controlled form fields), not first-paint validation.
 
 ## Task Routing
 
@@ -132,4 +133,4 @@ Before merging doc or runtime changes:
 1. Compare the claim or behavior against `main.py`, `src/lib/**`, and `.venv/Lib/site-packages/casp/**`.
 2. Update the matching packaged doc in `node_modules/caspian-utils/dist/docs/` if the running behavior changed.
 3. Update `.github/copilot-instructions.md` if the repo-wide implementation rules changed.
-4. Update this file if the decision order, task routing, workspace clarifications, or packaged-doc maintenance rules changed.
+4. Update this file if the decision order, task routing, workspace clarifications, or packaged-doc maintenance rules changed.

package/dist/main.py

@@ -1,5 +1,6 @@
 from casp.components_compiler import transform_components
 from casp.scripts_type import transform_scripts
+from casp.html_native import parse_fragment, serialize_fragment
 import asyncio
 import inspect
 import os
@@ -214,6 +215,7 @@ async def combined_lifespan(app: FastAPI):
     async with AsyncExitStack() as stack:
         for lifespan in get_app_lifespans():
             await stack.enter_async_context(lifespan(app))
+
         yield
 
 app = FastAPI(
@@ -950,7 +952,7 @@ def register_single_route(url_pattern: str, file_path: str):
             component_compiler=transform_components
         )
 
-        html_output = transform_scripts(html_output)
+        html_output = finalize_html(html_output)
         response = HTMLResponse(content=html_output)
         response.headers['X-PP-Root-Layout'] = root_layout_id
 
@@ -989,6 +991,63 @@ def register_single_route(url_pattern: str, file_path: str):
                       methods=route_methods, name=endpoint)
 
 
+def defer_component_roots(html_output: str) -> str:
+    """Wrap top-level ``[pp-component]`` roots in an inert ``<template>``.
+
+    The browser never parses/validates/fetches the contents of a ``<template>``
+    element, so raw ``{...}`` placeholders inside SVG geometry attributes, form
+    ``value``/date inputs, ``src``/``href`` URLs, or table/select structure no
+    longer trigger console errors, bogus ``404`` requests, value coercion, or
+    HTML foster-parenting before hydration. PulsePoint's ``mount()`` bootstrap
+    materializes ``template[pp-component]`` back into live DOM (reusing the
+    existing ``materializeTemplateComponentBoundaries`` path) before it scans
+    for component roots, so post-hydration behavior is identical to today.
+
+    Only the outermost (non-nested) roots are wrapped; nested component
+    boundaries ride along inside the inert content and become live when the
+    outer template is materialized, so morphing and RPC re-render still operate
+    on live ``[pp-component]`` DOM.
+    """
+    if 'pp-component' not in html_output:
+        return html_output
+
+    soup = parse_fragment(html_output)
+    body = soup.body
+    if body is None:
+        return html_output
+
+    roots = [
+        el for el in body.select('[pp-component]')
+        if el.name != 'template'
+        and not any(
+            parent.has_attr('pp-component') for parent in el.parents
+        )
+    ]
+    if not roots:
+        return html_output
+
+    for root in roots:
+        key = root.get('pp-component')
+        if key is None:
+            continue
+        template = soup.new_tag('template')
+        template['pp-component'] = key
+        root.insert_before(template)
+        template.append(root.extract())
+
+    return serialize_fragment(soup)
+
+
+def finalize_html(html_output: str) -> str:
+    """Final full-document transforms applied just before the response.
+
+    Runs ``transform_scripts`` (author ``<script>`` -> ``type="text/pp"``) then
+    ``defer_component_roots`` so scripts are tagged before they are moved into
+    the inert component ``<template>``.
+    """
+    return defer_component_roots(transform_scripts(html_output))
+
+
 register_routes()
 register_rpc_routes(app)
 
@@ -1019,7 +1078,7 @@ async def custom_404_handler(request: Request, exc: StarletteHTTPException):
                 context_data={'request': request},
                 page_component_source=not_found_path,
                 control_mode=True,
-                transform_fn=transform_scripts
+                transform_fn=finalize_html
             )
             resp = HTMLResponse(content=html_output, status_code=404)
             resp.headers['X-PP-Root-Layout'] = root_layout_id
@@ -1054,7 +1113,7 @@ async def custom_general_exception_handler(request: Request, exc: Exception):
                 context_data=context_data,
                 page_component_source=error_page_path,
                 control_mode=True,
-                transform_fn=transform_scripts
+                transform_fn=finalize_html
             )
             resp = HTMLResponse(content=html_output, status_code=500)
             resp.headers['X-PP-Root-Layout'] = root_layout_id