caspian-utils 0.1.26 → 0.2.1

package/dist/docs/pulsepoint.md

@@ -1,6 +1,6 @@
 ---
 title: PulsePoint Runtime Guide
-description: Use this page when the task mentions PulsePoint, `pp.state`, `pp.effect`, `pp-ref`, `pp-style`, `pp-for`, portals, `pp-reset-scroll`, SPA navigation, or `public/js/pp-reactive-v2.js`.
+description: Use this page when the task mentions PulsePoint, `pp.state`, `pp.effect`, `pp-ref`, `pp-style`, `pp-for`, portals, `pp-reset-scroll`, SPA navigation, or `public/js/pp-reactive-v2.js`. Read the "PulsePoint Is Not JSX" section before writing any template — PulsePoint borrows React's hook API but its markup is plain HTML, and JSX constructs silently corrupt the page.
 related:
   title: Related docs
   description: Read the components, routing, data-fetching, and project-structure docs alongside the PulsePoint runtime contract.
@@ -20,9 +20,9 @@ This file documents the PulsePoint contract for the shipped Caspian browser runt
 
 If a task involves `pp.state`, `pp.effect`, `pp.layoutEffect`, `pp-ref`, `pp-style`, `pp-spread`, `pp-for`, context, portals, `pp-reset-scroll`, SPA navigation, or component boundary behavior, read this page first and keep generated code aligned with the current Caspian runtime.
 
-Use `components.md` for authoring Python `@component` files, same-name HTML templates, and HTML-first `x-*` component tags. Use this page for the browser-side PulsePoint contract, the authoring rules that feed it, and the React-style mental model used by the shipped runtime.
+Use `components.md` for authoring Python `@component` files, same-name HTML templates, and HTML-first `x-*` component tags. Use this page for the browser-side PulsePoint contract and the authoring rules that feed it.
 
-PulsePoint is the default reactive frontend layer for Caspian. In the current runtime it follows a React-like component pattern, but it is HTML-first rather than JSX-first.
+PulsePoint is the default reactive frontend layer for Caspian. Its **script API** deliberately mirrors React hooks. Its **markup is plain HTML**, compiled by a template compiler that has no JSX support of any kind. Those two facts are independent, and conflating them is the single most common way generated PulsePoint code fails. Read the next section before writing a template.
 
 Do not assume React, Vue, Svelte, JSX, Alpine, HTMX, or older PulsePoint docs unless the task explicitly asks for a different frontend contract.
 
@@ -38,6 +38,93 @@ Apply these before generating any template, even without reading the rest of thi
 6. Call the backend with `pp.rpc(...)` backed by Python `@rpc()` actions; do not invent fetch wrappers or `pp.fetchFunction()`.
 7. `pp-for` goes only on `<template>` with plain `key`; context uses `pp.createContext(...)`, a lowercase `<token.provider>` tag, and `pp.context(token)`.
 8. If an API is not in `public/js/pp-reactive-v2.js`, it does not exist; do not invent hooks, directives, or globals.
