@webjsdev/cli 0.10.30 → 0.10.32

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,35 @@ 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, and redesign means more than recolor (UI apps).**
+   Give the app a design of its own (palette, typography, LAYOUT, spacing,
+   and chrome) chosen from what the app IS. Recoloring the scaffold and
+   swapping the logo while keeping its skeleton (a fixed top header with a
+   Home link and a theme toggle, the centered ~760px reading column, the
+   "Built with webjs" footer) is NOT a unique design. Decide from scratch
+   whether this app even needs a header or footer, what nav (if any), and
+   what layout fits (a centered board, a full-bleed dashboard, a split, a
+   single card). The scaffold ships a `webjs-scaffold-placeholder` marker on
+   its footer, so `webjs check` fails until you remove or replace the
+   "Built with webjs" branding. Self-audit before finishing: nothing should
+   read as the scaffold example (no "Built with webjs" footer, no leftover
+   example nav, no default reading column unless it truly fits). 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. Style with Tailwind
+   utilities wherever they reach, and use custom CSS only for what utilities
+   cannot express (@theme tokens, @keyframes, scrollbar, complex color-mix
+   or gradients). The `api` template has no UI, so this does not apply there.
+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 +412,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
@@ -664,7 +737,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 +797,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 +1090,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 +1144,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 +1178,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 -->
@@ -1116,8 +1265,12 @@ This project enforces a git workflow via agent-specific config files
   (`Add contact form with email validation`, not `update files`).
 - **NEVER add AI attribution.** No `Co-Authored-By: Claude`, no
   `Generated by AI`, no `AI-assisted` trailers or prefixes.
-- **Committing is automatic.** The user should never have to ask
-  "please commit". Commit after completing each logical unit.
+- **Committing is automatic (this overrides Claude Code's default).** The
+  user should never have to ask "please commit". Commit after completing each
+  logical unit. Claude Code's built-in never-commit default is overridden by
+  `CLAUDE.md`, and the `.claude/hooks/commit-before-stop.sh` Stop hook refuses
+  to end a turn with a pile of uncommitted work on a feature branch (disable
+  with `WEBJS_NO_COMMIT_STOP=1`).
 
 **Branch rules:**
 - **Feature branches.** Never commit directly to main

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>
+  `;
+}

package/templates/gallery/app/features/client-router/page.ts

@@ -0,0 +1,34 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/client-router route AND its second/ subpage), then delete this marker line. webjs check fails while the marker remains.
+// Client router: automatic. It auto-enables the moment @webjsdev/core loads in
+// the browser (the bundle every component pulls, so any page with a component
+// gets it for free). There is nothing to import. An <a href> to another page
+// does a soft navigation: the framework fetches only the divergent fragment
+// (via the X-Webjs-Have header), swaps it in place, and restores scroll on
+// back/forward. Links prefetch on hover by default. It degrades perfectly: with
+// JS off, every link is a normal full-page navigation.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Client router (soft nav) | features' };
+
+export default function ClientRouterExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Client router</h1>
+    <p class="text-muted-foreground mb-4">
+      Navigate to the second page and back. With JS on it is a soft swap (no full
+      reload, scroll restored); open the network tab to see only a fragment
+      fetched, prefetched on hover. With JS off the same links do full-page
+      navigations. Nothing was imported to get this.
+    </p>
+    <div class="flex gap-3 items-center">
+      <a href="/features/client-router/second" class="inline-flex items-center px-4 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm no-underline transition-all hover:bg-primary/90 active:scale-[0.97]">Go to page two</a>
+      <a href="/" class="text-muted-foreground no-underline font-medium text-sm hover:text-foreground transition-colors">Home</a>
+    </div>
+    <p class="text-muted-foreground text-sm mt-6">
+      Opt out app-wide with <code class="font-mono">{ "webjs": { "clientRouter": false } }</code>,
+      or per-link with <code class="font-mono">data-no-router</code> (use it for
+      auth flows like <code class="font-mono">/logout</code> that must reset
+      in-memory state).
+    </p>
+  `;
+}

