@webjsdev/cli 0.10.29 → 0.10.31

package/templates/AGENTS.md

@@ -4,8 +4,8 @@ Read this before editing any file. This is a webjs app: AI-first, web-
 components-first, no build step. The framework's own full API reference
 lives at https://github.com/webjsdev/webjs/blob/main/AGENTS.md and the
 full hosted documentation (every API, recipe, and example) lives at
-**https://docs.webjs.com**. Treat this file as the app-scoped
-companion and reach for docs.webjs.com whenever you need more detail.
+**https://docs.webjs.dev**. Treat this file as the app-scoped
+companion and reach for docs.webjs.dev whenever you need more detail.
 
 ## If you just scaffolded this app (AI agents, read first)
 
@@ -20,7 +20,13 @@ example `Home` nav, and pick a content-width container that fits. The
 default `<main class="max-w-[760px]">` is a reading column for prose and
 forms, so for a full-bleed app, dashboard, or board, widen the cap or
 remove it (keep the theme tokens). A wide layout left in the 760px
-reading column overflows into a horizontal scrollbar. This is ENFORCED:
+reading column overflows into a horizontal scrollbar. **Give the app a
+unique design.** When it has a UI, choose its palette, layout, typography,
+and chrome to fit what the user asked for, rather than mimicking the
+scaffold's example look (the warm accent, the reading column, the serif
+display, the example header/nav) or just recoloring the same layout. The
+`api` template has no UI, so this does not apply there. The design tokens
+and theme wiring are infrastructure to keep and restyle on top of. This is ENFORCED:
 the example `app/page.ts` and `app/layout.ts` carry a
 `webjs-scaffold-placeholder` marker comment, and `webjs check` fails
 while any marker remains, so this freshly scaffolded app fails the check
@@ -51,6 +57,17 @@ user asked for, never leftover scaffold code.
    app's real domain models (delete the example `User` model unless the
    app actually needs users), run `webjs db generate` then
    `webjs db migrate`, then build pages / actions / queries against them.
+4. **Prune what the app does not use.** The scaffold is reference, so keep
+   the infrastructure the app USES and delete the rest, both files AND
+   folders. No persistence means delete `db/`, `drizzle.config.ts`, and
+   the `db:*` scripts. No UI kit used means delete `components/ui/`,
+   `components.json`, and `lib/utils/cn.ts`. No PWA means delete
+   `public/sw.js` and `offline.html`. Always KEEP the durable knowledge
+   (`AGENTS.md`, `CONVENTIONS.md`, the per-agent rule files, the MCP
+   wiring), never prune it, so removing example code never removes your
+   context. Prune AFTER you have used the features and examples as reference, never
+   blindly up front. This is a no-op for the `api` template (no UI kit,
+   no PWA files).
 
 **Picking the right scaffold from the user's prompt** (you do this BEFORE
 running `webjs create`; if you're reading this you've already scaffolded.
@@ -171,7 +188,7 @@ entry, its own template parser. Inside `` html`…` `` templates you get:
 In VS Code / Cursor / Windsurf, the **`webjs` extension** bundles this
 automatically (no `tsconfig.json` edit, no separate Lit extension).
 