+9. **Every brace expression in an attribute must be inside quotes**: `class="{expr}"`, never `class={expr}`. Unquoted braces are shredded by the HTML parser.
+10. **A `{...}` expression produces text, never elements.** There is no JSX. Conditionals use `hidden="{...}"`, lists use `<template pp-for="…">`.
+
+## PulsePoint Is Not JSX
+
+This section exists because the React comparison in this doc, in `components.md`, and in `index.md` has repeatedly been over-read as permission to write JSX. It is not.
+
+**The React comparison is scoped to exactly two things:**
+
+1. The **hook API inside `<script>`** — `pp.state`, `pp.effect`, `pp.memo`, `pp.ref`, dependency arrays, cleanup functions. These behave like their React counterparts.
+2. **Component decomposition** — split a page into small single-responsibility components with props, the way you would split a React tree. This is about *file and responsibility shape*, not syntax.
+
+**The React comparison does not extend to markup — at all.** A Caspian template is an HTML file. It is parsed by an HTML parser first, then compiled. It is never parsed as JavaScript, so JSX expressions in element position are not "unsupported" — they are not even seen as code.
+
+### The JSX constructs that break PulsePoint
+
+Each row is a real failure, not a style preference.
+
+| JSX construct | What actually happens | PulsePoint form |
+|---|---|---|
+| `{cond && (<div>…</div>)}` | The `{cond && (` becomes literal text; the `<div>` becomes a real always-visible element; the `)}` becomes literal text. | `<div hidden="{!cond}">…</div>` |
+| `{cond ? <A/> : <B/>}` | Same — both branches render, plus visible stray text. | Two elements with complementary `hidden` bindings. |
+| `{items.map(i => (<li>{i.name}</li>))}` | The `<li>` renders exactly once with the literal text `{items.map(i => (` before it. | `<template pp-for="item in items"><li key="{item.id}">{item.name}</li></template>` |
+| An unquoted template-literal class, `class={` … `}` | **Silent HTML corruption.** The parser splits the unquoted value on spaces, producing junk attributes like `${b}="" 'a'=""`. The component root fails to compile and the page renders blank. | Quote the whole thing: ``class="{`a ${b}`}"`` |
+| `selected={x === 'y'}` | Same unquoted-attribute corruption, because of the spaces around `===`. | `selected="{x === 'y'}"`, or bind `value` on the `<select>`. |
+| `className=` | Not an HTML attribute. Ignored. | `class=` |
+| `onClick={fn}` | Not a DOM event attribute in HTML (attributes are case-insensitive, so this lands as `onclick` with a JSX value). | `onclick="{fn()}"` |
+| `htmlFor=`, `key={x}` in JSX braces | `htmlFor` is not HTML; `key` is a plain attribute here. | `for=`, `key="{x}"` |
+| `<>…</>` fragments | Parsed as an unknown tag. Also breaks the single-root rule. | One real root element. |
+| `style={{color:'red'}}` | Double-brace object literal is not CSS text. | `pp-style="{'color:red'}"` — a **string**, not an object. |
+| `dangerouslySetInnerHTML` | Does not exist. | Server-render trusted HTML, or use `pp-for` over real data. |
+
+### Why the corruption is silent
+
+`class={...}` and `selected={...}` fail in the parser, not in PulsePoint. The template compiler never gets valid markup, the component root never mounts, and the runtime's reveal step never clears `<body style="opacity: 0">`. The result is a **blank white page with no console error** — the hardest possible failure to diagnose. Quoting the attribute is not cosmetic.
+
+### The one-line test
+
+Before writing a template, ask: *"Would this file be valid HTML if I deleted every `{}` from it?"* If not, it is JSX and it will not work.
+
+## Complete Directive And API Surface
+
+**These lists are closed.** PulsePoint has no other directives, template syntax, or globals. If something is not listed here, it does not exist — do not infer it from React, Vue, Alpine, or another PulsePoint version. Verify against `public/js/pp-reactive-v2.js` when in doubt.
+
+### Author-facing template syntax (the whole list)
+
+| Syntax | Where it goes | Purpose |
+|---|---|---|
+| `{expression}` | Text nodes and **quoted** attribute values | Interpolate a value as text/attribute content |
+| `on*` (`onclick`, `oninput`, `onchange`, `onsubmit`, any native DOM event attribute) | Any element | Event binding |
+| `pp-for="item in items"` / `"(item, index) in items"` | **`<template>` only** | Keyed list rendering |
+| `key="{expr}"` | Repeated sibling inside a `pp-for` template | Keyed diffing identity |
+| `pp-ref="name"` / `pp-ref="{expr}"` | Native elements and `x-*` component tags | Imperative element access |
+| `pp-style="{cssText}"` | Any element | Dynamic inline style, as a **CSS string** |
+| `pp-spread="{...obj}"` | Any element | Spread an object into attributes |
+| `pp-ref-forward` | *Server-set* on component roots — see note below | Ref forwarding through layout-neutral hosts |
+| `<token.provider value="{v}">` (lowercase) | Anywhere in markup | Context provider |
+| `pp-spa="true"` / `pp-spa="false"` | `<body>` enables SPA navigation; `pp-spa="false"` on an `<a>` opts that link out | SPA navigation interception |
+| `pp-reset-scroll="true"` | A scroll container, or `<body>` | Reset that container's scroll on navigation |
+| `pp-scroll-key="stable-name"` | A scroll container | Stable scroll-restoration identity |
+| `pp-loading-content="true"` | The region swapped during navigation | Marks the navigation content region |
+| `pp-loading-url="/route"` | A loading-state element | Route-specific loading lookup |
+| `pp-loading-transition='{"fadeIn":…,"fadeOut":…}'` | The loading region | Navigation fade timings |
+
+There is **no** `pp-if`, `pp-show`, `pp-else`, `pp-model`, `pp-bind`, `pp-class`, `pp-text`, `pp-html`, `pp-on`, or `pp-key`. Conditionals are `hidden="{...}"`; two-way binding is `value="{state}"` plus an `oninput` handler.
+
+### Runtime-managed — never author these
+
+The render pipeline or the browser runtime writes these. Handwriting them corrupts instance tracking:
+
+`pp-component`, `type="text/pp"`, `pp-owner`, `pp-event-owner`, `pp-ref-owner`, `pp-ref-forward`, `pp-context-provider` (the generated tag), `pp-context-token`, `pp-context-value`, `pp-root-layout`, `pp-fragment-root`, `data-pp-ref`, `data-pp-input-value`, `data-pp-default-value`, `data-pp-checked-value`, `data-pp-default-checked`, `data-pp-select-value`, `pp-dynamic-script`, `pp-dynamic-meta`, `pp-dynamic-link`.
+
+`pp-ref-forward` appears in the author-facing table only because you will see it in rendered HTML and in composition components; the server component compiler sets it on a root whose own root is another `x-*` component. Do not write it yourself.
+
+### Component-script hooks (the whole list)
+
+`pp.state`, `pp.effect`, `pp.layoutEffect`, `pp.ref`, `pp.memo`, `pp.callback`, `pp.reducer`, `pp.context`, `pp.portal`, `pp.id`, `pp.errorBoundary`, `pp.syncExternalStore`, `pp.imperativeHandle`, `pp.transition`, `pp.deferredValue`, `pp.optimistic`, plus the `pp.props` bag.
+
+### Runtime utilities (the whole list)
+
+`pp.createContext`, `pp.mount`, `pp.redirect`, `pp.rpc`, `pp.enablePerf`, `pp.disablePerf`, `pp.getPerfStats`, `pp.resetPerfStats`.
+
+React hooks with **no** PulsePoint equivalent: `useContext`-as-a-provider-call, `useInsertionEffect`, `useDebugValue`, `useActionState`, `useFormStatus`, `forwardRef`, `memo()` as a component wrapper, `lazy`, `Suspense`, `startTransition` as a free function. Do not generate them.
+
+### Identifiers injected into event handlers
+
+Inside an `on*` attribute the runtime provides `event`, plus the aliases `e`, `$event`, `target` (→ `event.target`), `currentTarget` and `el` (both → `event.currentTarget`). An alias is skipped when the component scope already declares that name.
 
 ## Source Of Truth
 