package/templates/gallery/app/features/client-router/second/page.ts

@@ -0,0 +1,20 @@
+// webjs-scaffold-placeholder. Feature gallery route (client-router page two). Pruned together with the parent app/features/client-router route. Delete this marker line once you adapt or remove it. webjs check fails while the marker remains.
+// The soft-navigation target for the client-router demo. A plain page: the
+// router needs no per-page code. The browser Back button restores this page and
+// its scroll position from the client-router snapshot cache.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Client router: page two | features' };
+
+export default function ClientRouterSecond() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Page two</h1>
+    <p class="text-muted-foreground mb-4">
+      You arrived here without a full reload. Press the browser Back button (or
+      the link below): the previous page and its scroll position are restored
+      from the snapshot cache.
+    </p>
+    <a href="/features/client-router" class="text-primary no-underline font-medium">&larr; Back to page one</a>
+  `;
+}

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

@@ -0,0 +1,14 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/components route AND modules/components), 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/components/components/counter-card.ts';
+
+export const metadata: Metadata = { title: 'Components (signals + slots) | features' };
+
+export default function ComponentsExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Components</h1>
+    <p class="text-muted-foreground mb-4">The WebComponent factory, a reactive prop, an instance signal, and a slot.</p>
+    <counter-card label="Taps"><strong>A slotted title</strong></counter-card>
+  `;
+}

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

@@ -0,0 +1,14 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/directives route AND modules/directives), 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/directives/components/directive-demo.ts';
+
+export const metadata: Metadata = { title: 'Directives (repeat + watch) | features' };
+
+export default function DirectivesExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Directives</h1>
+    <p class="text-muted-foreground mb-4">The lit-html directive set: <code>repeat</code> keys a reordering list so nodes are reused, and <code>watch(signal)</code> swaps one node without a full re-render.</p>
+    <directive-demo></directive-demo>
+  `;
+}

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

@@ -0,0 +1,36 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/env route), then delete this marker line. webjs check fails while the marker remains.
+// Environment variables: process.env.X reads are server-only. NODE_ENV is
+// defined on both sides. A name prefixed WEBJS_PUBLIC_ is exposed to the browser
+// through an inline script (no build step); everything else stays server-side
+// so secrets never reach the client. This page reads them during SSR, so the
+// values are in the first paint with no JS. Validate required vars at boot with
+// an app-root env.ts (a schema or a validator fn) that fails fast.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Env vars (public vs server) | features' };
+
+export default function EnvExample() {
+  // Server-only read (this function runs on the server for SSR).
+  const nodeEnv = process.env.NODE_ENV || 'development';
+  // A WEBJS_PUBLIC_ var is safe to surface to the browser; unset here unless you
+  // add WEBJS_PUBLIC_APP_NAME=... to .env, which demonstrates the default.
+  const publicName = process.env.WEBJS_PUBLIC_APP_NAME || '(unset, add WEBJS_PUBLIC_APP_NAME to .env)';
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Environment variables</h1>
+    <p class="text-muted-foreground mb-4">
+      Read on the server during SSR. Only <code>WEBJS_PUBLIC_</code>-prefixed
+      names are exposed to the browser; the rest stay server-side.
+    </p>
+    <ul class="list-disc pl-5 mb-4 space-y-1">
+      <li><code class="font-mono text-sm">NODE_ENV</code> = <span class="text-primary">${nodeEnv}</span> <span class="text-muted-foreground text-sm">(defined both sides)</span></li>
+      <li><code class="font-mono text-sm">WEBJS_PUBLIC_APP_NAME</code> = <span class="text-primary">${publicName}</span></li>
+    </ul>
+    <p class="text-muted-foreground text-sm">
+      Never read a secret in a page, layout, or component that ships to the
+      browser. Keep secret reads in <code class="font-mono">.server.ts</code>
+      files, and validate required vars at boot with
+      <code class="font-mono">app/env.ts</code>.
+    </p>
+  `;
+}

package/templates/gallery/app/features/file-storage/file/[key]/route.ts

