caspian-utils 0.2.4 → 0.2.6

package/dist/docs/pulsepoint.md

@@ -1,6 +1,6 @@
 ---
 title: PulsePoint Runtime Guide
-description: Use this page when the task mentions PulsePoint, performance, rerenders, slow inputs or searches, `pp.state`, `pp.ref`, `pp.effect`, `pp-ref`, `pp-style`, `pp-for`, portals, `pp-reset-scroll`, SPA navigation, or `public/js/pp-reactive-v2.js`. Read "PulsePoint Is Not JSX" before writing templates and "High-performance authoring" before changing runtime reconciliation.
+description: Use this page when the task mentions PulsePoint, performance, rerenders, slow inputs or searches, `pp.state`, `pp.ref`, `pp.effect`, `pp-ref`, `pp-style`, `pp-for`, portals, `pp-reset-scroll`, SPA navigation, or `public/js/pp-reactive-v2.js`. Read "PulsePoint Is Not JSX" before writing templates and "High-performance authoring" before changing runtime reconciliation.
 related:
   title: Related docs
   description: Read the components, routing, data-fetching, and project-structure docs alongside the PulsePoint runtime contract.
@@ -771,172 +771,308 @@ Behavior to rely on:
 - 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.
 
-## High-performance authoring
-
-PulsePoint renders synchronously when a component requests an update. That makes state ownership and component boundaries part of the performance contract: the runtime can optimize reconciliation, but it cannot decide that an authored state change was unnecessary.
-
-### State means "render required"
-
-Use `pp.state(...)` when changing the value must affect at least one render-facing behavior:
-
-- template text, attributes, lists, or conditional visibility
-- a bound child prop or provided context value
-- a memo, effect, or other render dependency that must follow the value
-- authoritative data returned from an RPC call
-
-Use `pp.ref(...)` when a mutable value must persist but changing it should not render:
-
-- debounce and timeout handles
-- request generations or stale-response tokens
-- pagination cursors that are not displayed
-- previous values and imperative integration handles
-- transient search text used only to build a later RPC payload
-
-A ref mutation is intentionally invisible to the template. Do not replace state with a ref when the UI is expected to update.
-
-### Debounce frequency and render cost are different
-
-A debounce answers "how often should this work start?" It does not answer "how much work happens when it starts?"
-
-This shape can still stall a large owner:
-
-```html
-<script>
-  const [query, setQuery] = pp.state("");
-
-  function onSearch(value) {
-    clearTimeout(onSearch.timer);
-    onSearch.timer = setTimeout(() => setQuery(value), 300);
-  }
-
-  pp.effect(() => {
-    loadRows(query);
-  }, [query]);
-</script>
-```
-
-When the timer fires, `setQuery` asks the whole owning component to render even if `query` never appears in its markup. If that owner also contains a large list, dialogs, forms, providers, or many nested components, typing that resumes near the timer can compete with the render.
-
-When query text exists only for an RPC request, keep the query and timer in refs, debounce the request itself, and render only the accepted result:
-
-```html
-<section>
-  <input
-    type="search"
-    placeholder="Search products"
-    oninput="scheduleSearch(event.target.value)"
-  />
-
-  <template pp-for="row in rows">
-    <article key="{row.id}">{row.label}</article>
-  </template>
-
-  <script>
-    const [rows, setRows] = pp.state([]);
-    const query = pp.ref("");
-    const timer = pp.ref(null);
-    const generation = pp.ref(0);
-
-    function scheduleSearch(value) {
-      query.current = value;
-      const requestGeneration = ++generation.current;
-
-      clearTimeout(timer.current);
-      timer.current = setTimeout(
-        () => search(requestGeneration),
-        300
-      );
-    }
-
-    async function search(requestGeneration) {
-      const response = await pp.rpc(
-        "search_products",
-        { query: query.current },
-        { abortPrevious: true }
-      );
-
-      if (requestGeneration !== generation.current) return;
-      setRows(response.items ?? []);
-    }
-
-    pp.effect(
-      () => () => clearTimeout(timer.current),
-      []
-    );
-  </script>
-</section>
-```
-
-The native input remains immediate, timer/query bookkeeping does not render, and only the authoritative rows update the list. The generation check prevents an older response from overwriting a newer search. See [fetch-data.md](./fetch-data.md#search-filters-and-request-races) for the RPC-side rules.
-
-### Keep high-frequency state close to the control
-
-Component boundaries define who owns a render. A keystroke-frequency value should live in the smallest component that needs to render from it.
-
-- Split a search/toolbar from a large result grid when their update frequencies differ.
-- Split frequently edited form state from unrelated dialogs, page shells, and providers.
-- Keep shared state in a parent only when multiple children genuinely need the same render-driving value.
-- Do not create wrapper components that still own all high-frequency state and therefore rerender every subtree.
-
-For a controlled input that genuinely must write state on every keystroke, keep its owner small. If an expensive derived consumer may lag by one commit, use `pp.deferredValue(...)` for that consumer:
-
-```html
-<section>
-  <input value="{query}" oninput="setQuery(event.target.value)" />
-  <x-large-results query="{deferredQuery}" />
-
-  <script>
-    const [query, setQuery] = pp.state("");
-    const deferredQuery = pp.deferredValue(query, "");
-  </script>
-</section>
-```
-
-`pp.deferredValue` is not a substitute for correct ownership, and `pp.transition()` does not time-slice or deprioritize work. PulsePoint remains synchronous.
-
-### Avoid duplicate and invisible commits
-
-Each setter that changes a value requests a render, even when the eventual UI change is small.
-
-- Do not set `loading=true` for a background refresh when existing rows remain visible and no loading indicator changes.
-- Batch related state changes in the same synchronous turn when possible; PulsePoint coalesces scheduled updates.
-- Do not mirror the same value in multiple state hooks.
-- Keep pagination/request cursors in refs when moving the cursor should only start work, then put returned rows and visible metadata in state.
-- Memoize only genuinely expensive derivations or values whose identity matters. `pp.memo` does not make an unnecessary owner render free.
-- Use keyed `pp-for` rows so reconciliation can preserve row identity.
-
-### Diagnose the owner before the runtime
-
-Classify the symptom before editing `public/js/pp-reactive-v2.js`:
-
-| Evidence | Likely classification | First action |
-| --- | --- | --- |
-| A state setter fires, but the changed value is not rendered | Component authoring issue | Move non-rendering bookkeeping to a ref or call the action directly |
-| A debounce fires just before typing stalls | Component/request ownership issue | Debounce the RPC or expensive action, not an unnecessary broad-owner setter |
-| Loading and result setters produce two large commits | Component authoring issue | Remove invisible loading commits or isolate the visible indicator |
-| A high-frequency control owns a large list/provider/dialog subtree | Component-boundary issue | Move the state to a smaller focused component |
-| Rendered HTML is byte-identical but a large stable subtree is still reconciled | Possible runtime issue | Profile runtime phases and verify the stable-DOM case |
-| One small necessary binding change spends disproportionate time in DOM diffing or nested bootstrap | Possible runtime issue | Build a focused reproduction and benchmark before changing reconciliation |
-
-Enable measurements only while profiling:
-
-```html
-<script>
-  pp.enablePerf();
-  pp.resetPerfStats();
-
-  // Reproduce one interaction, then inspect:
-  console.log(pp.getPerfStats());
-
-  pp.disablePerf();
-</script>
-```
-
-Correlate the expensive component and phase with the setter or RPC completion that requested it. Compare the same interaction, DOM size, data, and number of repetitions before and after a change. Input paint timing and RPC latency are separate from render timing, so measure them separately.
-
-Do not "fix" a PulsePoint performance problem with `querySelector`, manual listeners, `innerHTML`, or parallel DOM state. Those bypass ownership instead of correcting it.
-
-## Context
+## High-performance authoring
+
+PulsePoint renders synchronously when a component requests an update. That makes state ownership and component boundaries part of the performance contract: the runtime can optimize reconciliation, but it cannot decide that an authored state change was unnecessary.
+
+### State means "render required"
+
+Use `pp.state(...)` when changing the value must affect at least one render-facing behavior:
+
+- template text, attributes, lists, or conditional visibility
+- a bound child prop or provided context value
+- a memo, effect, or other render dependency that must follow the value
+- authoritative data returned from an RPC call
+
+Use `pp.ref(...)` when a mutable value must persist but changing it should not render:
+
+- debounce and timeout handles
+- request generations or stale-response tokens
+- pagination cursors that are not displayed
+- previous values and imperative integration handles
+- transient search text used only to build a later RPC payload
+
+A ref mutation is intentionally invisible to the template. Do not replace state with a ref when the UI is expected to update.
+
+### Debounce frequency and render cost are different
+
+A debounce answers "how often should this work start?" It does not answer "how much work happens when it starts?"
+
+This shape can still stall a large owner:
+
+```html
+<script>
+  const [query, setQuery] = pp.state("");
+
+  function onSearch(value) {
+    clearTimeout(onSearch.timer);
+    onSearch.timer = setTimeout(() => setQuery(value), 300);
+  }
+
+  pp.effect(() => {
+    loadRows(query);
+  }, [query]);
+</script>
+```
+
+When the timer fires, `setQuery` asks the whole owning component to render even if `query` never appears in its markup. If that owner also contains a large list, dialogs, forms, providers, or many nested components, typing that resumes near the timer can compete with the render.
+
+When query text exists only for an RPC request, keep the query and timer in refs, debounce the request itself, and render only the accepted result:
+
+```html
+<section>
+  <input
+    type="search"
+    placeholder="Search products"
+    oninput="scheduleSearch(event.target.value)"
+  />
+
+  <template pp-for="row in rows">
+    <article key="{row.id}">{row.label}</article>
+  </template>
+
+  <script>
+    const [rows, setRows] = pp.state([]);
+    const query = pp.ref("");
+    const timer = pp.ref(null);
+    const generation = pp.ref(0);
+
+    function scheduleSearch(value) {
+      query.current = value;
+      const requestGeneration = ++generation.current;
+
+      clearTimeout(timer.current);
+      timer.current = setTimeout(
+        () => search(requestGeneration),
+        300
+      );
+    }
+
+    async function search(requestGeneration) {
+      const response = await pp.rpc(
+        "search_products",
+        { query: query.current },
+        { abortPrevious: true }
+      );
+
+      if (requestGeneration !== generation.current) return;
+      setRows(response.items ?? []);
+    }
+
+    pp.effect(
+      () => () => clearTimeout(timer.current),
+      []
+    );
+  </script>
+</section>
+```
+
+The native input remains immediate, timer/query bookkeeping does not render, and only the authoritative rows update the list. The generation check prevents an older response from overwriting a newer search. See [fetch-data.md](./fetch-data.md#search-filters-and-request-races) for the RPC-side rules.
+
+### Keep high-frequency state close to the control
+
+Component boundaries define who owns a render. A keystroke-frequency value should live in the smallest component that needs to render from it.
+
+- Split a search/toolbar from a large result grid when their update frequencies differ.
+- Split frequently edited form state from unrelated dialogs, page shells, and providers.
+- Keep shared state in a parent only when multiple children genuinely need the same render-driving value.
+- Do not create wrapper components that still own all high-frequency state and therefore rerender every subtree.
+
+For a controlled input that genuinely must write state on every keystroke, keep its owner small. If an expensive derived consumer may lag by one commit, use `pp.deferredValue(...)` for that consumer:
+
+```html
+<section>
+  <input value="{query}" oninput="setQuery(event.target.value)" />
+  <x-large-results query="{deferredQuery}" />
+
+  <script>
+    const [query, setQuery] = pp.state("");
+    const deferredQuery = pp.deferredValue(query, "");
+  </script>
+</section>
+```
+
+`pp.deferredValue` is not a substitute for correct ownership, and `pp.transition()` does not time-slice or deprioritize work. PulsePoint remains synchronous.
+
+### Avoid duplicate and invisible commits
+
+Each setter that changes a value requests a render, even when the eventual UI change is small.
+
+- Do not set `loading=true` for a background refresh when existing rows remain visible and no loading indicator changes.
+- Batch related state changes in the same synchronous turn when possible; PulsePoint coalesces scheduled updates.
+- Do not mirror the same value in multiple state hooks.
+- Keep pagination/request cursors in refs when moving the cursor should only start work, then put returned rows and visible metadata in state.
+- Memoize only genuinely expensive derivations or values whose identity matters. `pp.memo` does not make an unnecessary owner render free.
+- Use keyed `pp-for` rows so reconciliation can preserve row identity.
+
+### Keyed rows are reconciled per row, not per list
+
+A render rebuilds the whole component as one HTML string and reconciles it against the live DOM. For a list, that used to mean changing one row cost the same as rebuilding every row: the entire list was re-serialized, re-parsed and re-walked.
+
+The runtime now remembers the markup each keyed row produced. A row that renders byte-identically again is not re-parsed and not re-diffed — its live node is kept, along with its attributes, text and bound handlers. Runs of consecutive unchanged rows collapse together, so a list where a handful of rows changed costs about what those rows cost, largely independent of how long the list is.
+
+This is automatic, but it only engages for rows the runtime can safely stand in for. A row participates when:
+
+- the loop body renders **exactly one root element** per row,
+- that element carries a non-empty, unique `key`,
+- the loop is not nested inside another `pp-for`, and
+- the row's markup contains no nested component boundary, owned slot content, or context provider.
+
+Practical consequences when authoring a large list:
+
+- **Always key rows.** An unkeyed row can never be reused, so an unkeyed list still reconciles in full.
+- **Keep the row body single-rooted.** A loop body with two sibling elements, or with bare text next to the element, opts the whole loop out. Wrap the row in one element.
+- **A row built entirely from a child component** (`<template pp-for="row in rows"><x-row key="{row.id}" … /></template>`) is reconciled the normal way, because the parent is responsible for refreshing that boundary's bound props. Prefer plain markup in the row when the list is large and its rows rarely change.
+- Keep values that feed a row stable. A row whose markup is regenerated identically is free; a row whose markup differs by even one character is full work.
+
+### A mounted child boundary is reconciled by its attributes, not by its markup
+
+The same idea applies to composition, which is the shape most pages actually have: a shell that assembles many `x-*` components rather than one component owning a wall of markup.
+
+A child component's internals belong to the child, so the parent never reconciles into them — it only reconciles the child's root, whose attributes carry the props. Once the child is mounted, the parent therefore emits that root **with an empty body** instead of re-emitting the child's markup, which means a parent render no longer re-serializes and re-parses subtrees it was going to ignore. In a real browser, a shell of 30 small children went from 0.82 ms to about 0.30 ms per parent update, and the cost stopped scaling with how much markup the children contain.
+
+This is automatic and needs no authoring change, but the shape still matters:
+
+- **The first render of a boundary always emits its full markup**, because the child bootstraps from what the parent emitted. A boundary that a conditional removes and later restores starts that cycle again.
+- **A boundary is excluded when the parent is responsible for its content**: owned/slot content (`pp-owner`), a context provider inside it, or a parent-owned `pp-ref` capture inside it. Those keep re-emitting in full.
+- **Props stay live.** Attributes on the boundary root are emitted and reconciled on every render exactly as before, so a child whose props changed still re-renders.
+- **Prefer passing data as props over projecting large slot content** into a frequently re-rendering shell — projected content is re-rendered by its owner, so it does not get this treatment.
+
+If a reused boundary is ever found not to be mounted, the runtime logs `[PP-WARN] Nested boundary content reuse was abandoned…`, permanently disables the reuse for that component, and re-renders it from full markup. Seeing that warning means the cache and the DOM disagreed — report it rather than working around it.
+
+Two related properties follow from the same idea, and they are worth knowing when you reason about what a parent render costs:
+
+- **A bound prop is committed to the child's root only when its value changes.** `active="{selected === 3}"` is evaluated every render, but the attribute is written only on the render where the answer actually flips. The live attribute holds the evaluated value the whole time — it no longer flickers back to the authored `{expr}` text mid-render, so a `MutationObserver` or a CSS transition watching a component root sees only real changes.
+- **A child whose props did not change is not re-walked.** A leaf child costs its parent one prop comparison, not a traversal of its subtree.
+
+Together with the elided body, a mounted child that nothing changed about costs its parent: one prop evaluation per bound attribute, one shallow comparison, and no DOM writes.
+
+### Prop identity decides whether a child re-renders
+
+A child re-renders when its props changed, and props are compared **shallowly, by identity**. Every brace expression on a boundary root is re-evaluated on each parent render, so an expression that *builds* a value returns a new identity every time and the child re-renders even when the data is identical.
+
+This is the single most common cause of "my whole page re-renders when I type one character":
+
+```html
+<!-- Every parent render creates a new array and a new function, so this child
+     re-renders on every parent render even when `products` never changed. -->
+<x-product-table
+  rows="{products.filter((p) => p.active)}"
+  on-select="{(row) => setSelected(row.id)}"
+/>
+```
+
+Give each of them a stable identity, and the child is skipped entirely when nothing it depends on changed:
+
+```html
+<x-product-table
+  rows="{activeProducts}"
+  options="{tableOptions}"
+  on-select="{selectRow}"
+/>
+
+<script>
+  const [products, setProducts] = pp.state([]);
+  const [selected, setSelected] = pp.state(null);
+
+  const activeProducts = pp.memo(
+    () => products.filter((p) => p.active),
+    [products]
+  );
+
+  // Constant for the life of the component.
+  const tableOptions = pp.memo(() => ({ dense: true }), []);
+
+  const selectRow = pp.callback((row) => setSelected(row.id), []);
+</script>
+```
+
+Rules of thumb:
+
+- **Primitives are free.** `label="Total"`, `count="{items.length}"` and `active="{selected === row.id}"` compare by value, so they only "change" when the value really changes. Prefer passing primitives over passing an object the child immediately destructures.
+- **Build object props in the script, never inline in the attribute.** An attribute value that starts with `{{` is read as a server template block, not a PulsePoint binding, so an inline object literal is not valid there — assign it to a name in `<script>` (memoized) and pass that name.
+- **`pp.memo` for derived arrays/objects, `pp.callback` for handlers** passed as props. Both need a dependency array; without one they rebuild every render and nothing is gained.
+- **Do not memoize primitives.** `pp.memo(() => a + b, [a, b])` costs more than the addition.
+- This only matters for values crossing a component boundary. Inside one component's own markup, an inline object or arrow function is harmless.
+
+### Give a provider a stable context value
+
+Context values are compared by identity too, and a provider's consumers are refreshed whenever that identity changes. Providing a freshly built object makes **every consumer in the subtree** re-render on **every** provider render — the widest-blast-radius version of the problem above:
+
+```html
+<!-- Wrong: a new object every render, so all consumers refresh every render. -->
+<script>
+  const [theme, setTheme] = pp.state("light");
+  ThemeContext.Provider({ value: { theme, setTheme } });
+</script>
+```
+
+```html
+<!-- Right: identity changes only when `theme` does. -->
+<script>
+  const [theme, setTheme] = pp.state("light");
+
+  const themeValue = pp.memo(() => ({ theme, setTheme }), [theme]);
+  ThemeContext.Provider({ value: themeValue });
+</script>
+```
+
+Split unrelated values into separate contexts when they change at different rates. A context carrying both a rarely-changing `user` and a per-keystroke `query` forces every `user` consumer to re-render on each keystroke; two contexts keep each consumer tied to what it actually reads.
+
+### Keep effects from doing work nobody asked for
+
+An effect with no dependency array runs after **every** render of its component:
+
+```html
+<script>
+  // Runs on every render, refetching on unrelated state changes.
+  pp.effect(() => { loadRows(page); });
+
+  // Runs only when `page` changes.
+  pp.effect(() => { loadRows(page); }, [page]);
+
+  // Runs once on mount.
+  pp.effect(() => { subscribe(); return () => unsubscribe(); }, []);
+</script>
+```
+
+Dependencies are compared by identity as well, so an object or function rebuilt each render belongs in `pp.memo`/`pp.callback` before it is used as a dependency — otherwise the array never matches and the effect runs every render anyway.
+
+### Diagnose the owner before blaming the runtime
+
+Nearly every "PulsePoint is slow" report is an authoring or ownership problem, and the fix is in the template or the component split — not in the runtime. Classify the symptom first:
+
+| Evidence | Likely classification | First action |
+| --- | --- | --- |
+| A state setter fires, but the changed value is not rendered | Component authoring issue | Move non-rendering bookkeeping to a ref or call the action directly |
+| A debounce fires just before typing stalls | Component/request ownership issue | Debounce the RPC or expensive action, not an unnecessary broad-owner setter |
+| Loading and result setters produce two large commits | Component authoring issue | Remove invisible loading commits or isolate the visible indicator |
+| A high-frequency control owns a large list/provider/dialog subtree | Component-boundary issue | Move the state to a smaller focused component |
+| A child re-renders on every parent render although its visible props look unchanged | Component authoring issue | A prop is a new object/array/function identity each render — see "Prop identity decides whether a child re-renders" |
+| Every context consumer re-renders whenever the provider renders | Component authoring issue | The provided `value` is a fresh object each render — memoize it |
+| Changing one row of a large list costs about as much as changing every row | Component authoring issue | Check the row is keyed, single-rooted, and not a component boundary, so per-row reuse can engage |
+| Rendered HTML is byte-identical but a large stable subtree is still reconciled | Possible runtime issue | Capture `pp.getPerfStats()` for the interaction and report it with the component shape |
+| One small necessary binding change spends disproportionate time in `domDiff` or `bootstrapNested` | Possible runtime issue | Reduce it to the smallest reproducing template, then report it with the phase numbers |
+
+Enable measurements only while profiling:
+
+```html
+<script>
+  pp.enablePerf();
+  pp.resetPerfStats();
+
+  // Reproduce one interaction, then inspect:
+  console.log(pp.getPerfStats());
+
+  pp.disablePerf();
+</script>
+```
+
+Correlate the expensive component and phase with the setter or RPC completion that requested it. Compare the same interaction, DOM size, data, and number of repetitions before and after a change. Input paint timing and RPC latency are separate from render timing, so measure them separately.
+
+Do not "fix" a PulsePoint performance problem with `querySelector`, manual listeners, `innerHTML`, or parallel DOM state. Those bypass ownership instead of correcting it.
+
+## 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`.
 
@@ -957,7 +1093,7 @@ Important:
 - Context is component-level, not directive-based. There is no `pp-context` attribute.
 - `pp.context(token)` resolves from ancestors. A component does not consume the value it provides in the same render.
 - If provider and consumer live in different component script scopes, pass the token through props or store it in shared outer or global state.
-- The preferred authoring style is a lowercase provider tag in the template. The TypeScript runtime's `TemplateCompiler.transformContextProviderTags(...)` recognizes `*.provider` tags case-insensitively and rewrites them to runtime-owned `<pp-context-provider>` boundaries. The runtime context lookup is also case-insensitive, so `<themecontext.provider>` can resolve a script binding named `ThemeContext`.
+- The preferred authoring style is a lowercase provider tag in the template. The runtime recognizes `*.provider` tags case-insensitively and rewrites them to runtime-owned `<pp-context-provider>` boundaries. The context lookup is also case-insensitive, so `<themecontext.provider>` can resolve a script binding named `ThemeContext`.
 - The runtime also supports imperative `ThemeContext.Provider({ value })` calls during render, but that form provides from the component boundary rather than documenting the HTML subtree shape. Use it only when component-wide provision is intended.
 - Do not invent or document `pp.provideContext`. The current runtime explicitly does not expose it.
 
@@ -1318,12 +1454,12 @@ Use these rules when generating or editing PulsePoint runtime code:
 - In authored Caspian templates, do not handwrite `pp-component` or `type="text/pp"`; let the render pipeline inject them.
 - For grouped subtrees, follow the section layout pattern in [routing.md](./routing.md), keep the shared interactive shell in the parent folder's `layout.html`, and keep route-specific PulsePoint code in each child `index.html`.
 - For grouped shells with independent shell and content scrolling, put `pp-reset-scroll="true"` on the content pane rather than the whole shell when only the page content should reset between child-route navigations.
-- Prefer PulsePoint state and template directives over manual DOM mutation for reactive updates.
-- Treat `pp.state(...)` as a request to render. Keep timers, request generations, undisplayed pagination cursors, and transient RPC-only query text in `pp.ref(...)`; do not move a value to a ref when markup or render dependencies must react to it.
-- A debounce limits frequency but does not reduce the cost of the update it eventually runs. For server search, debounce the RPC, discard stale responses, and keep only accepted results in state instead of waking a page-sized owner through an undisplayed query state.
-- Keep high-frequency input state in the smallest useful component boundary. Use `pp.deferredValue(...)` only when an expensive consumer may safely lag one commit, and remember that `pp.transition()` is not concurrent scheduling.
-- Before changing runtime reconciliation, use `pp.enablePerf()` to decide whether the app requested a redundant broad render or stable byte-identical output still incurred disproportionate runtime work.
-- Avoid generating ids, `data-*` state, `querySelector`, `getElementById`, `addEventListener`, manual `innerHTML`, or custom event buses for normal Caspian UI behavior.
+- Prefer PulsePoint state and template directives over manual DOM mutation for reactive updates.
+- Treat `pp.state(...)` as a request to render. Keep timers, request generations, undisplayed pagination cursors, and transient RPC-only query text in `pp.ref(...)`; do not move a value to a ref when markup or render dependencies must react to it.
+- A debounce limits frequency but does not reduce the cost of the update it eventually runs. For server search, debounce the RPC, discard stale responses, and keep only accepted results in state instead of waking a page-sized owner through an undisplayed query state.
+- Keep high-frequency input state in the smallest useful component boundary. Use `pp.deferredValue(...)` only when an expensive consumer may safely lag one commit, and remember that `pp.transition()` is not concurrent scheduling.
+- Before changing runtime reconciliation, use `pp.enablePerf()` to decide whether the app requested a redundant broad render or stable byte-identical output still incurred disproportionate runtime work.
+- Avoid generating ids, `data-*` state, `querySelector`, `getElementById`, `addEventListener`, manual `innerHTML`, or custom event buses for normal Caspian UI behavior.
 - Avoid data-attribute click wiring such as `data-action="save"` plus a delegated listener. Use `onclick="save()"` or `onsubmit="{save(event)}"` in authored HTML and keep reactive state in `pp.state(...)`.
 - If you are explicitly editing raw runtime HTML or internals, keep `pp-component` unique per live instance.
 - In authored templates, use a plain `<script>` inside the root. In runtime HTML, the owned script appears as `script[type="text/pp"]`.
@@ -1386,9 +1522,9 @@ These are current runtime caveats that matter for authors and AI tools:
 - `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.state(...)` changes schedule a component render; `pp.ref(...)` mutations do not. This is an ownership contract, not merely a syntax choice.
-- Debouncing a state setter does not make the resulting render cheaper. A large owner should not hold RPC-only query text, timer handles, request generations, or undisplayed pagination cursors in state.
+- `pp.transition()` does not deprioritize work. PulsePoint renders synchronously; the hook provides an accurate `isPending` flag, not a concurrent scheduler.
+- `pp.state(...)` changes schedule a component render; `pp.ref(...)` mutations do not. This is an ownership contract, not merely a syntax choice.
+- Debouncing a state setter does not make the resulting render cheaper. A large owner should not hold RPC-only query text, timer handles, request generations, or undisplayed pagination cursors in state.
 - `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.

package/package.json

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