@@ -350,6 +437,10 @@ Important:
 - Component scripts are plain JavaScript executed with `new Function(...)`. Do not use `import`, `export`, or top-level `await` inside them.
 - The runtime auto-returns supported top-level bindings from the script. Do not rely on manual `return { ... }` objects.
 - `pp.props` contains the current prop bag for the component.
+- `pp.props` is computed from the **rendered root element's attributes**, not from any server-side signature. A prop that never lands on the root is `undefined` in the browser, with no server error and no console warning. In a Python component this means every prop the template references must be forwarded through `get_attributes({...}, props)`; see [components.md](./components.md#every-prop-a-template-reads-must-be-forwarded-to-the-root).
+- Prop value types depend on how the attribute reaches the root. An unevaluated brace expression such as `volume="{vol}"` is evaluated in the parent component's scope and keeps its real type (number, boolean, object, function). A literal attribute such as `volume="0"` arrives as the **string** `"0"`, so `volume === 0` is false. A valueless attribute arrives as boolean `true`. Coerce or compare loosely when the value may be a server-rendered literal.
+- Attribute names round-trip through kebab-case: `isFullscreen` renders as `is-fullscreen` and returns as `pp.props.isFullscreen`.
+- Attribute names that are JavaScript reserved words are dropped from the prop bag, so `pp.props.class` and `pp.props.for` never exist. Use a non-reserved prop name when the script must read the value.
 - `pp.props.children` contains the root's initial inner HTML before the owned script is removed from the render template.
 - Props are not auto-injected as standalone top-level template or handler variables. Read them through `pp.props` or explicitly destructure them in the component script.
 
@@ -389,7 +480,7 @@ That is the authored form. In browser-inspected runtime HTML, Caspian will alrea
 
 ## Hooks and runtime API
 