@@ -0,0 +1,19 @@
+// Serves a stored file back by key. getFileStore().get(key) returns the bytes as
+// a web ReadableStream (streamed, never buffered whole into memory) plus the
+// content type recorded at upload. A route.ts is server-only, so importing the
+// storage singleton here is safe. The [key] segment is validated inside the
+// store (traversal-safe), so a crafted key cannot escape the uploads directory.
+import { getFileStore } from '@webjsdev/server';
+
+export async function GET(_req: Request, { params }: { params: { key: string } }) {
+  const file = await getFileStore().get(params.key);
+  if (!file) return new Response('Not found', { status: 404 });
+  // file.body is a web ReadableStream at runtime (the diskStore streams the
+  // bytes); the store's type is a Node/web union, so narrow it for Response.
+  return new Response(file.body as ReadableStream<Uint8Array>, {
+    headers: {
+      'content-type': file.contentType,
+      'content-length': String(file.size),
+    },
+  });
+}

package/templates/gallery/app/features/file-storage/page.ts

@@ -0,0 +1,62 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/file-storage route AND modules/file-storage), then delete this marker line. webjs check fails while the marker remains.
+// File storage: a no-JS upload. A multipart <form> posts to this page's `action`
+// (the progressive-enhancement write path); the action calls a 'use server'
+// helper that streams the bytes into the FileStore. On success it redirects
+// (PRG) with the new key in the query, and the page renders a download link that
+// streams the file back through file/[key]/route.ts. Works with JS off; the
+// client router applies the same flow in place with JS on.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import { storeUpload } from '#modules/file-storage/actions/store-upload.server.ts';
+
+export const metadata: Metadata = { title: 'File storage (upload + serve) | features' };
+
+export async function action({ formData }: { formData: FormData }) {
+  const file = formData.get('file');
+  if (!(file instanceof File) || file.size === 0) {
+    return { success: false, error: 'Choose a file to upload.' };
+  }
+  const result = await storeUpload(file);
+  if (!result.success) return result;
+  const { key, name, size } = result.data;
+  const q = new URLSearchParams({ key, name, size: String(size) });
+  return { success: true, redirect: '/features/file-storage?' + q.toString() };
+}
+
+export default function FileStorageExample({
+  searchParams,
+  actionData,
+}: {
+  searchParams: Record<string, string | undefined>;
+  actionData?: { error?: string };
+}) {
+  const key = (searchParams.key || '').trim();
+  const name = (searchParams.name || '').trim();
+  const size = (searchParams.size || '').trim();
+  return html`
+    <h1 class="text-h2 font-bold mb-4">File storage</h1>
+    <p class="text-muted-foreground mb-4">
+      Upload a file: the bytes stream into the FileStore (a local
+      <code class="font-mono">.webjs/uploads</code> directory by default,
+      gitignored). Swap the backend for S3/R2 with one
+      <code class="font-mono">setFileStore()</code> call, no call-site change.
+    </p>
+    <form method="post" enctype="multipart/form-data" class="flex flex-wrap gap-3 items-center mb-4">
+      <input type="file" name="file" required
+        class="text-sm text-muted-foreground file:mr-3 file:px-3.5 file:py-2 file:rounded-xl file:border-0 file:bg-card file:border file:border-border file:text-foreground file:text-sm file:cursor-pointer" />
+      <button type="submit"
+        class="px-4 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-primary/90 active:scale-[0.97]">Upload</button>
+    </form>
+    ${actionData?.error
+      ? html`<p class="text-destructive text-sm mb-4">${actionData.error}</p>`
+      : ''}
+    ${key
+      ? html`
+        <div class="px-4 py-3 rounded-xl bg-card border border-border text-sm">
+          Stored <span class="text-foreground font-medium">${name}</span>
+          <span class="text-muted-foreground/70">(${size} bytes)</span>
+          <a class="text-primary no-underline ml-2" href="/features/file-storage/file/${key}">download</a>
+        </div>`
+      : ''}
+  `;
+}