@webjsdev/cli 0.10.40 → 0.10.41

package/templates/.agents/skills/webjs/references/client-router-and-streaming.md

@@ -0,0 +1,204 @@
+# Client Router and Streaming
+
+## What This Covers
+
+- The automatic client router (SPA-style partial swaps), how it opts out, and programmatic `navigate()` / `revalidate()`.
+- Link prefetch with device-adaptive defaults.
+- `<webjs-frame>` partial-swap regions (WebJs's Turbo Frames).
+- View Transitions opt-in.
+- `<webjs-stream>` surgical element updates (WebJs's Turbo Streams) and streaming RPC results.
+- `Suspense` page-level streaming and `<webjs-suspense>` component-level streaming.
+- WebSockets (`connectWS`, the `WS` route export, `broadcast()`).
+- The opt-in navigation-loading indicator.
+
+Read this when a task touches client navigation, prefetch, partial-page swaps, streaming, or realtime. For the components that render inside these regions (async render, `renderFallback()`, signals) see `components.md`. For the server actions these features call see `data-and-actions.md`.
+
+## The Client Router
+
+The router auto-enables the moment `@webjsdev/core` loads in the browser, which is any page that ships a component. There is nothing to import or opt into. It intercepts same-origin `<a>` clicks (including inside shadow DOM), fetches the target HTML, and replaces only the inside of the deepest shared layout. Outer header, sidenav, and footer DOM is never re-rendered, so scroll positions, input values, and `<details>` state survive a navigation.
+
+**Opting out.** App-wide with config, or per moment at runtime.
+
+```jsonc
+// package.json
+{ "webjs": { "clientRouter": false } }
+```
+
+```js
+import { disableClientRouter } from '@webjsdev/core';
+disableClientRouter();
+```
+
+Per link, opt out with `data-no-router` (auth flows like `/logout`, OAuth redirects, print views, an experimental route with a different runtime). Cross-origin hrefs, `download`, a non-`_self` target, pure same-page hash jumps, and non-HTML extensions are auto-skipped.
+
+**Programmatic navigation and cache eviction.**
+
+```js
+import { navigate, revalidate } from '@webjsdev/core';
+await navigate('/about');                     // push history
+await navigate('/login', { replace: true });  // replace history
+revalidate('/products/123');                  // evict one URL from the snapshot cache
+revalidate();                                 // clear the entire snapshot cache
+```
+
+The router keeps a URL-keyed snapshot cache (LRU, cap 16) so Back/Forward restores instantly, then refetches in the background. Call `revalidate(path)` after a server action mutates data a cached page depends on. Wire bytes are minimized by an `X-Webjs-Have` header, so the server returns only the divergent layout fragment. Concurrent navigations abort the prior in-flight fetch, and scroll is restored on Back/Forward.
+
+**Error recovery.** A 2xx/3xx swap applies in place, and an HTML error body of any status (a 422 re-rendered form, a 5xx error page) is ALSO applied in place with no reload. For a non-HTML error or a transport failure the router dispatches a cancelable `webjs:navigation-error` on `document` (detail `{ url, status, error }`). Call `preventDefault()` to own recovery, otherwise the router renders a minimal in-place alert into the layout slot.
+
+```ts
+document.addEventListener('webjs:navigation-error', (e) => {
+  e.preventDefault();
+  showToast(`Could not load ${e.detail.url} (status ${e.detail.status})`);
+});
+```
+
+**Form state.** A form submitting through the router gets `aria-busy="true"` for the in-flight duration, plus bubbling `webjs:submit-start` and `webjs:submit-end` (detail `{ form, url, ok }`) events. Style `form[aria-busy="true"]` in pure CSS or listen for the events.
+
+## Link Prefetch
+
+Same-origin in-app links prefetch speculatively so a click resolves from a warm cache. On by default, no per-link opt-in needed. The default strategy is DEVICE-ADAPTIVE, because one strategy cannot serve both input modalities. On a hover-capable fine pointer the default is `intent` (warm on hover/focus after a ~100ms dwell). On touch the default is `viewport` (warm as links settle on-screen), because touch has no hover. Modality is detected with `matchMedia('(hover: hover) and (pointer: fine)')`, never a UA sniff.
+
+Override per link with the `data-prefetch` attribute.
+
+```html
+<a href="/dashboard">adaptive default (intent on pointer, viewport on touch)</a>
+<a href="/dashboard" data-prefetch="intent">hover / focus / touch</a>
+<a href="/dashboard" data-prefetch="render">eager on insert</a>
+<a href="/dashboard" data-prefetch="viewport">on scroll into view</a>
+<a href="/dashboard" data-prefetch="none">never</a>
+```
+
+Next-style aliases work (`true` = `render`, `auto` = `viewport`, `false` = `none`). `viewport` uses an IntersectionObserver at threshold 0.5 with a ~250ms dwell, cancelled the instant a link scrolls back out, so a fast scroll spends no requests. Speculation is bounded by a concurrency cap, in-flight de-dupe, and an LRU + TTL cache, and is disabled entirely under `Save-Data`, `prefers-reduced-data`, or a 2g connection. The guiding rule is snappy but never at the cost of bloating the network tab, so when the two conflict the gate under-fetches.
+
+A prefetch issues a real GET, so any mutating endpoint MUST be a POST or a `<form>` submission (which the router never prefetches), never a GET link. A `webjs:prefetch` event fires on `document` when a fragment lands in the cache.
+
+## `<webjs-frame>` Partial-Swap Regions
+
+`<webjs-frame>` is WebJs's take on Turbo Frames, so most `<turbo-frame>` muscle memory transfers. It is a lazy, URL-addressable region that swaps on its own, driven by a link or form targeting its id, and it ships zero component JS. Use it for a region that loads or refreshes INDEPENDENTLY of a full-page navigation (a marketing widget, tabbed UI, a filtered results panel), which a page or layout cannot express.
+
+```ts
+html`<webjs-frame id="activity">…contents…</webjs-frame>`
+```
+
+On click the router walks `closest('webjs-frame')` from the target. If a frame is found and the response carries a matching `<webjs-frame id>`, the swap is scoped to that frame's children, and the server returns ONLY that subtree.
+
+**External targeting.** A trigger does not have to be nested inside the frame. An `<a>` or `<form>` carrying `data-webjs-frame="<id>"` drives that frame from anywhere (an explicit `data-webjs-frame` wins over the enclosing-frame default). `data-webjs-frame="_top"` is a reserved token forcing a full-page navigation that breaks out of the frame.
+
+**Self-loading.** Give a frame a `src` and it self-fetches (through the same swap path).
+
+```html
+<webjs-frame id="rail" src="/widgets/rail"></webjs-frame>            <!-- eager on connect -->
+<webjs-frame id="comments" src="/posts/42/comments" loading="lazy">  <!-- fetch on viewport entry -->
+  <p>Loading comments...</p>
+</webjs-frame>
+```
+
+A `src`-driven frame is JS-DEPENDENT (the browser does not natively fetch `<webjs-frame src>`), so use it for DEFERRED content where a JS-off placeholder is acceptable. For content that must exist without JS, render it server-side into the frame. A frame's route can itself use `<webjs-suspense>` to stream slow data behind a fallback. Frame events: `webjs:frame-busy` (both edges, `aria-busy` set for free) and a cancelable `webjs:frame-missing` when the response lacks the requested frame.
+
+## View Transitions (opt-in)
+
+The router can wrap a navigation's DOM mutation in the native View Transitions API so a swap cross-fades instead of snapping. It is OFF by default. Opt in with a meta in any page head (re-read per navigation), mirroring Turbo's convention.
+
+```html
+<meta name="view-transition" content="same-origin">
+```
+
+The accepted value is `same-origin`. When enabled it wraps all three swap paths (the layout-marker swap, the `<webjs-frame>` swap, and the full-body fallback). When `startViewTransition` is unavailable the swap runs synchronously with no flash and no throw. To persist a live element (a playing `<audio>`, an open menu) across a swap by node identity, mark it `data-webjs-permanent` and give it an `id`.
+
+## `<webjs-stream>` Surgical Updates
+
+`<webjs-stream>` is WebJs's take on Turbo Streams, and the action set mirrors `<turbo-stream>`. It is the only SINGLE-element update primitive (append one row, remove one item, bump a count, insert a toast), whereas a frame or layout swap redraws a whole region.
+
+```html
+<webjs-stream action="append" target="comments">
+  <template><li>Nice post!</li></template>
+</webjs-stream>
+```
+
+Actions: `append` / `prepend` (child of the target id), `before` / `after` (sibling), `replace` (the target itself), `update` (the target's children), `remove` (no template). A `targets="<css-selector>"` applies to every match. There are two delivery paths sharing one applier. Over HTTP a form submission rides the router with `Accept: text/vnd.webjs-stream.html`, and the server returns a stream only when that Accept is present (JS off gets a normal render, so it stays progressive-enhancement-safe). Over a live channel, `renderStream(message)` applies a server-pushed payload.
+
+```ts
+// app/post/[id]/route.ts
+import { stream, streamResponse, acceptsStream, broadcast } from '@webjsdev/server';
+
+export async function POST(req: Request, { params }) {
+  const comment = await addComment(params.id, await req.formData());
+  const parts = stream.append('comments', `<li>${escapeHtml(comment.text)}</li>`);
+  broadcast(`post:${params.id}`, parts);              // fan out to every viewer
+  if (acceptsStream(req)) return streamResponse(parts);
+  return Response.redirect(`/post/${params.id}`, 303); // no-JS fallback
+}
+```
+
+`stream.*` escapes the target id but NOT the content, so escape any user substring yourself, exactly like an `html` hole.
+
+## Streaming (Suspense and RPC)
+
+**Page-level streaming (`Suspense`).** Pass a promise as `children` to defer a slow region behind a fallback. TTFB is the time to render everything outside the boundary, and the resolved content streams in as a `<template>` when the promise lands.
+
+```js
+import { html, Suspense } from '@webjsdev/core';
+export default function Page() {
+  return html`<h1>Catalogue</h1>
+    ${Suspense({ fallback: html`<p>Loading…</p>`, children: fetchExpensive() })}`;
+}
+```
+
+**Component-level streaming (`<webjs-suspense>`).** An `async render()` component BLOCKS the first byte by default (real data in the first paint). To STREAM a slow component behind a fallback instead, wrap it. Multiple boundaries fetch concurrently, and a throwing component is isolated to its own error state while siblings stream.
+
+```js
+html`<webjs-suspense .fallback=${html`<p>Loading section…</p>`}>
+  <user-profile uid="42"></user-profile>
+</webjs-suspense>`
+```
+
+**Streaming RPC results.** A `'use server'` action that RETURNS a `ReadableStream`, async iterable, or async generator streams its chunks over the single RPC response. Detection is purely on the return value, so no config export is needed. This is the token-stream or progress case consumed imperatively after an interaction.
+
+```ts
+'use server';
+export async function* streamAnswer(prompt: string) {
+  for await (const token of llm.complete(prompt)) yield token;
+}
+// inside a component:
+for await (const token of await streamAnswer(q)) this.text.set(this.text.get() + token);
+```
+
+Back-pressure is respected, and the request `AbortSignal` cancels the source on a client disconnect or a superseded render. A mid-stream throw surfaces as an error from the iterable, so wrap the `for await` in `try/catch`. For a slow region you want behind a fallback on the FIRST paint, use `<webjs-suspense>` instead.
+
+## WebSockets
+
+**Server.** Export `WS` from a `route.{js,ts}` file. In dev the module re-imports per connection, so keep shared state on `globalThis`.
+
+```js
+export function WS(ws, req, { params }) {
+  ws.on('message', (data) => ws.send('echo:' + data));
+  ws.on('close', () => { /* cleanup */ });
+}
+```
+
+**Client.** `connectWS(url, handlers)` from `@webjsdev/core` auto-reconnects with exponential backoff, handles JSON parse/stringify, and queues sends while disconnected.
+
+```js
+import { connectWS, renderStream } from '@webjsdev/core';
+connectWS('/feed', { onMessage: (m) => renderStream(m) });
+```
+
+**Broadcast.** `broadcast(path, data)` from `@webjsdev/server` fans a message to every connected client on that path (single-instance). For multi-instance, add Redis pub/sub yourself, there is no framework magic.
+
+## Navigation-Loading Indicator (opt-in)
+
+For a CSS-only progress affordance while a navigation is in flight, add `data-webjs-nav-progress` to `<html>` once in the root layout. The router then sets `data-navigating` on `<html>` during a nav (deferred 150ms, so quick navs never trigger it). Style off that attribute.
+
+```html
+<html data-webjs-nav-progress>
+```
+
+```css
+html[data-navigating] { cursor: progress; }
+html[data-navigating]::after {
+  content: ''; position: fixed; top: 0; left: 0; right: 0; height: 2px;
+  background: var(--accent); animation: progress 1s ease-in-out infinite;
+}
+```
+
+It is opt-in because toggling an `<html>` attribute re-resolves `oklch()` / `color-mix()` tokens on WebKit (every iOS browser), which flashes the background for one frame on a token-driven theme. Enable it only when your theme does not lean on wide-gamut color tokens, otherwise use the JS path (listen for `webjs:navigate`, and `webjs:submit-start` for forms).

package/templates/.agents/skills/webjs/references/components.md

@@ -0,0 +1,167 @@
+# Components
+
+## What This Covers
+
+- Declaring reactive properties through the `WebComponent({ ... })` factory and `prop()`, with options (`reflect`, `state`, `attribute`, `default`, `converter`, `hasChanged`)
+- Signals as the default state primitive for component-local and shared state
+- The Lit-aligned lifecycle and exactly which hooks SSR runs versus skips
+- Light DOM (default) versus shadow DOM, and the light-host `display: block` rule
+- Slots with full shadow-DOM parity in both DOM modes
+- `async render()`: SSR-blocking first paint, client stale-while-revalidate, `renderFallback()` / `renderError()`
+- Display-only elision (when a component is stripped from the browser)
+- Inherited members app code must NOT shadow (`title`, `remove`, `render`, ...)
+
+Read this when you are authoring or reviewing a `WebComponent`. For styling a component (Tailwind, the tag-prefix rule, host sizing) see `styling.md`. For streaming a slow region or programmatic navigation see `client-router-and-streaming.md`. For Lit habits that break WebJs see `muscle-memory-gotchas.md`.
+
+## Reactive properties: the base-class factory
+
+Reactive properties are declared by passing their shape into `WebComponent({ ... })`. The types flow automatically to `this.<prop>`, so there is NO `static properties` block and NO `declare` line (a `static properties` block throws at runtime, caught by `no-static-properties`).
+
+```ts
+import { WebComponent, prop, html } from '@webjsdev/core';
+
+class Dialog extends WebComponent({
+  open: prop(Boolean, { reflect: true }),                       // reflects to the `open` attribute
+  showClose: prop(Boolean, { attribute: 'show-close-button' }), // custom attribute name
+  variant: prop<'info' | 'danger'>(String, { reflect: true }),  // narrowed union type
+  student: prop<Student>(Object),                               // narrowed object type
+  items: prop<Tag[]>(Array),                                    // array-typed prop uses Array, not Object
+  internal: prop({ state: true }),                             // internal state, no attribute, no type
+}) {
+  constructor() {
+    super();
+    this.open = false;             // set defaults in the constructor, after super()
+    this.student = { name: '', email: '' };
+    this.items = [];
+  }
+  render() {
+    return html`<button ?disabled=${!this.open}>${this.variant}</button>`;
+  }
+}
+Dialog.register('ui-dialog');
+```
+
+The bare form is shorthand: `count: Number` means `prop(Number)`. Use `prop()` to pass options or narrow the TS type.
+
+| Option | Default | Meaning |
+|---|---|---|
+| `type` | `String` | Constructor feeding the default attribute converter |
+| `reflect` | `false` | Property changes write back to the HTML attribute |
+| `state` | `false` | Internal-only. No attribute, not observed |
+| `attribute` | derived from name | The HTML attribute name the property rides |
+| `default` | none | Declarative initial value (a function runs per instance for a fresh object / array) |
+| `hasChanged` | strict `!==` | Custom change detection |
+| `converter` | type-based | Custom attribute-to-property serialization |
+
+For an array-typed prop pass `Array`, not `Object` (`array-prop-uses-array-type` flags the `Object` form). For anything the built-in converters cannot parse (Date, Map, Set) supply a `converter`.
+
+**Never use a class-field declaration OR initializer** (`count = 0`, `student: Student = {...}`, `todos!: Todo[]`). Under `useDefineForClassFields` even a type-only `todos!: Todo[]` compiles to define an own property after `super()`, which clobbers the prototype's reactive accessor and silently breaks reactivity. Only declare props in the factory and read/write them off `this`. The `reactive-props-no-class-field` rule catches this.
+
+## Signals are the default state primitive
+
+Reserve the factory for values that ride an HTML attribute, reflect to one, or arrive via `.prop=${value}` SSR hydration. For everything else use signals.
+
+```ts
+import { signal, computed } from '@webjsdev/core';
+
+const cart = signal<Item[]>([]);                 // module-scope: shared across components, survives navigations
+const count = computed(() => cart.get().length); // derived
+```
+
+Read with `signal.get()` inside `render()`; the built-in `SignalWatcher` tracks the read and re-renders on change. An instance signal created in the constructor is component-local. For a fine-grained DOM swap use `${watch(signal)}` from `@webjsdev/core/directives`.
+
+## Lifecycle (Lit-aligned) and what SSR runs
+
+Each update cycle runs these in order; each receives a `changedProperties` Map.
+
+| # | Hook | When |
+|---|---|---|
+| 1 | `shouldUpdate(changed)` | Return `false` to skip. Default `true`. |
+| 2 | `willUpdate(changed)` | Pre-render. Assignments here fold into THIS cycle. |
+| 3 | `update(changed)` | Default calls `render()` + commits. Override rarely. |
+| 4 | `firstUpdated(changed)` | Once, on the first render only. |
+| 5 | `updated(changed)` | Every commit. Ad-hoc post-render DOM work. |
+| 6 | `updateComplete` resolves | `await el.updateComplete` to read post-render DOM in tests. |
+
+**SSR runs only the value-deriving path**: the constructor, attribute application, `willUpdate` (and controllers' `hostUpdate`), `reflect: true` reflection, then `render()`. It does NOT invoke `connectedCallback`, `disconnectedCallback`, `firstUpdated`, `updated`, `update`'s DOM commit, `hostUpdated`, or `shouldUpdate`. So set first-paint defaults in the constructor, derive SSR-visible state in `willUpdate`, and keep browser-only work (DOM queries, layout, `localStorage`, viewport) in `connectedCallback` / `firstUpdated`. A browser global in the constructor or `render()` throws at SSR (flagged by `no-browser-globals-in-render`; attribute methods and `closest()` are shimmed).
+
+## Light DOM (default) vs shadow DOM
+
+Light DOM is the default: global CSS and Tailwind utilities apply directly, no `:host` or CSS-var plumbing. Set `static shadow = true` only for `static styles = css\`...\`` scoped styles, third-party embed isolation, or the native `::slotted()` selector.
+
+```ts
+class Panel extends WebComponent({ label: String }) {
+  static shadow = true;
+  static styles = css`:host { display: block } .body { padding: 16px }`;
+  render() { return html`<div class="body">${this.label}</div>`; }
+}
+```
+
+- A light-DOM component authoring custom CSS MUST prefix every class selector with its tag name (`.my-card__body` or `my-card .body`). Prefer Tailwind, unique by construction. `static styles` on a light-DOM component is silently ignored.
+- **Never interpolate into a component's `<style>` or `<script>` body** (`html\`<style>${x}</style>\``). The server emits it but the client drops the raw-text hole, so it paints then wipes to empty on hydrate (flagged by `no-interpolation-in-raw-text-element`). Use `static styles` or Tailwind.
+- Light-DOM hosts are marked `display: block` via one low-priority `@layer webjs-host` rule (overridable by any Tailwind utility). Shadow hosts are NOT marked; set `:host { display: block }` in `static styles`. Size the HOST (put `w-full max-w-[...]` on the render root), not only an inner wrapper. See `styling.md`.
+
+## Slots
+
+The full `<slot>` surface works in light DOM with shadow-DOM parity; migrating modes never requires a template rewrite.
+
+```ts
+class MyCard extends WebComponent {
+  render() {
+    return html`
+      <header><slot name="header"></slot></header>
+      <main><slot></slot></main>
+      <footer><slot name="footer">no actions</slot></footer>`;
+  }
+}
+```
+
+Named slots, the default slot (unnamed children, text, comments), fallback content (a slot's inner markup when nothing matches), first-wins resolution, and dynamic `name=${...}` all behave per spec. The DOM API mirrors shadow slots: `assignedNodes` / `assignedElements` (with `{ flatten: true }`), `element.assignedSlot`, and the `slotchange` event. Both modes are SSR'd (light DOM projects into `<slot data-webjs-light data-projection="actual">`, shadow DOM via Declarative Shadow DOM), so slotted content renders with no JS.
+
+A compound child reads its parent at the first server paint via `closest('ui-tabs')` (only tag-name selectors resolve at SSR, and the compound parent must be light DOM). Genuine live-DOM reads (`querySelector`, `classList`, geometry) still throw at SSR, so keep them in `connectedCallback` / `firstUpdated`.
+
+## Async render: first-paint server data
+
+`render()` may be `async`, so a leaf component fetches its own server data into the first paint with no prop-drilling.
+
+```ts
+class UserActivity extends WebComponent({ uid: String }) {
+  renderFallback() { return html`<div class="skeleton h-24"></div>`; } // optional, re-fetch only
+  async render() {
+    const items = await getActivity(this.uid); // 'use server' action: real fn at SSR, RPC stub on client
+    return html`<ul>${items.map((i) => html`<li>${i.label}</li>`)}</ul>`;
+  }
+}
+```
+
+Three decoupled concerns, do not conflate them.
+
+1. **SSR always blocks by default.** The server awaits `async render()`, so the resolved data is baked into the first paint. There is no first-paint fallback, ever (a progressive-enhancement upgrade over a client-fetched `Task`).
+2. **The client re-fetch default is stale-while-revalidate.** When a prop or dependency change re-runs `async render()`, the previous content stays until the new render resolves. No blank, no flash, no user code.
+3. **`renderFallback()` is the OPTIONAL re-fetch loading UI.** Shown ONLY during a client re-fetch, NEVER on first paint, and it does NOT create a server-streaming boundary.
+
+Errors are isolated per component by default (no user code): a thrown `await` renders a component-scoped error state while siblings render, never bubbling to the route `error.ts`. Override `renderError(error)` only to customize it (dev shows the message, prod stays silent).
+
+Decision rules. Use `async render()` for request-time server data that should be in the first paint (the default). Add `renderFallback()` when a client re-fetch's stale content would mislead. Use `Task` / signals for genuinely client-only data (a click, viewport, live updates). For SLOW data where blocking the first byte hurts, wrap the region in `<webjs-suspense .fallback=${html\`Loading...\`}>` to stream it (the only way to show a first-paint fallback; see `client-router-and-streaming.md`). Do NOT fetch in `connectedCallback` for data knowable server-side, and do NOT prop-drill what a leaf can fetch itself.
+
+## Display-only elision
+
+A component that does no client-side work renders the same SSR'd HTML with or without its JS, so WebJs strips its import from the served source (and any vendor reachable only through it). This is automatic and conservative. A component stays elidable while it has NONE of:
+
+- an `@event` binding or native handler property (`.onclick`)
+- a factory-declared reactive property that is not `{ state: true }`
+- an overridden lifecycle hook (including `renderFallback` / `renderError`)
+- an imported `signal` / `computed` / `watch` / `Task` / `ref` / streaming directive, or `addController` / `requestUpdate`
+- code that runs at module load (a top-level call, non-data `new`, dynamic `import(...)`, top-level `await`); only declarations and `X.register(...)` are allowed
+- a rendered `<slot>`, or being rendered by a component that itself ships
+
+A bare `async render()` (no other signal, light DOM) is elided too: the SSR'd data is the complete first paint. Force shipping with `static interactive = true` when interactivity is invisible to static analysis (a dynamically-built tag string, a `:defined` rule in an external stylesheet). `static shadow = true` always ships (Declarative Shadow DOM re-attaches only during parsing). Turn elision off app-wide with `{ "webjs": { "elide": false } }` or `WEBJS_ELIDE=0`.
+
+## Members app code must not shadow
+
+A `WebComponent` inherits `HTMLElement` (browser) or an `ElementShim` (SSR) plus the framework reactivity base. A reactive prop or method whose NAME collides either fails to compile (`TS2415` for a type-incompatible property, `TS2416` for a method signature) or silently hijacks the native member at runtime. The fix is always to rename.
+
+- HTMLElement / Element: `title`, `id`, `slot`, `role`, `hidden`, `dir`, `lang`, `translate`, `draggable`, `tabIndex`, `className`, `dataset`, `remove`, `closest`, `matches`, `focus`, `blur`, `click`, `append` / `prepend`, `before` / `after`. Rename (`postTitle`, `removeItem`, `handleClick`).
+- WebComponent base: `render`, `update`, `requestUpdate`, `updated` / `firstUpdated`, `willUpdate` / `shouldUpdate`, `connectedCallback`, `renderError` / `renderFallback`, `addController` / `removeController`, `updateComplete`. Only override one deliberately, with its exact signature; never repurpose the name for app logic.
+
+Framework-private fields are underscore-prefixed (`_renderRoot`, `_connected`, `_changedProperties`, `_updatePromise`, `_isUpdating`); never declare a prop or field that matches one. Safe, non-inherited names: `label`, `open`, `count`, `value`, `name`, `items`, `todos`, `active`, `variant`, `size`, `checked`, `selected`, `heading`, `message`, `status`. When in doubt, grep the base surface in `node_modules/@webjsdev/core/src/component.js`.

package/templates/.agents/skills/webjs/references/data-and-actions.md

@@ -0,0 +1,187 @@
+# Data and Actions
+
+## What This Covers
+
+- The `modules/<feature>/` architecture (thin `app/` adapters, `actions/` mutations, `queries/` reads, one function per file)
+- `'use server'` RPC actions, the serializer-safe wire, and how a client import becomes a typed stub
+- Input validation at the boundary via `export const validate`
+- HTTP-verb config exports (`method`, `cache`, `tags`, `invalidates`, `middleware`)
+- The `ActionResult<T>` envelope and its robust failure detection
+- The `route()` REST adapter that exposes an action over HTTP
+- Drizzle rc.3 reads (`db.query.*`) and mutations (`.returning()`)
+- Keeping server-only types off the client (`import type` vs a value import)
+
+Read this when a task touches a server mutation, a data read, input validation, a REST endpoint, or the shape a component consumes. Sibling refs: `routing-and-pages.md` (the page `action` write path, `route.ts` handlers), `auth-and-sessions.md` (protecting an action or endpoint), `optimistic-ui.md` (consuming `ActionResult` on the client), `typescript.md` (erasable syntax, full-stack types).
+
+## The Architecture (read this first)
+
+`app/` is routing ONLY: thin adapters that import from `modules/`. Feature logic lives under `modules/<feature>/`.
+
+- `modules/<feature>/actions/*.server.ts` mutations (create, update, delete)
+- `modules/<feature>/queries/*.server.ts` reads
+- `modules/<feature>/components/*.ts` feature-owned components (shared UI goes in top-level `components/`)
+- `modules/<feature>/utils/*.ts` pure helpers (no `'use server'`, no DB)
+- `modules/<feature>/types.ts` browser-safe typedefs (no runtime server import)
+
+**One exported function per action / query file, named after the file.** A configured `.server.ts` file with more than one callable function is a `webjs check` error. App-internal imports use the `#` root alias (`#modules/...`, `#db/...`), not deep `../../../` relatives.
+
+## The `.server.ts` boundary
+
+`.server.ts` is the one server boundary. It is BOTH source protection (the file router never serves the source) AND, with `'use server'`, an RPC mechanism.
+
+| File | `'use server'`? | What it is |
+|---|---|---|
+| `*.server.ts` | yes | Server action. Source-protected AND RPC-callable; the browser import becomes a stub POSTing to `/__webjs/action/<hash>/<fn>`. |
+| `*.server.ts` | no | Server-only utility. Source-protected; the browser import is a throw-at-load stub. |
+| plain `.ts` | yes | Lint violation (`use-server-needs-extension`). Rename to add `.server.`. |
+| plain `.ts` | no | Browser-safe. |
+
+**Importing the action IS the API.** The dev server rewrites a client import into a typed RPC stub, so you write `await createPost({ title })` and never hand-write `fetch()`. REST over HTTP is a `route.ts` that calls the action (below). Never import a no-`'use server'` utility directly into a shipping page / layout / component; its browser stub throws at load. Reach it through a `'use server'` action instead.
+
+## A query and an action
+
+Reads live in `queries/`, mutations in `actions/`. Both are `.server.ts` with `'use server'`, so their browser imports become typed RPC stubs. Args and returns round-trip through the serializer (it carries `Date` / `Map` / `Set` / `BigInt` / `Error` / typed arrays / `Blob` / `File` / `FormData` / cycles), so a query may return a `Date` and the client receives a real `Date`.
+
+```ts
+// modules/posts/queries/list-posts.server.ts
+'use server';
+import { db } from '#db/connection.server.ts';
+export async function listPosts() {
+  return db.query.posts.findMany({
+    where: { published: true },
+    orderBy: { createdAt: 'desc' },
+  });
+}
+```
+
+```ts
+// modules/posts/actions/create-post.server.ts
+'use server';
+import { db } from '#db/connection.server.ts';
+import { posts } from '#db/schema.server.ts';
+export async function createPost(input: { title: string; body: string }) {
+  const title = String(input?.title || '').trim();
+  if (!title) return { success: false, error: 'title required', status: 400 };
+  const [row] = await db.insert(posts).values({ title, body: String(input?.body || '') }).returning();
+  return { success: true, data: row };
+}
+```
+
+A page runs on the server, so it imports the query directly and awaits it. A client component imports the action and calls it (rewritten to an RPC stub).
+
+## The Drizzle query surface (rc.3)
+
+**Reads go through the relational query API** (`db.query.<table>.findFirst` / `.findMany`), NOT `db.select().from()`. Filter with a plain object `where` (the RQBv2 shape), order with an `orderBy` object, and pull relations with `with`.
+
+```ts
+const post = await db.query.posts.findFirst({
+  where: { slug: input.slug },
+  with: { author: { columns: { name: true } } },
+});
+const rows = await db.query.posts.findMany({
+  where: { authorId: me.id },
+  orderBy: { createdAt: 'desc' },
+  columns: { id: true, slug: true, title: true },
+});
+```
+
+Two rc.3 removals trip older tutorials: `db.select({ ... })` with a projection object is a `TS2554` (call `select()` with NO argument for the full row, then narrow in JS), and `.returning({ ... })` with a field object is also `TS2554` (call `.returning()` bare).
+
+**Mutations** use the query-builder with the imported SQL operators (`eq`, `and`, `inArray` from `drizzle-orm`) and read back with a no-arg `.returning()`:
+
+```ts
+import { eq } from 'drizzle-orm';
+const [row] = await db.insert(posts).values({ title, body, authorId: me.id }).returning();
+const [updated] = await db.update(posts).set({ title }).where(eq(posts.id, id)).returning();
+await db.delete(posts).where(eq(posts.id, id));
+```
+
+A `.returning()` row is the table's own columns only, never `with` relations. When the caller wants a joined shape, re-read with `db.query.*` or splice the already-known related value in by hand. Full surface at https://docs.webjs.dev.
+
+## Input validation at the boundary
+
+Declare `export const validate` beside the action. It runs SERVER-SIDE before the action body on the RPC boundary, receiving the action's FIRST argument. The framework only CALLS the validator (it ships no validation library) and reads its return: `{ success: true, data? }` runs the action (an optional `data` replaces the input), `{ success: false, fieldErrors }` returns a 422 WITHOUT running the body, and a THROW becomes a sanitized error.
+
+```ts
+// modules/posts/actions/create-post.server.ts
+'use server';
+export const validate = (input: any) => {
+  const fieldErrors: Record<string, string> = {};
+  const title = String(input?.title || '').trim();
+  if (!title) fieldErrors.title = 'Title is required';
+  if (String(input?.body || '').length < 10) fieldErrors.body = 'Too short';
+  if (Object.keys(fieldErrors).length) return { success: false, fieldErrors };
+  return { success: true, data: { title, body: String(input.body) } };
+};
+export async function createPost(input: { title: string; body: string }) { /* runs only when valid */ }
+```
+
+A client call resolves with the failure envelope (it does NOT throw), so the component reads `result.fieldErrors`. A zod adapter wraps `safeParse` so its result becomes the envelope; the framework stays zod-free.
+
+## HTTP-verb config exports
+
+A `'use server'` action is a POST by default. Reserved sibling exports, read statically (the same way a page reads `export const revalidate`), change its HTTP semantics WITHOUT changing the call site (you still write `await getUser(7)`).
+
+```ts
+// modules/users/queries/get-user.server.ts: a cached, tagged GET read
+'use server';
+export const method = 'GET';                       // absent = POST
+export const cache = 60;                            // seconds, or { maxAge, swr, public }
+export const tags = (id: number) => ['user:' + id];
+export async function getUser(id: number) { return db.query.users.findFirst({ where: { id } }); }
+```
+
+```ts
+// a mutation evicts the tags it touches
+'use server';
+export const invalidates = (id: number) => ['user:' + id];
+export const middleware = [requireAuth];           // async (ctx, next) => result; read ctx via actionContext()
+export async function updateUser(id: number, patch: Partial<User>) { /* ... */ }
+```
+
+- A **GET** rides args in the URL (POST fallback over a 4KB cap), is CSRF-exempt, and carries `Cache-Control` + a weak `ETag` (304 on `If-None-Match`) + `X-Webjs-Tags`. A **mutation** (POST/PUT/PATCH/DELETE) sends the rich body (DELETE rides the URL), is CSRF-protected, and on success evicts its `invalidates` tags and reports them via `X-Webjs-Invalidate`. A method mismatch is a `405` + `Allow`.
+- **SAFETY.** `cache` with `public: true` SHARES one response across ALL users, keyed only by URL + args. Use it ONLY for data identical for every visitor (the same rule as a page's `export const revalidate`), never for a session or per-user read.
+- Per-action `middleware` short-circuits by returning an `ActionResult` instead of calling `next()`, and accumulates context the action reads via `actionContext()` from `@webjsdev/server`.
+
+## The `ActionResult<T>` envelope
+
+Every action returns this additive envelope.
+
+```ts
+type ActionResult<T> =
+  | { success: true; data?: T; redirect?: string }   // redirect MUST be a same-site local path
+  | { success: false; error?: string; fieldErrors?: Record<string, string>;
+      values?: Record<string, string>; status?: number };
+```
+
+**Failure detection is robust.** A result is a FAILURE when `result.success === false`, OR `result.fieldErrors` is present, OR `result.error` is present and `result.success !== true`. Everything else is a success (an explicit `success: true`, or a bare value with no error markers). This means an error is never swallowed just because the author omitted a literal `success: false`.
+
+**`result.redirect` must be a same-site local path** (a single leading `/`). A protocol-relative `//host` or an absolute `scheme://host` URL is rejected (open-redirect guard); for a real external redirect, throw `redirect(absoluteUrl)` instead. A user-facing error message belongs on the envelope (`{ success: false, error }`), never on a raw throw, because prod sanitizes a thrown action error to a generic message plus a digest.
+
+## Exposing an action over REST: the `route()` adapter
+
+A public REST endpoint is a `route.ts` that imports and calls the action, optionally through the `route()` adapter from `@webjsdev/server` (it merges query + route params + JSON body into one input object and JSON-responds).
+
+```ts
+// app/api/posts/route.ts
+import { route } from '@webjsdev/server';
+import * as postActions from '#modules/posts/actions/create-post.server.ts';
+export const POST = route(postActions);   // module namespace: applies the action's OWN validate + middleware
+```
+
+Passing the MODULE NAMESPACE lets the adapter read the action's declared `middleware` and `validate`, so a guard declared once next to the action protects the RPC and REST boundaries alike. Passing the imported FUNCTION (`route(createPost, { validate })`) cannot see sibling config exports, so it applies only what you pass. A `{ success: false, fieldErrors }` return becomes a 422 JSON response; a validator that THROWS becomes a 400.
+
+A `route.ts` endpoint is NOT covered by the RPC CSRF check, so authenticate every mutating endpoint, use `validate`, and rate-limit (see `auth-and-sessions.md`).
+
+## Keeping server-only types off the client
+
+An interactive component needs the SHAPE of the data it renders, and those shapes derive from server-only modules. The one rule: **a type crossing to the browser is a TYPE, never a runtime value.** An `import type { ... }` is erased by the TypeScript stripper before the module reaches the browser. A plain `import { ... }` (a value import) survives stripping, pins the server module into the browser closure, and trips the `no-server-import-in-browser-module` check.
+
+```ts
+// SAFE: type-only, erased before it reaches the browser.
+import type { Post } from '#db/schema.server.ts';
+// UNSAFE: a value import survives stripping and pins the server schema. Throws at load.
+import { posts } from '#db/schema.server.ts';
+```
+
+Keep the wire shape in a browser-safe `modules/<feature>/types.ts` with NO runtime import from a `.server.ts` file or from `db/`. Define a hand-written DTO, or a type-only derivation (`import type { Post } ...; export type PostFormatted = Omit<Post, 'createdAt'> & { createdAt: string }`). Never `export *` or a value re-export from a `.server.ts` in `types.ts`; that carries the runtime table bindings and breaks any component importing the types. Full reference at https://docs.webjs.dev.