-PulsePoint uses a React-style mental model inside each component script: stateful render scope, dependency-based effects, refs, reducer-style updates, context consumption, and portals.
+PulsePoint uses a React-style mental model **inside each component script**: stateful render scope, dependency-based effects, refs, reducer-style updates, context consumption, and portals. That similarity stops at the `<script>` boundary — the surrounding markup is plain HTML, never JSX. See [PulsePoint Is Not JSX](#pulsepoint-is-not-jsx).
 
 Hooks exposed inside component scripts through `pp`:
 
@@ -402,6 +493,13 @@ Hooks exposed inside component scripts through `pp`:
 - `pp.reducer(reducer, initialState)` returns `[state, dispatch]`.
 - `pp.context(token)` resolves a provided context value from ancestor components.
 - `pp.portal(ref, target?)` registers a ref-managed element for portal rendering and returns an object that includes `sourceParent`.
+- `pp.id()` returns a stable, DOM-safe unique id for the life of that hook slot.
+- `pp.syncExternalStore(subscribe, getSnapshot)` subscribes to a mutable source outside PulsePoint and rerenders when its snapshot changes.
+- `pp.imperativeHandle(ref, createHandle, deps?)` publishes an imperative API on a parent-owned ref instead of the raw DOM node.
+- `pp.transition()` returns `[isPending, startTransition]`.
+- `pp.deferredValue(value, initialValue?)` returns a copy of `value` that catches up one commit later.
+- `pp.optimistic(passthrough, reducer?)` returns `[optimisticState, addOptimistic]`.
+- `pp.errorBoundary()` returns `[error, reset]` and marks the component as an error boundary.
 - `pp.props` exposes the current props.
 
 Global helpers exposed through the `pp` singleton and also merged into the component runtime:
@@ -425,6 +523,12 @@ Notes:
 - Older docs may call the RPC helper `pp.fetchFunction()`. In the current bundled runtime the implemented global API is `pp.rpc()`.
 - Keep template-facing bindings at the top level so the AST-based exporter can see them.
 - For predictable code generation, prefer passing an explicit dependency array to `pp.effect`, `pp.layoutEffect`, `pp.memo`, and `pp.callback`.
+- Top-level destructuring is exported to template scope for every form: array patterns, object patterns, nested patterns, defaults, rest elements, and holes. `const [isPending, startTransition] = pp.transition()` and `const [error, reset] = pp.errorBoundary()` reach the template the same way `pp.state` does.
+- `pp.id()` is derived from the component id plus the hook slot, so the same slot keeps its id across rerenders and two instances of the same component never collide. Use it for `id`/`for` pairing and `aria-*` references instead of hand-rolled counters.
+- `pp.syncExternalStore` requires a referentially stable `subscribe`. Wrap it in `pp.callback(..., [])`, otherwise the store is unsubscribed and resubscribed on every render. The runtime re-reads the snapshot immediately after subscribing so a change that lands between render and subscription is not lost.
+- `pp.transition` does not deprioritize rendering the way React's concurrent scheduler does, because PulsePoint renders synchronously. It does give a correct `isPending` flag for both synchronous and promise-returning scopes, which is the common use (disabling a submit button while `pp.rpc()` resolves). Overlapping scopes stay pending until the last one settles.
+- `pp.optimistic` drops its pending actions as soon as `passthrough` changes, which is the point at which the server has confirmed or rejected the guess. Without a reducer, each action replaces the value.
+- `pp.deferredValue` lags by one commit. Use it to keep an input responsive while an expensive derived subtree catches up.
 
 Effect with cleanup and dependencies:
 
@@ -513,6 +617,160 @@ Portal pattern for overlays that must escape clipping ancestors:
 
 `pp.portal(ref)` moves the ref-managed element to `document.body` by default, or to the element passed as the second argument. Portaled content keeps its logical component ancestry, so context, props, and events keep working.
 
+Stable ids for accessible field pairing:
+
+```html
+<div>
+  <label for="{emailId}">Email</label>
+  <input id="{emailId}" type="email" aria-describedby="{hintId}" />
+  <p id="{hintId}">We never share this.</p>
+
+  <script>
+    const emailId = pp.id();
+    const hintId = pp.id();
+  </script>
+</div>
+```
+
+Never derive ids from an index or a module-level counter. `pp.id()` is the only form that stays stable across rerenders and unique across instances of the same component.
+
+External store subscription:
+
+```html
+<section>
+  <p>{isNarrow ? "Compact layout" : "Wide layout"}</p>
+
+  <script>
+    const subscribe = pp.callback((onStoreChange) => {
+      const query = window.matchMedia("(max-width: 640px)");
+      query.addEventListener("change", onStoreChange);
+      return () => query.removeEventListener("change", onStoreChange);
+    }, []);
+
+    const isNarrow = pp.syncExternalStore(
+      subscribe,
+      () => window.matchMedia("(max-width: 640px)").matches
+    );
+  </script>
+</section>
+```
+
+Prefer this over `pp.state` plus `pp.effect` for anything the component does not own. It reads the snapshot during render and closes the gap between render and subscription, which a hand-rolled effect silently drops.
+
+Imperative handle for a child-owned API. The parent passes its own ref down as an ordinary prop:
+
+```html
+<!-- parent -->
+<div>
+  <button onclick="{dialogControl.current.open()}">Open</button>
+  <x-confirm-dialog control-ref="{dialogControl}" />
+
+  <script>
+    const dialogControl = pp.ref(null);
+  </script>
+</div>
+```
+
+```html
+<!-- ConfirmDialog component -->
+<section>
+  <script>
+    const [open, setOpen] = pp.state(false);
+
+    pp.imperativeHandle(
+      pp.props.controlRef,
+      () => ({
+        open: () => setOpen(true),
+        close: () => setOpen(false),
+      }),
+      []
+    );
+  </script>
+
+  <div hidden="{!open}">
+    <button onclick="{setOpen(false)}">Close</button>
+  </div>
+</section>
+```
+
+Notes:
+
+- A prop whose bound expression evaluates to an object is passed through by reference, so `control-ref="{dialogControl}"` arrives as the real ref object on `pp.props.controlRef`.
+- Do **not** author `pp-ref-forward` to make this work. That attribute is runtime-managed, and `pp-ref` on an `x-*` tag binds the child's root DOM node, which is a different feature. Use a normal prop when the parent needs a child-defined API rather than an element.
+- The handle is published in the layout-effect phase and cleared on unmount, so parents should call into it from event handlers or effects, not during their own render.
+
+Optimistic update around an RPC call:
+
+```html
+<section>
+  <button onclick="{addLike()}">Like ({likes})</button>
+
+  <script>
+    const [confirmedLikes, setConfirmedLikes] = pp.state(pp.props.likes ?? 0);
+    const [likes, addOptimisticLike] = pp.optimistic(
+      confirmedLikes,
+      (state, delta) => state + delta
+    );
+
+    async function addLike() {
+      addOptimisticLike(1);
+      const result = await pp.rpc("like_post", { postId: pp.props.postId });
+      setConfirmedLikes(result.likes);
+    }
+  </script>
+</section>
+```
+
+The optimistic `+1` is discarded the moment `confirmedLikes` changes, so the server value never double-counts the guess.
+
+Transition for pending async work:
+
+```html
+<section>
+  <button onclick="{save()}" disabled="{isSaving}">
+    {isSaving ? "Saving..." : "Save"}
+  </button>
+
+  <script>
+    const [isSaving, startSaving] = pp.transition();
+
+    function save() {
+      startSaving(() => pp.rpc("save_profile", { name: pp.props.name }));
+    }
+  </script>
+</section>
+```
+
+### Error boundaries
+
+`pp.errorBoundary()` marks a component as the recovery point for render and effect failures. Without one, a throwing render is logged to the console and leaves the subtree in whatever state it reached.
+
+```html
+<section>
+  <script>
+    const [error, reset] = pp.errorBoundary();
+  </script>
+
+  <div hidden="{!error}">
+    <p>Something went wrong: {error?.message}</p>
+    <button onclick="{reset()}">Try again</button>
+  </div>
+
+  <div hidden="{!!error}">
+    <x-report-chart />
+  </div>
+</section>
+```
+
+Behavior to rely on:
+
+- Errors thrown during a child's render or effects bubble up the logical component ancestry to the nearest boundary. If nothing catches, the runtime logs `[PP-ERROR] Render Cycle Failed` as before.
+- Unlike React, a boundary also catches throws from its **own** render and effects, because in Caspian the boundary and its fallback markup live in the same single-root component.
+- Effect callbacks and effect cleanups take the same path as render failures, so a throwing subscription teardown is not silently swallowed.
+- The boundary **latches**: it keeps holding the error until `reset()` is called.
+- A boundary absorbs at most five errors without an intervening `reset()`, then logs and stops catching. This stops a fallback that itself throws from spinning the render loop. `reset()` re-arms it.
+- Event handler errors are not routed to boundaries. Handle those with `try`/`catch` inside the handler, which matches React.
+
 ## Context
 
 Context is implemented in the current runtime with a React-style provider pattern rather than a legacy `pp.provideContext(...)` helper. Because Caspian templates are HTML-first, authored provider tags should be written in lowercase HTML form, for example `<themecontext.provider>`, even when the JavaScript token is named `ThemeContext`.
@@ -567,11 +825,11 @@ Consumer example for a child component that receives the token through props:
 
 When a child component needs the same token object, pass it from the provider scope as a prop such as `theme-token="{ThemeContext}"`.
 
-## Props and nested components
-
-In Caspian single-file Python components, the root element's attributes must be authored via `get_attributes(...)` and `{{ attributes }}`; see [components.md](./components.md#receiving-props-in-a-python-component). Attributes accepted from an `x-*` tag but not forwarded to the rendered root are dropped and never reach `pp.props`.
-
-- Child component props are derived from DOM attributes.
+## Props and nested components
+
+In Caspian single-file Python components, the root element's attributes must be authored via `get_attributes(...)` and `{{ attributes }}`; see [components.md](./components.md#receiving-props-in-a-python-component). Attributes accepted from an `x-*` tag but not forwarded to the rendered root are dropped and never reach `pp.props`.
+
+- Child component props are derived from DOM attributes.
 - Attribute names are converted from kebab-case to camelCase for the prop bag.
 - Native `on*` attributes and `pp-component` are not included in props.
 - Empty attributes become boolean `true` props.
@@ -591,6 +849,9 @@ Nested components:
 ## Template expressions and attributes
 
 - Use `{expression}` in text nodes and attribute values.
+- **Attribute brace expressions must be quoted.** Write `class="{expr}"`, `disabled="{isSaving}"`, `selected="{role === 'admin'}"`. The unquoted JSX form `class={expr}` is not a PulsePoint syntax variant — it is invalid HTML. An unquoted value ends at the first space, so everything after it is re-parsed as further attribute names, and the element (and usually the whole component root) is destroyed before the compiler ever runs. This is silent: no console error, just a blank page.
+- **An interpolation evaluates to a value, never to markup.** The compiler coerces the result with `String(...)` and HTML-escapes it. Elements cannot come out of an expression, so there is no JSX-style element-returning branch or `.map()`. Use `hidden="{...}"` for conditionals and `<template pp-for="…">` for lists.
+- Objects, functions, and symbols in text position log `[PP-WARN] Invalid template child` and render nothing — that warning usually means JSX-shaped code was attempted.
 - Follow HTML-first attribute naming. Native event attributes are lowercase DOM event attributes (`onclick`, `oninput`, `onsubmit`). Every other attribute on a component boundary is a prop: kebab-case names become camel-cased only inside `pp.props` (`selected-value` becomes `selectedValue`, `open-change` becomes `openChange`, and `on-open-change` becomes `onOpenChange`). A function prop does not need an `on-` prefix; that prefix is only an API naming convention. Use `on-click` when a component intentionally exposes an `onClick` prop, because lowercase `onclick` is reserved for the native DOM event on the boundary element.
 - Pure bindings like `value="{count}"` are evaluated as expressions.
 - For dynamic inline styles in authored templates, prefer `pp-style="{styleText}"` over `style="{styleText}"` so HTML/CSS tooling does not parse the brace expression as raw CSS.
@@ -606,6 +867,7 @@ Nested components:
 - Use `pp-spread="{...attrs}"` to spread an object expression into attributes.
 - `pp-spread` omits nullish values, omits known HTML boolean attributes when their value is `false`, emits them bare when `true`, preserves string-valued `aria-*`/`data-*` booleans, and escapes `&`, `"`, and `<` in emitted attribute values.
 - Use plain `key` for keyed diffing. `pp-key` is not implemented.
+- Only top-level declarations in the component script reach template scope, but every destructuring shape is supported there: `const [a, b] = anyTuple()`, `const [, only] = pair`, `const [first = 1, ...rest] = list`, `const [{ id }] = rows`, and the object-pattern forms. A binding declared inside a block or function is not exported.
 
 Example:
 
@@ -677,6 +939,57 @@ Component example:
 </div>
 ```
 
+## Conditional rendering
+
+PulsePoint has **no conditional directive**. There is no `pp-if`, no `pp-show`, no `pp-else`, and no JSX-style `{cond && (<div/>)}`. Conditional UI is expressed three ways, in this order of preference.
+
+**1. `hidden="{...}"` — the default.** Bind the native boolean attribute. The element stays in the DOM and keeps its state; only its visibility changes.
+
+```html
+<div hidden="{!message}" class="notice">{message}</div>
+
+<div hidden="{!showForm}">
+  <form onsubmit="{submitForm(event)}"> … </form>
+</div>
+```
+
+Notes:
+
+- `hidden` is in the runtime's boolean-attribute set, so a truthy value emits the bare attribute and a falsy value removes it.
+- Under Tailwind's preflight, `[hidden]:where(:not([hidden="until-found"]))` is `display: none !important`, so `hidden` reliably beats a `flex`/`grid`/`block` utility on the same element. **Without Tailwind preflight**, `hidden` is only a UA-stylesheet `display: none` and any `display` rule overrides it — in that case hide with a bound class instead.
+- Because the subtree still exists, guard expressions inside it: use `{deleteTarget?.name}`, not `{deleteTarget.name}`. A hidden element is still rendered, so a throw there still breaks the component.
+
+**2. A ternary inside an interpolation — for text, classes, and attributes.**
+
+```html
+<h3>{editingUser ? 'Edit User' : 'Create User'}</h3>
+<button disabled="{isSaving}">{isSaving ? 'Saving…' : 'Save'}</button>
+<span class="{'badge ' + (user.role === 'admin' ? 'badge-admin' : 'badge-user')}">{user.role}</span>
+```
+
+Template literals work too, as long as the attribute is quoted — the compiler tracks nested braces and quotes: ``class="{`badge ${isAdmin ? 'badge-admin' : ''}`}"``. String concatenation is easier to read and avoids nesting mistakes.
+
+**3. `pp-for` over a 0-or-1 length collection — when the node must truly leave the DOM.** Use this when a hidden subtree would be wrong (an expensive child component, a duplicate form field name, a video that must stop).
+
+```html
+<template pp-for="item in selected ? [selected] : []">
+  <x-detail-panel key="{item.id}" item="{item}" />
+</template>
+```
+
+For an empty-state row, bind `hidden` on the placeholder rather than branching:
+
+```html
+<tbody>
+  <tr hidden="{users.length !== 0}">
+    <td colspan="5">No users found.</td>
+  </tr>
+  <template pp-for="user in users">
+    <tr key="{user.id}">…</tr>
+  </template>
+</tbody>
+```
+
 ## Lists and keyed diffing
 
 - Use `pp-for` only on `<template>`.
@@ -829,6 +1142,7 @@ These are runtime details.
 
 Use these rules when generating or editing PulsePoint runtime code:
 
+- **Write plain HTML, never JSX.** Before finishing any template, verify it would still be valid HTML with every `{}` deleted, that every attribute brace expression is quoted, that conditionals use `hidden="{...}"`, and that lists use `<template pp-for="…">` with `key`. This check catches the highest-frequency generation failure and costs one pass.
 - Treat PulsePoint as the default reactive frontend for Caspian app code.
 - For first-party HTML interactions, use PulsePoint `on*` event attributes, state, refs, effects, directives, and `pp.rpc()` before reaching for DOM APIs.
 - For simple forms, bind `onsubmit` in the authored HTML and read named fields with `Object.fromEntries(new FormData(event.currentTarget).entries())`; do not generate per-input refs or effect-managed submit listeners just to gather values.
@@ -860,6 +1174,19 @@ Use these rules when generating or editing PulsePoint runtime code:
 
 Do not generate these unless the current source explicitly adds support:
 
+JSX constructs in markup — these are the highest-frequency generation failure, so check for them explicitly before finishing a template:
+
+- `{cond && (<element/>)}` or `{cond ? <A/> : <B/>}` element-returning branches — use `hidden="{...}"`
+- `{list.map(item => (<element/>))}` — use `<template pp-for="item in list">`
+- unquoted brace attributes: `class={…}`, `selected={…}`, `value={…}`, `disabled={…}` — always quote: `class="{…}"`
+- `className`, `htmlFor`, `onClick`/`onChange`/`onSubmit` camelCase event props, `defaultValue` as a React prop, `dangerouslySetInnerHTML`
+- `style={{ color: "red" }}` object literals — `pp-style` takes a CSS **string**
+- `<>…</>` fragments, or any second top-level node
+- `key` written as a JSX brace prop outside a quoted attribute
+- imported/returned components as JavaScript values — components are server-side `x-*` tags
+
+Also avoid:
+
 - React, Vue, Svelte, Alpine, HTMX, or JSX-first patterns as the default Caspian frontend approach
 - standard DOM scripting as the default first-party interaction model, including id/data-attribute driven `querySelector(...)`, `addEventListener(...)`, or manual `innerHTML` rendering for normal buttons, forms, filters, toggles, uploads, and reactive lists
 - `pp-context`
@@ -889,6 +1216,12 @@ These are current runtime caveats that matter for authors and AI tools:
 - `pp.context()` resolves through ancestor components, not the current component's own pending providers.
 - `pp.provideContext` is not part of the current runtime API. Use an HTML-first lowercase provider tag such as `<themecontext.provider>`.
 - `pp.portal()` preserves logical ancestry through the registry, so context and prop refresh behavior continue to work through portaled descendants.
+- Top-level array destructuring is exported to template scope for any initializer, not only `pp.state` and `pp.reducer`. A binding declared inside a block or function is still not exported.
+- `pp.transition()` does not deprioritize work. PulsePoint renders synchronously; the hook provides an accurate `isPending` flag, not a concurrent scheduler.
+- `pp.syncExternalStore(...)` resubscribes whenever `subscribe` changes identity, so pass a `pp.callback(..., [])`-wrapped function.
+- `pp.optimistic(...)` clears its pending actions on the render where `passthrough` changes, using a render-phase update rather than an effect, so there is no frame showing stale optimistic output.
+- `pp.errorBoundary()` catches render, effect, and effect-cleanup throws, including the boundary component's own. It does not catch event-handler errors. It latches until `reset()` and stops catching after five captures without a reset.
+- `pp.imperativeHandle(...)` needs the parent's ref passed down as an ordinary prop. `pp-ref` on an `x-*` tag is a different feature that binds the child's root DOM node, and `pp-ref-forward` is runtime-managed and must not be authored.
 
 ## Final reminder
 

package/dist/docs/routing.md

@@ -36,7 +36,7 @@ Start with these rules:
 - In grouped shells with separate shell and content scrolling, put `pp-reset-scroll="true"` on the content pane in `layout.html` when that pane should reset on child-route navigation while the shell sidebar or rail keeps its own scroll.
 - Use `layout.py` when a layout needs shared props or metadata before rendering. The `layout()` function may be synchronous or async.
 - Keep visible route and layout markup in `index.html` and `layout.html`. Treat `index.py` and `layout.py` as backend companions, not as places to author visible HTML.
-- Treat every authored route and layout template like a React component body: it must have exactly one top-level parent HTML element or one imported `x-*` root, and any owned plain `<script>` must live inside that same root.
+- Treat every authored route and layout template like a React component body **for root counting only**: exactly one top-level parent HTML element or one imported `x-*` root, with any owned plain `<script>` inside that same root. The markup itself is plain HTML, never JSX — see [pulsepoint.md](./pulsepoint.md) "PulsePoint Is Not JSX".
 - For route and layout interactivity, use PulsePoint in the authored HTML first: native `on*` event attributes, `pp.state(...)`, refs, effects, directives, and `pp.rpc()`. Do not create standard JavaScript event systems with ids, `data-*` state, `querySelector`, `addEventListener`, or manual `innerHTML` for normal first-party UI.
 
 ## Hard Template Invariant
@@ -189,7 +189,7 @@ Route templates follow the same authored-vs-runtime contract documented in [puls
 
 When a route needs button clicks, form submits, input changes, filters, tabs, menus, uploads, polling, or reactive list updates, author those interactions as PulsePoint behavior in `index.html`. Use `onclick`, `oninput`, `onchange`, `onsubmit`, `pp.state(...)`, `pp-for`, refs, effects, and `pp.rpc(...)` instead of starting with `id` attributes plus `document.querySelector(...)` or `addEventListener(...)`. For simple form submits, prefer `onsubmit="{submitForm(event)}"` and `Object.fromEntries(new FormData(event.currentTarget).entries())` over per-input `pp-ref` payload collection.
 
-For AI-generated route templates, treat `src/app/**/index.html` the same way you would a React component body: return one parent node that contains the entire route markup. This includes any owned script.
+For AI-generated route templates, treat `src/app/**/index.html` the same way you would a React component body **in root count only**: one parent node containing the entire route markup, including any owned script. Inside that root, write plain HTML with PulsePoint directives — `hidden="{...}"` for conditionals, `<template pp-for="…">` for lists, and quoted brace attributes such as `class="{…}"`. JSX shapes (`{cond && <div/>}`, `{list.map(...)}`, `class={...}`) break the render.
 
 Good:
 

package/package.json

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