create-caspian-app 1.0.8 → 1.0.9

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

@@ -59,6 +59,10 @@ This is the top architectural requirement for this workspace. Treat it as a hard
 - Do not treat `token_auto_refresh` as the switch that makes routes private. In the current app it only affects sliding-session refresh if `auth.refresh_session()` is called.
 - Use PulsePoint as the default reactive frontend layer unless the user requests another stack.
 - For first-party Caspian HTML interactivity, use PulsePoint event attributes such as `onclick`, `oninput`, `onsubmit`, state, refs, effects, directives, and `pp.rpc()` before considering standard DOM scripting. Do not start by adding ids, `data-*` wiring, `querySelector`, `getElementById`, `addEventListener`, manual `innerHTML`, or custom client-side state managers for normal reactive UI.
+- Treat render ownership as the first PulsePoint performance decision. Put a value in `pp.state(...)` only when changing it must update markup, a bound child prop/context value, or render-dependent effects. Put non-rendering mutable bookkeeping in `pp.ref(...)`: debounce handles, request/version tokens, pagination cursors, previous values, and transient search text that exists only to build a later RPC payload. A ref mutation does not render and must not be used when the template is expected to update.
+- A debounce controls frequency, not render cost. Do not debounce a setter that wakes a large page owner merely to launch an RPC. Store the latest query in a ref, debounce the RPC call, keep authoritative returned rows in state, and use an incrementing request generation (plus `abortPrevious` when appropriate) so an older response cannot overwrite a newer search. Avoid pre-request state changes such as `setLoading(true)` when they do not change visible UI; each setter is another requested render.
+- Keep high-frequency controls in the smallest component boundary that owns them. Split a search/toolbar or frequently edited form from a large list, dialog collection, provider, or page shell when their state does not need to rerender the whole subtree. For a controlled input that genuinely must update state on every keystroke, keep its owner small and use `pp.deferredValue(...)` for an expensive derived consumer when a one-commit lag is acceptable.
+- Diagnose before editing the PulsePoint runtime. If authored state explicitly changes and the owner rerenders, first remove redundant state, duplicate loading commits, broad ownership, and request races. If rendered HTML is byte-identical yet a stable large subtree is still traversed, or a small necessary binding change causes disproportionate runtime phases, then investigate reconciliation with `pp.enablePerf()`, `pp.resetPerfStats()`, and `pp.getPerfStats()`. `pp.transition()` exposes pending status but does not time-slice or deprioritize rendering. Never work around a performance problem with manual `querySelector`, listeners, or `innerHTML`.
 - For normal forms, treat the HTML submit event as the first choice: bind `onsubmit="{submitForm(event)}"` on the `<form>`, call `event.preventDefault()` in the handler when staying on the page, and build the RPC payload with `Object.fromEntries(new FormData(event.currentTarget).entries())`. Let input `name` attributes define the payload keys and let Python validate, normalize, and decide what to persist. Do not add `pp-ref` to every input or attach an effect-managed submit listener just to build an RPC payload.
 - Treat imperative DOM APIs and `pp-ref` element reads as narrow escape hatches for third-party widgets, browser APIs that require direct DOM access, focus/measurement/media/canvas behavior, or one-off integration code. When they are needed, keep them inside the owning PulsePoint component script, usually behind `pp.ref(...)` and `pp.effect(...)`, so PulsePoint still owns the component state and event flow.
 - When `caspian.config.json` has `tailwindcss: true`, treat Python `merge_classes(...)` plus browser `twMerge(...)` as the only Tailwind class-merging contract: `merge_classes(...)` emits frontend-ready `{twMerge(...)}` expressions, and authored PulsePoint attribute expressions or scripts may call global `twMerge(...)` directly.

package/dist/AGENTS.md