-See [docs.webjs.com → Editor setup](https://docs.webjs.com/docs/editor-setup)
+See [docs.webjs.dev → Editor setup](https://docs.webjs.dev/docs/editor-setup)
 for the full walkthrough.
 
 **Config validation in `package.json`.** The scaffold ships
@@ -296,11 +313,32 @@ wrapper adds zero value and obscures the real element from inspection,
 form submission, and screen readers. Custom elements are reserved for
 behavior the browser can't deliver natively.
 
+### Accessible control labeling
+
+Give every interactive control an accessible name, and make clickable
+text a `<label for="control-id">` (or the control itself) so a text click
+activates the control on BOTH the JS path and the no-JS form-submit path.
+Use `aria-label` and `aria-pressed` on icon-only controls (a toggle
+button, an icon-only close/menu button). A native `<input>` under a
+`<label>` gets this for free, which is another reason to reach for the
+Tier-1 class helpers on real elements. In a browser test,
+`assertNoA11yViolations(el)` from `@webjsdev/core/testing` catches
+missing labels.
+
 ## File conventions
 
 ```
-app/                     thin route adapters (import from modules/)
-  page.ts                → /
+app/                     ROUTING ONLY: thin route adapters (import from modules/).
+                         No CSS, helpers, or constants here; those live in
+                         styles/, lib/utils/, and modules/. globals.css is at
+                         styles/, NOT app/.
+  page.ts                → / (the scaffold home links to the gallery)
+  features/<name>/       single-feature demos (routing, components,
+                         server-actions, optimistic-ui, async-render,
+                         directives, route-handler, forms, metadata, caching,
+                         env, client-router, service-worker); prune what you skip
+  examples/<name>/       whole example apps that compose features (todo);
+                         prune what you skip
   layout.ts              root layout, wraps every page
   error.ts               error boundary (render failures → user-friendly)
   loading.ts             Suspense fallback for sibling page
@@ -324,6 +362,8 @@ modules/<feature>/
   types.ts               feature types
 lib/
   ...                    cross-cutting infra (session, auth config, etc.)
+styles/
+  globals.css            @webjsdev/ui theme tokens (NOT in app/; app/ is routing-only)
 db/
   schema.server.ts       Drizzle models + relations (your data layer)
   columns.server.ts      column helpers (dialect-specific; the only file to swap for Postgres)
@@ -341,6 +381,41 @@ test/<feature>/                feature-scoped tests, one folder per concern
 middleware.ts            root middleware (optional, outermost)
 ```
 
+### The gallery (reference content, prune it)
+
+The scaffold ships a gallery organized by KIND, so features and whole apps are
+not mixed:
+- `app/features/<name>/` are single-feature demos, one webjs concept each
+  (routing, components, server-actions, optimistic-ui, async-render, directives,
+  route-handler, forms, metadata, caching, env, client-router, service-worker,
+  plus the infra demos websockets, file-storage, rate-limit, broadcast).
+- `app/examples/<name>/` are whole example apps that compose several features
+  (todo: optimistic UI + progressive enhancement + a11y + db + modules).
+
+Both keep their logic in `modules/<name>/`. Each route is small, idiomatic, and
+heavily commented, and the gallery is your PRIMARY reference for how webjs works.
+
+**Study the whole gallery FIRST, prune SECOND.** Before you write or delete
+anything, read every feature demo and the example app end to end (the code AND
+the comments) to absorb the idioms you will reuse: the modules split, signals,
+the `optimistic()` API, `async render()`, the `.server.ts` vs `'use server'`
+boundary, progressive-enhancement forms, `<label for>` a11y, dynamic routes, and
+`route.ts` handlers. Only AFTER you have internalised the patterns should you
+prune. Never delete the examples blindly up front (that throws away your context
+before you have read it), and never prune the durable knowledge surfaces
+(`AGENTS.md`, `CONVENTIONS.md`, the per-agent rule files), which stay as context
+for every future iteration.
+
+Then prune: the examples are REFERENCE, not your app, so keep and adapt the ones
+you need and delete the rest. Pruning a route means deleting its
+`app/features/<name>` or `app/examples/<name>` folder AND its `modules/<name>`
+folder (and, for the todo app, the `todos` table in `db/schema.server.ts`), then
+removing its link from `app/page.ts`. Each route page carries a
+`webjs-scaffold-placeholder` marker so `webjs check` fails until you have
+consciously kept-and-adapted or pruned it. After pruning, delete any now-empty
+directories (an empty `lib/utils/` or `modules/<name>/` is leftover scaffolding,
+not structure).
+
 ### Typed page / layout / route-handler props
 
 Type page / layout / route-handler arguments with the exported helpers so a
@@ -517,7 +592,7 @@ git commit -m "vendor + download dayjs"
 Bundle files land in `.webjs/vendor/<pkg>@<version>.js`. importmap
 points at local `/__webjs/vendor/` paths. Browser fetches from your
 own origin. Suitable for `script-src 'self'` CSP, air-gapped deploys,
-or compliance environments. See [docs.webjs.com Deployment → CSP](https://docs.webjs.com/docs/deployment#csp).
+or compliance environments. See [docs.webjs.dev Deployment → CSP](https://docs.webjs.dev/docs/deployment#csp).
 
 **Other CLI commands:**
 
@@ -593,7 +668,7 @@ const url = process.env.WEBJS_PUBLIC_API_URL;       // works
 const secret = process.env.AUTH_SECRET;             // undefined (fail-closed)
 ```
 
-`process.env.NODE_ENV` is also defined in the browser (`'development'` in `webjs dev`, `'production'` in `webjs start`), so vendor bundles that probe it work without setup. Full docs: [Configuration](https://docs.webjs.com/docs/configuration).
+`process.env.NODE_ENV` is also defined in the browser (`'development'` in `webjs dev`, `'production'` in `webjs start`), so vendor bundles that probe it work without setup. Full docs: [Configuration](https://docs.webjs.dev/docs/configuration).
 
 ## Component pattern
 
@@ -751,6 +826,31 @@ globally. Prefer Tailwind. When a utility bundle repeats, extract it into
 a `lib/utils/ui.ts` helper returning an `` html`...` `` fragment, not a
 CSS class.
 
+#### Design tokens: ONE theme, shadcn-canonical
+
+The app has a SINGLE theme, defined once in `app/layout.ts`. It uses the
+standard `@webjsdev/ui` (shadcn-compatible) semantic tokens, set to this app's
+brand palette. Use the canonical utility names everywhere, in the page chrome
+AND inside components: `bg-background`, `text-foreground`, `bg-card`, `bg-muted`,
+`text-muted-foreground`, `bg-primary`, `text-primary-foreground`, `bg-accent`,
+`text-accent-foreground`, `border-border`, `ring-ring`. These are exactly the
+tokens the components copied in by `webjs ui add <name>` read, so a scaffolded
+page and a later-added ui component share one coherent theme automatically.
+
+- **Never invent a parallel token vocabulary** (`--fg`, `--bg`, `text-fg`,
+  `bg-elev`, a separate `--brand`). It collides with the ui tokens (the accent
+  once flipped to neutral on navigation for exactly this reason) and diverges
+  from the shadcn conventions the ui kit and AI agents both expect.
+- **Reach for opacity modifiers before a new token**: `bg-primary/10` for a
+  tint, `hover:bg-primary/90` for a hover, `text-muted-foreground/70` for a
+  subtler text level.
+- **Edit the palette in one place** (`app/layout.ts`). To ADD a token, do it
+  the canonical way: a `--x` variable in the `:root` / `.dark` blocks plus a
+  `--color-x: var(--x)` line in the `@theme inline` block, then use it as
+  `bg-x` / `text-x`.
+- Dark mode is a `.dark` class the theme toggle sets. Tokens switch by theme
+  automatically, so a component written with these names works in both.
+
 Reserve raw CSS for what utilities cannot express: design-token `:root` /
 `@theme` definitions, `@property` + `@keyframes` animations,
 `::-webkit-scrollbar`, `prefers-reduced-motion` blocks, and complex
@@ -761,6 +861,16 @@ legitimately use `static styles = css\`\`` for scoped CSS.
 
 ## Server action pattern
 
+**The `.server.ts` vs `'use server'` decision, in one question.** Will the
+client call it? Add `'use server'` and the file becomes an RPC action
+(the browser import is rewritten to a typed stub). Is it server-only
+infra instead (a DB driver, secrets, `node:*`)? Use NO directive, and
+never import it into a page, layout, or component. Reach it from a
+`'use server'` action, a `route.ts` handler, or `middleware.ts`. A
+`.server.ts` file WITHOUT the directive is a server-only utility whose
+browser import throws at module load (invariant 2 below), so a
+page/component that imports it directly crashes on the client.
+
 ```ts
 // modules/posts/actions/create-post.server.ts
 'use server';
@@ -788,7 +898,43 @@ that RETURNS a `ReadableStream` / async generator streams its chunks (consume
 with `for await`); read the request `AbortSignal` via `actionSignal()` to cancel
 on disconnect. **SAFETY:** a `cache` with `public: true` shares one response
 across all users, so use it only for data identical for every visitor. Full
-reference: https://docs.webjs.com/docs/server-actions
+reference: https://docs.webjs.dev/docs/server-actions
+
+## Mutations: default to optimistic UI
+
+Default to optimistic UI for every feasible mutation. Use `optimistic()`
+from `@webjsdev/core` (create, toggle, like, follow, reorder, rename,
+status change) so the UI updates instantly and rolls back automatically
+on failure. The declarative form queues an update on a component with
+auto-release when the action promise settles, no hand-written try-catch,
+cache-and-restore, or temp-id bookkeeping.
+
+```ts
+import { WebComponent, prop, optimistic, html } from '@webjsdev/core';
+import { createTodo } from '#modules/todos/actions/create-todo.server.ts';
+
+class TodoList extends WebComponent({ todos: prop<Todo[]>(Array) }) {
+  private optimisticTodos = optimistic(this, {
+    source: () => this.todos,
+    update: (state, title: string) => [...state, { title, pending: true }],
+  });
+  async handleSubmit(title: string) {
+    const promise = createTodo({ title });
+    this.optimisticTodos.add(title, promise);   // auto-releases on settle
+    await promise;
+  }
+  render() {
+    return html`<ul>${this.optimisticTodos.value.map(t => html`
+      <li class=${t.pending ? 'opacity-50' : ''}>${t.title}</li>`)}</ul>`;
+  }
+}
+```
+
+Do NOT use optimistic UI where it hurts: unpredictable or server-computed
+results (AI output, server-assigned values the client cannot guess),
+side-effectful mutations the user must wait on (payment, email, OAuth),
+and destructive irreversible actions (a confirm-first UX is better). Full
+reference: https://docs.webjs.com/docs/optimistic-ui
 
 ## Client navigation patterns (auto-magic)
 
@@ -1166,7 +1312,11 @@ composition, so a nested shell ends up dropped by the HTML parser.
    `lib/utils/cn.ts` with `cn`, design-
    system helpers). Server-only `lib/*` files must only be imported
    from `.server.ts`/`route.ts`/`middleware.ts`; browser-safe `lib/*`
-   files (like `lib/utils/cn.ts`) can be imported anywhere.
+   files (like `lib/utils/cn.ts`) can be imported anywhere. A TYPE-ONLY
+   import is the exception: `import type { Todo } from
+   '#db/schema.server.ts'` is fine in a page or component, because the
+   TypeScript stripper erases it before it reaches the browser, so
+   sharing a derived row type is safe and is not flagged.
 3. Event / property / boolean holes in `` html`` `` are unquoted:
    `@click=${fn}`, not `@click="${fn}"`.
 4. Component state lives in signals. Import `signal` from

package/templates/CONVENTIONS.md

@@ -310,9 +310,45 @@ production workloads.
 <!-- OVERRIDE -->
 
 This project was created with `webjs create`. Every file you see right
-now (the `app/page.ts` "Hello from …" homepage, the example `User`
-model, the `theme-toggle` component, the example users module in api /
-saas templates) is a **starting point**.
+now (the `app/page.ts` homepage, the example `User` model, the
+`theme-toggle` component, the gallery under `app/features/` and
+`app/examples/` in the full-stack template, the example users module in
+api / saas templates) is a **starting point**.
+
+The full-stack and saas scaffolds ship a **gallery** organized by kind so features
+and whole apps are not mixed. `app/features/<name>/` are single-feature
+demos, one webjs concept each (routing, components, server-actions,
+optimistic-ui, async-render, directives, route-handler). `app/examples/<name>/`
+are whole example apps that compose several features (todo: optimistic UI
++ progressive enhancement + a11y + db + modules). Both keep their logic in
+`modules/`, are small and heavily commented, and are the PRIMARY reference
+for how webjs works.
+
+**Study the whole gallery FIRST, prune SECOND.** Before writing or deleting
+anything, read every feature demo and the example app end to end (code AND
+comments) to absorb the idioms you will reuse. Only AFTER you have
+internalised the patterns should you prune. Never delete the examples
+blindly up front (that discards your context before you have read it), and
+never prune the durable knowledge surfaces (`AGENTS.md`, `CONVENTIONS.md`,
+the per-agent rule files), which stay as context for every future
+iteration.
+
+Then prune: the examples are REFERENCE, not the app, so keep and adapt the
+ones you need and **delete the rest**. Pruning a route means deleting its
+`app/features/<name>` or `app/examples/<name>` folder AND its
+`modules/<name>` folder (for the todo app, also the `todos` table in
+`db/schema.server.ts` and its link in `app/page.ts`). Each route page
+carries a `webjs-scaffold-placeholder` marker, so `webjs check` fails until
+you consciously keep-and-adapt or prune it. After pruning, delete any
+now-empty directories, an empty `lib/utils/` or `modules/<name>/` is
+leftover scaffolding, not structure.
+
+**`app/` is routing-only.** Only routing files belong in `app/` (page,
+layout, route, middleware, and metadata routes). CSS, helpers, and
+constants do NOT: the theme lives at `styles/globals.css` (NOT
+`app/globals.css`), browser-safe helpers at `lib/utils/`, and feature
+logic in `modules/`. If you add a stylesheet or a helper, put it outside
+`app/`.
 
 When the user asks the agent to build their actual app:
 
@@ -325,6 +361,10 @@ When the user asks the agent to build their actual app:
    need a theme picker.
 4. **Delete the example users module** (api/saas templates) if the app
    doesn't use it.
+4b. **Prune the gallery** (full-stack template). Keep and adapt the
+   `app/features/` demos and the `app/examples/` app the real app uses,
+   delete the rest (route + module + any table), and remove their links
+   from `app/page.ts`.
 5. **Adapt `app/layout.ts` to the app, not just the page.** Set the real
    brand, replace the example `Home` nav with the app's navigation, and
    pick a content-width container that fits. The default
@@ -333,15 +373,25 @@ When the user asks the agent to build their actual app:
    dashboard, or board, or a wide layout overflows into an unnecessary
    horizontal scrollbar. Keep the design tokens and theme setup, those
    are infrastructure.
-6. **Keep:** the Drizzle setup, the test config, the agent config files
+6. **Use a unique design (UI apps).** Give the app a look of its own that
+   fits what the user asked for. Choose the palette, layout, typography,
+   spacing, and chrome deliberately. Do NOT mimic the scaffold's example
+   look (its warm accent, the 760px reading column, the serif display, the
+   example header/nav), and do not just recolor the same layout. The
+   `api` template has no UI, so this does not apply there. The design
+   tokens and theme wiring in `app/layout.ts` are infrastructure to keep
+   and restyle on top of, not the example look to preserve.
+7. **Keep:** the Drizzle setup, the test config, the agent config files
    (`AGENTS.md`, `CONVENTIONS.md`, `CLAUDE.md`, `.cursorrules`, etc.),
    `db/connection.server.ts` + `db/columns.server.ts`, the directory
    conventions, the design tokens in `app/layout.ts`. These are the
    infrastructure, not the example app.
 
-This is enforced, not just advised. The example `app/page.ts` and
-`app/layout.ts` carry a `webjs-scaffold-placeholder` marker comment, and
-the `no-scaffold-placeholder` check fails while any marker remains, so a
+This is enforced, not just advised. The example `app/page.ts`,
+`app/layout.ts`, and each `app/features/<name>/page.ts` +
+`app/examples/<name>/page.ts` carry a
+`webjs-scaffold-placeholder` marker comment, and the
+`no-scaffold-placeholder` check fails while any marker remains, so a
 freshly scaffolded app fails `webjs check` until you address each
 placeholder. The marker is acknowledge-and-remove: replace the example
 content, or deliberately keep it, and in either case delete the marker
@@ -352,6 +402,19 @@ The scaffold exists so the agent doesn't reinvent the directory layout,
 the Drizzle wiring, the test runner config, or the convention files. It
 does NOT exist so the agent ships the example homepage.
 
+### Prune what the app does not use
+
+The scaffold is reference, so keep the infrastructure the app actually
+USES and delete the rest, both files AND their folders. No persistence
+means delete `db/`, `drizzle.config.ts`, and the `db:*` scripts. No UI
+kit used means delete `components/ui/`, `components.json`, and
+`lib/utils/cn.ts`. No PWA means delete `public/sw.js` and `offline.html`.
+Always KEEP the durable knowledge (`AGENTS.md`, `CONVENTIONS.md`, the
+per-agent rule files, the MCP wiring), and never prune it, so removing
+example code never removes your context. Prune AFTER you have used the
+features and examples as reference, never blindly up front. This is a no-op for the
+`api` template, which ships no UI kit and no PWA files.
+
 ---
 
 ## Sensible defaults
@@ -401,7 +464,7 @@ modules/
 - One exported function per server action/query file
 - Server actions need BOTH the `.server.{js,ts}` extension AND a `'use server'` directive at the top. Extension alone marks a server-only utility (source-protected, not RPC-callable). Directive alone is a lint violation (`use-server-needs-extension`).
 - Components must call `Class.register('tag')`
-- **Server-only code goes in `.server.{js,ts}` files, `route.ts` handlers, or `middleware.ts`. Never in pages, layouts, or components.** Direct imports of a DB driver (`pg`) or `node:*` from pages, layouts, or components crash the browser at module load. Wrap in a `.server.{js,ts}` file; the framework rewrites that import to an RPC stub on the browser side. The DB lives in `db/*.server.ts`; `lib/` holds other server-only infra and browser-safe utilities (`lib/utils/cn.ts` with `cn`); the convention is "if a `lib/` file needs Node APIs, only import it from server-only files."
+- **Server-only code goes in `.server.{js,ts}` files, `route.ts` handlers, or `middleware.ts`. Never in pages, layouts, or components.** Direct imports of a DB driver (`pg`) or `node:*` from pages, layouts, or components crash the browser at module load. Wrap in a `.server.{js,ts}` file; the framework rewrites that import to an RPC stub on the browser side. The DB lives in `db/*.server.ts`; `lib/` holds other server-only infra and browser-safe utilities (`lib/utils/cn.ts` with `cn`); the convention is "if a `lib/` file needs Node APIs, only import it from server-only files." A TYPE-ONLY `import type { Todo } from '#db/schema.server.ts'` is the exception, fine in a page or component because the stripper erases it before it reaches the browser.
 - Routes (`app/**/page.ts`, `app/**/route.ts`) must be thin: import logic from modules
 - **Fetch server data in the component that needs it, with an `async render()`, not by prop-drilling.** A leaf component can write `const u = await getUser(this.uid)` directly in `render()`; SSR awaits it so the data is in the first paint, and the client uses stale-while-revalidate on a re-fetch. Reach for `renderFallback()` only to show a re-fetch loading state, and `Task` / signals only for genuinely client-only data (a `Task` shows its pending state at SSR, losing first-paint data). Do not put `await getData()` in a page / layout when a leaf component can own it (page fetches run sequentially, a route-level waterfall).
 - **Keep pages and layouts as pure carriers, so their modules stay out of the network tab.** A page/layout never hydrates; the framework drops its module from the browser as long as its only browser-relevant job is registering the components it imports. It starts shipping its own module (invisible in tests) the moment its closure does any OTHER client work. So do not give a page/layout module-scope client work (a top-level call, a `window` / `document` / `customElements` access, a bare side-effect import, or a `@webjsdev/core/client-router` import: routing is automatic), and do not import a client-global-touching non-component util into it. Put client behaviour in a component, server-only code in `.server.{js,ts}`. Self-check: `page.ts` / `layout.ts` should not appear in the browser's network tab.
@@ -664,7 +727,7 @@ export class MyWidget extends WebComponent({
   render() {
     return html`
       <div class="p-4 border border-border rounded-lg">
-        <p class="font-serif text-fg">${this.label}: ${this.count}</p>
+        <p class="font-serif text-foreground">${this.label}: ${this.count}</p>
       </div>
     `;
   }
@@ -724,8 +787,27 @@ Both hydrate without flash on the client.
 The scaffold ships with the **Tailwind CSS browser runtime** + `@theme`
 design tokens defined in the root layout. Every colour, font family,
 fluid type scale value, and motion duration is declared once in `@theme`
-and available everywhere via utility classes (`text-fg`, `bg-bg-elev`,
-`font-serif`, `duration-fast`, `text-display`).
+and available everywhere via utility classes (`text-foreground`,
+`bg-card`, `font-serif`, `duration-fast`, `text-display`).
+
+**One theme, canonical tokens.** The app has a SINGLE theme, defined
+once in `app/layout.ts` using the standard `@webjsdev/ui`
+(shadcn-compatible) semantic tokens set to the brand palette. Use the
+canonical utility names everywhere, in the page chrome AND inside
+components: `bg-background`, `text-foreground`, `bg-card`, `bg-muted`,
+`text-muted-foreground`, `bg-primary`, `text-primary-foreground`,
+`bg-accent`, `text-accent-foreground`, `border-border`, `ring-ring`.
+These are exactly the tokens a component copied in by
+`webjs ui add <name>` reads, so a scaffolded page and a later-added ui
+component share one coherent theme with no extra wiring. **Never invent a
+parallel token vocabulary** (`--fg`, `--bg`, `text-fg`, `bg-elev`, a
+separate `--brand`): it collides with the ui tokens (the accent once
+flipped to neutral on navigation for exactly this reason) and diverges
+from the shadcn conventions the kit and AI agents both expect. Reach for
+opacity modifiers (`bg-primary/10`, `hover:bg-primary/90`,
+`text-muted-foreground/70`) before adding a token; to ADD one, do it the
+canonical way (a `--x` variable in the `:root` / `.dark` blocks plus a
+`--color-x: var(--x)` line in `@theme inline`, then `bg-x` / `text-x`).
 
 **Tailwind-first is the strong default for pages AND light-DOM
 components (the default DOM mode).** Use utilities for layout, spacing,
@@ -998,6 +1080,12 @@ toggle, the tab switch) requires JS.
 - **Don't gate read-paths on hydration.** Never write components whose
   SSR'd HTML is empty or wrong on purpose with the expectation that
   JS will fill it in. The first paint must be the right content.
+- **Label every interactive control.** Give each control an accessible
+  name, and make clickable text a `<label for="control-id">` (or the
+  control itself) so a text click activates the control on BOTH the JS
+  path and the no-JS form-submit path. Use `aria-label` and
+  `aria-pressed` on icon-only controls. `assertNoA11yViolations(el)` in a
+  browser test (see the Testing section) catches missing labels.
 
 **SSR-meaningful component state.** The SSR pipeline constructs the
 component, applies its attributes, runs `willUpdate` and controllers'
@@ -1046,6 +1134,16 @@ Where the data lives, where to read it:
 
 <!-- OVERRIDE -->
 
+**The `.server.ts` vs `'use server'` decision, in one question.** Will the
+client call it? Add `'use server'` and the file becomes an RPC action
+(the browser import is rewritten to a typed stub). Is it server-only
+infra instead (a DB driver, secrets, `node:*`)? Use NO directive, and
+never import it into a page, layout, or component. Reach it from a
+`'use server'` action, a `route.ts` handler, or `middleware.ts`. A
+`.server.ts` file WITHOUT the directive is a server-only utility whose
+browser import throws at module load, so a page/component that imports it
+directly crashes on the client.
+
 ```ts
 // modules/posts/actions/create-post.server.ts
 'use server';
@@ -1070,6 +1168,47 @@ export async function createPost(input: {
 
 ---
 
+## Mutations: default to optimistic UI
+
+<!-- OVERRIDE -->
+
+Default to optimistic UI for every feasible mutation. Use `optimistic()`
+from `@webjsdev/core` (create, toggle, like, follow, reorder, rename,
+status change) so the UI updates instantly and rolls back automatically
+on failure. No hand-written try-catch, cache-and-restore, or temp-id
+reconciliation.
+
+```ts
+import { WebComponent, prop, optimistic, html } from '@webjsdev/core';
+import { createTodo } from '#modules/todos/actions/create-todo.server.ts';
+
+class TodoList extends WebComponent({ todos: prop<Todo[]>(Array) }) {
+  private optimisticTodos = optimistic(this, {
+    source: () => this.todos,
+    update: (state, title: string) => [...state, { title, pending: true }],
+  });
+
+  async handleSubmit(title: string) {
+    const promise = createTodo({ title });
+    this.optimisticTodos.add(title, promise);   // auto-releases on settle
+    await promise;
+  }
+
+  render() {
+    return html`<ul>${this.optimisticTodos.value.map(t => html`
+      <li class=${t.pending ? 'opacity-50' : ''}>${t.title}</li>`)}</ul>`;
+  }
+}
+```
+
+Do NOT reach for optimistic UI where it hurts: unpredictable or
+server-computed results (AI output, server-assigned values the client
+cannot guess), side-effectful mutations the user must wait on (payment,
+email, OAuth), and destructive irreversible actions (a confirm-first UX
+is better). See `agent-docs/advanced.md` for the full API.
+
+---
+
 ## Code style
 
 <!-- OVERRIDE -->

package/templates/gallery/app/examples/todo/page.ts

@@ -0,0 +1,34 @@
+// webjs-scaffold-placeholder. Example gallery route. Keep and adapt it, or prune it (delete this app/examples/todo route, modules/todo, AND the todos table in db/schema.server.ts), then delete this marker line. webjs check fails while the marker remains.
+// A THIN route adapter: app/ is routing only. It fetches the initial data
+// (server-side) via the 'use server' query and renders the interactive
+// component, plus a page `action` for the no-JS write path. All the real logic
+// lives in modules/todo/. This is the idiomatic app-thin + modules-logic split.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core'; // Metadata is a @webjsdev/core type
+import { listTodos } from '#modules/todo/queries/list-todos.server.ts';
+import { createTodo } from '#modules/todo/actions/create-todo.server.ts';
+import { toggleTodo } from '#modules/todo/actions/toggle-todo.server.ts';
+import { deleteTodo } from '#modules/todo/actions/delete-todo.server.ts';
+import '#modules/todo/components/todo-app.ts';
+
+export const metadata: Metadata = { title: 'Todo (optimistic UI) | examples' };
+
+export default async function TodoExample() {
+  // SSR-fetched and seeded, so <todo-app> paints the real list on first byte.
+  const todos = await listTodos();
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Optimistic todo</h1>
+    <todo-app .todos=${todos}></todo-app>
+  `;
+}
+
+// No-JS write path: the component's <form>s post here; with JS the component
+// intercepts and mutates optimistically instead. Success is a 303 PRG.
+export async function action({ formData }: { formData: FormData }) {
+  const intent = String(formData.get('intent') ?? '');
+  const id = String(formData.get('id') ?? '');
+  if (intent === 'create') return createTodo({ title: String(formData.get('title') ?? '') });
+  if (intent === 'toggle') return toggleTodo({ id });
+  if (intent === 'delete') return deleteTodo({ id });
+  return { success: false as const, error: 'Unknown action.', status: 400 };
+}

package/templates/gallery/app/features/async-render/page.ts

@@ -0,0 +1,14 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/async-render route AND modules/async-render), then delete this marker line. webjs check fails while the marker remains.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import '#modules/async-render/components/server-clock.ts';
+
+export const metadata: Metadata = { title: 'Async render (server data in first paint) | features' };
+
+export default function AsyncRenderExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Async render</h1>
+    <p class="text-muted-foreground mb-4">A component's <code>async render()</code> awaits server data. SSR blocks, so the resolved value is in the first paint (no fallback, readable with JS off).</p>
+    <server-clock></server-clock>
+  `;
+}

package/templates/gallery/app/features/broadcast/feed/route.ts

@@ -0,0 +1,19 @@
+// The WebSocket endpoint for the broadcast demo. Unlike the echo endpoint, this
+// fans each incoming message out to EVERY client on the path with broadcast()
+// from '@webjsdev/server'. The framework auto-registers each connection to its
+// route path, so broadcast('/features/broadcast/feed', ...) reaches all of them.
+import { broadcast } from '@webjsdev/server';
+
+// Structural type for the socket, so the demo needs no `@types/ws` dependency.
+type WSLike = {
+  on(event: 'message' | 'close', cb: (data: Buffer) => void): void;
+  send(msg: string): void;
+};
+
+export function WS(ws: WSLike) {
+  ws.on('message', (data) => {
+    // Fan out to every connected client (the sender included, so all open tabs
+    // stay in sync). Pass { except: ws } if you want to skip the sender.
+    broadcast('/features/broadcast/feed', data.toString());
+  });
+}

package/templates/gallery/app/features/broadcast/page.ts

@@ -0,0 +1,24 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/broadcast route AND modules/broadcast), then delete this marker line. webjs check fails while the marker remains.
+// Broadcast: fan a message out to EVERY client connected to a WebSocket path,
+// not just the sender. The framework auto-registers each connection to its path,
+// so broadcast(path, data) from '@webjsdev/server' reaches all of them. This is
+// the difference from the plain websockets demo (which echoes to one socket).
+// Open this page in two browser tabs and send: both see every message.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import '#modules/broadcast/components/broadcast-feed.ts';
+
+export const metadata: Metadata = { title: 'Broadcast (fan-out to all clients) | features' };
+
+export default function BroadcastExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Broadcast</h1>
+    <p class="text-muted-foreground mb-4">
+      Every message is fanned out to all connected clients via
+      <code class="font-mono">broadcast()</code>. Open this page in a second tab
+      and watch messages appear in both. Single-instance by default; wire Redis
+      to scale across processes.
+    </p>
+    <broadcast-feed></broadcast-feed>
+  `;
+}

package/templates/gallery/app/features/caching/page.ts

@@ -0,0 +1,39 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/caching route), then delete this marker line. webjs check fails while the marker remains.
+// Caching: `export const revalidate = N` opts the page into the server HTML
+// response cache, keyed by URL for N seconds. The rendered timestamp below only
+// changes once per window: reload inside 10s and it is identical, reload after
+// and it refreshes. SAFETY: only cache a page that is identical for every
+// visitor (no cookies(), no session, no per-user data), since the key is the URL
+// alone. For per-query reads use cache() + tags with revalidateTag; for assets
+// use HTTP Cache-Control + ETag (conditional GET).
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Caching (revalidate) | features' };
+
+// Cache this page's SSR HTML for 10 seconds.
+export const revalidate = 10;
+
+export default function CachingExample() {
+  // Runs at render time, then the whole response is cached for `revalidate`
+  // seconds, so this value is frozen until the window elapses.
+  const renderedAt = new Date().toLocaleTimeString('en-US', { hour12: false });
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Caching</h1>
+    <p class="text-muted-foreground mb-4">
+      This page sets <code>export const revalidate = 10</code>, so its
+      server-rendered HTML is cached per URL for ten seconds.
+    </p>
+    <p class="mb-4">
+      Rendered at
+      <code class="font-mono text-primary">${renderedAt}</code>.
+      Reload within 10s and this is unchanged; after 10s it re-renders.
+    </p>
+    <p class="text-muted-foreground text-sm">
+      Only for pages identical for every visitor. For per-user or per-query data
+      use <code>cache()</code> with <code>tags</code> and
+      <code>revalidateTag</code>, or a GET action's
+      <code>export const cache</code>.
+    </p>
+  `;
+}