@@ -80,6 +80,7 @@ Use `.github/copilot-instructions.md` for the repo-wide implementation rules. Th
 - In a prop-receiving single-file Python component, `x-*` attributes arrive as raw string kwargs (including unevaluated strings such as `"{permOpen}"`) and do not become browser `pp.props` automatically. Forward every browser-facing prop onto the single native root with `get_attributes({...}, props)`, render `<root {{ attributes }}>`, and pass `attributes=attributes` into `html(...)`. Props accepted by Python but not re-emitted are silently absent from `pp.props`; no server error or browser warning is raised. Remember that forwarded names are real DOM attributes, so avoid unintended native collisions such as `title` when a component-specific name like `user-name` is appropriate. A named Python parameter is consumed out of `**props`, so it is no longer in the passthrough dict and must be listed explicitly in the `get_attributes` defaults. Forwarding also does not preserve types: a brace expression (`volume="{vol}"`) is evaluated in parent scope and keeps its real type, but a literal server value renders as a string, so `volume="0"` makes `volume === 0` false; a valueless attribute becomes `true`; `None`/`False`/`""` are omitted entirely so the prop reads `undefined` rather than `false`; and JS reserved words such as `class` are dropped from `pp.props`. When an icon toggle, `hidden`, or class binding silently does nothing, verify the prop is on the rendered root before debugging the expression. See `node_modules/caspian-utils/dist/docs/components.md` "Receiving Props In A Python Component" and "Every Prop A Template Reads Must Be Forwarded To The Root."
 - For component-to-component composition, use real Python imports inside single-file `html(...)` components instead of placing `<!-- @import ... -->` inside the returned HTML string. A component's own `x-*` tags resolve from the components imported into its Python module, which disambiguates same-name components across directories. Runtime resolution precedence inside a component's output is inherited ancestor components, then the component's own Python imports, then a local `@import` in that same template, but the authoring pattern for single-file components is Python imports. Slot content (children) resolves in the scope where it was authored, so the component that writes an `x-*` tag in markup must import that component.
 - For first-party HTML interactivity in this workspace, PulsePoint is the required default. Use PulsePoint `on*` event attributes, `pp.state`, refs, effects, directives, and `pp.rpc()` instead of inventing id/data-attribute driven JavaScript with `querySelector`, `getElementById`, `addEventListener`, manual `innerHTML`, or parallel client state. For simple forms, bind `onsubmit` in the HTML, convert named fields with `Object.fromEntries(new FormData(event.currentTarget).entries())`, and validate/normalize that payload in Python; do not add `pp-ref` to each input, create a form ref, and attach an effect-managed submit listener just to collect submitted values.
+- For PulsePoint performance work, read `node_modules/caspian-utils/dist/docs/pulsepoint.md` "High-performance authoring" and `fetch-data.md` "Search, filters, and request races" before changing the runtime. Diagnose ownership first: `pp.state` is for values whose change must produce a render (markup, bound props/context, or render-dependent effects); `pp.ref` is for timers, request generations, pagination cursors, and transient query text that should persist without rendering. A debounce delays work but does not make a state update cheap. Keep high-frequency input state in the smallest owning component, do not toggle loading state when that toggle changes no visible UI, discard stale RPC responses, and remember that `pp.transition()` reports pending work but does not provide concurrent rendering. Treat a large component that explicitly requests unnecessary renders as an authoring issue; treat byte-identical output that still traverses a large stable subtree as a possible runtime issue. Never "optimize" either case by replacing PulsePoint with manual DOM wiring.
 - When `caspian.config.json` has `websocket: true`, WebSocket behavior is app-owned in `main.py`. Do not assume fixed route names or endpoint paths across Caspian projects; define project-specific socket paths in the app, keep shared socket helpers in `src/lib/websocket/**` when needed, and let each route that needs a socket client pass its own `websocket_path` or `websocket_url` into its template.
 - WebSocket pages may be public, authenticated, role-gated, or mixed depending on the app. Keep route-specific browser UI in that route's `src/app/**/index.html`, keep first-render socket URL/path values in the matching `index.py`, and keep reusable session/auth/connection/broadcast helpers out of route files only when they are shared.
 - For WebSocket clients, use PulsePoint for component state and lifecycle but native `new WebSocket(...)` for the transport. Keep the socket in `pp.ref(...)`, close it in a cleanup effect, and keep direct socket event listeners inside the owning route template script.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-caspian-app",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "Scaffold a new Caspian project (FastAPI-powered reactive Python framework).",
   "main": "dist/index.js",
   "type": "module",