@webjsdev/cli 0.10.35 → 0.10.36

package/lib/create.js

@@ -1,5 +1,5 @@
 /**
- * `webjs create <name>`: scaffold a new webjs app with opinionated defaults.
+ * `webjs create <name>`: scaffold a new WebJs app with opinionated defaults.
  *
  * Creates a directory with:
  *   - app/ with a root layout + page
@@ -7,7 +7,7 @@
  *   - components/ with a theme toggle
  *   - test/unit/ and test/e2e/ with example tests
  *   - CONVENTIONS.md, AGENTS.md, CLAUDE.md
- *   - package.json with webjs deps + test scripts
+ *   - package.json with WebJs deps + test scripts
  *   - tsconfig.json for editor support
  */
 
@@ -160,7 +160,7 @@ async function copyUiComponents(appDir, names) {
  * the scaffolded app. Merges `templates/gallery/{app,modules}` over the app so
  * single-feature demos land under `app/features/<name>/`, whole example apps
  * under `app/examples/<name>/`, and their logic under `modules/<name>/`, the
- * app-thin + modules-logic split webjs prescribes.
+ * app-thin + modules-logic split WebJs prescribes.
  *
  * Ships verbatim (no `{{APP_NAME}}` substitution): the examples are self-
  * contained and reference only `@webjsdev/*`, drizzle, `#db/*`, and each other.
@@ -392,7 +392,7 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // Bun runtime (#541): the long-running server scripts (`dev` / `start`)
       // are prefixed `bun --bun` so the app SERVES on Bun. The `--bun` overrides
       // the `webjs` bin's `#!/usr/bin/env node` shebang (without it `bun run dev`
-      // would exec webjs under Node, silently running the "bun" app on Node).
+      // would exec WebJs under Node, silently running the "bun" app on Node).
       // Baking it into the script body means a plain `bun run dev` (or even
       // `npm run dev`) starts on Bun, so a user never has to remember the flag.
       // The runtime-neutral tooling scripts below (test / db / check / typecheck
@@ -487,7 +487,7 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       noEmit: true,
       allowImportingTsExtensions: true,
       skipLibCheck: true,
-      // webjs uses Node's built-in type-stripping (`process.features.
+      // WebJs uses Node's built-in type-stripping (`process.features.
       // typescript === 'strip'`) which preserves source positions
       // byte-exactly. The constraint is that TypeScript must be
       // "erasable": no `enum`, no `namespace` with values, no
@@ -581,7 +581,7 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     '.github/pull_request_template.md',
     // CI is the test gate (the pre-commit hook only blocks main). Runs
     // webjs check + the unit / browser / e2e layers on every PR and push
-    // to main, mirroring the webjs framework's own CI.
+    // to main, mirroring the WebJs framework's own CI.
     '.github/workflows/ci.yml',
     '.editorconfig',
     // VS Code: associate the published webjs-config JSON Schema with the
@@ -1179,8 +1179,9 @@ ${UI_THEME}
          Add a new design token the canonical way, a --x variable below plus a
          --color-x: var(--x) line in the @theme inline block, then use it as bg-x /
          text-x. Reach for opacity modifiers
-         (bg-primary/10, hover:bg-primary/90, text-muted-foreground/70) before
-         inventing a new token. */
+         (bg-primary/10, hover:bg-primary/90, border-border/60) before inventing a
+         new token, but keep body text at full opacity so it stays above the AA
+         contrast floor (a faded text-muted-foreground/70 measured 3.83:1). */
       :root {
         --font-sans:  -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
         --font-serif: ui-serif, 'Iowan Old Style', Palatino, Georgia, serif;
@@ -1358,11 +1359,12 @@ export const metadata = {
 };
 
 // Two kinds of reference the scaffold ships. FEATURES are single-concept demos
-// (one webjs feature each, under app/features/, logic in modules/). EXAMPLES are
+// (one WebJs feature each, under app/features/, logic in modules/). EXAMPLES are
 // whole apps that compose several features (under app/examples/). Prune what you
 // do not use (delete the route AND its modules/<name>), then reshape this page.
 const features = [
   { href: '/features/routing', title: 'Routing', blurb: 'A static route plus a dynamic [id] segment that reads params. The file-based router in miniature.' },
+  { href: '/features/boundaries', title: 'Boundaries', blurb: 'The control-flow throws (forbidden / unauthorized / notFound) and the nearest boundary file that catches each.' },
   { href: '/features/components', title: 'Components', blurb: 'The WebComponent factory, reactive props, instance signals, and slot projection in light DOM.' },
   { href: '/features/server-actions', title: 'Server actions', blurb: 'A use-server RPC action next to a server-only .server.ts utility, and why the boundary matters.' },
   { href: '/features/optimistic-ui', title: 'Optimistic UI', blurb: 'The imperative optimistic(signal, value, action) flip: instant update, automatic rollback on failure.' },
@@ -1437,7 +1439,7 @@ export default function Home() {
 `);
   } else {
     // saas home: the auth landing (hero + login/signup/dashboard) stays the
-    // headline, and the webjs feature gallery sits BELOW it, so a saas app is
+    // headline, and the WebJs feature gallery sits BELOW it, so a saas app is
     // also a learning surface. Keep the `features` list in sync with the
     // full-stack home above (both ship the same gallery).
     await writeFile(join(appDir, 'app', 'page.ts'), `// webjs-scaffold-placeholder. This is the example homepage. Replace it with your app's real landing page, then delete this line. webjs check fails while the marker remains.
@@ -1454,12 +1456,13 @@ export const metadata = {
   title: '${displayName}: built with webjs',
 };
 
-// The webjs feature gallery, shown below the auth landing. FEATURES are
+// The WebJs feature gallery, shown below the auth landing. FEATURES are
 // single-concept demos (under app/features/, logic in modules/); EXAMPLES are
 // whole apps (under app/examples/). Prune what you do not use (delete the route
 // AND its modules/<name>). Keep this list in sync with the full-stack home.
 const features = [
   { href: '/features/routing', title: 'Routing', blurb: 'A static route plus a dynamic [id] segment that reads params. The file-based router in miniature.' },
+  { href: '/features/boundaries', title: 'Boundaries', blurb: 'The control-flow throws (forbidden / unauthorized / notFound) and the nearest boundary file that catches each.' },
   { href: '/features/components', title: 'Components', blurb: 'The WebComponent factory, reactive props, instance signals, and slot projection in light DOM.' },
   { href: '/features/server-actions', title: 'Server actions', blurb: 'A use-server RPC action next to a server-only .server.ts utility, and why the boundary matters.' },
   { href: '/features/optimistic-ui', title: 'Optimistic UI', blurb: 'The imperative optimistic(signal, value, action) flip: instant update, automatic rollback on failure.' },

package/lib/doctor.js

@@ -1,7 +1,7 @@
 /**
  * `webjs doctor`: a project-health checklist runner (issue #266).
  *
- * webjs has unusually many fragile preconditions, each an independent failure
+ * WebJs has unusually many fragile preconditions, each an independent failure
  * mode a contributor onboarding to an existing repo only hits at runtime: the
  * Node 24+ strip-types floor, the `erasableSyntaxOnly` TS flag, importmap pin
  * freshness, env drift vs `.env.example`, `@webjsdev/*` version coherence, and

package/lib/saas-template.js

@@ -27,7 +27,12 @@ async function readUiComponent(name) {
   // it to the scaffolded app's aliased path (cn lives at lib/utils/cn.ts).
   return raw
     .replaceAll("'../lib/utils.ts'", "'#lib/utils/cn.ts'")
-    .replaceAll('"../lib/utils.ts"', '"#lib/utils/cn.ts"');
+    .replaceAll('"../lib/utils.ts"', '"#lib/utils/cn.ts"')
+    // onBeforeCache lives in its own client-only module so cn() stays pure (#819).
+    // Without this rewrite dialog.ts keeps the registry-relative `../lib/dom.ts`
+    // (which resolves to a nonexistent components/lib/dom.ts) and fails typecheck.
+    .replaceAll("'../lib/dom.ts'", "'#lib/utils/dom.ts'")
+    .replaceAll('"../lib/dom.ts"', '"#lib/utils/dom.ts"');
 }
 
 /** Copy named registry components into `<appDir>/components/ui/`. */
@@ -87,6 +92,15 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "import { db } from '#db/connection.server.ts';",
     "import { compare } from './password.server.ts';",
     "",
+    "// AUTH_SECRET signs session tokens. Set a strong value in .env for any real",
+    "// deployment. The dev fallback keeps a fresh scaffold booting, but is NOT",
+    "// safe for production, so we fail fast if it is missing or blank there.",
+    "const trimmedSecret = process.env.AUTH_SECRET?.trim();",
+    "if (process.env.NODE_ENV === 'production' && !trimmedSecret) {",
+    "  throw new Error('AUTH_SECRET must be set in production');",
+    "}",
+    "const authSecret = trimmedSecret || 'dev-insecure-secret-change-me';",
+    "",
     "export const { auth, signIn, signOut, handlers } = createAuth({",
     "  providers: [",
     "    Credentials({",
@@ -97,7 +111,7 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "      },",
     "    }),",
     "  ],",
-    "  secret: process.env.AUTH_SECRET,",
+    "  secret: authSecret,",
     "});",
     "",
   ].join('\n'));
@@ -324,7 +338,7 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "    <div class=\"max-w-sm mx-auto mt-12\">",
     "      <div class=${cardClass()}>",
     "        <div class=${cardHeaderClass()}>",
-    "          <h3 class=${cardTitleClass()}>Sign in</h3>",
+    "          <h1 class=${cardTitleClass()}>Sign in</h1>",
     "          <p class=${cardDescriptionClass()}>Welcome back: log in to continue.</p>",
     "        </div>",
     "        <div class=${cardContentClass()}>",
@@ -393,7 +407,7 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "    <div class=\"max-w-sm mx-auto mt-12\">",
     "      <div class=${cardClass()}>",
     "        <div class=${cardHeaderClass()}>",
-    "          <h3 class=${cardTitleClass()}>Create an account</h3>",
+    "          <h1 class=${cardTitleClass()}>Create an account</h1>",
     "          <p class=${cardDescriptionClass()}>Get started with your new workspace.</p>",
     "        </div>",
     "        <div class=${cardContentClass()}>",
@@ -460,7 +474,7 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "    </div>",
     "    <div class=${cardClass()}>",
     "      <div class=${cardHeaderClass()}>",
-    "        <h3 class=${cardTitleClass()}>Welcome, ${user?.name || user?.email}!</h3>",
+    "        <h2 class=${cardTitleClass()}>Welcome, ${user?.name || user?.email}!</h2>",
     "        <p class=${cardDescriptionClass()}>You're authenticated. Replace this scaffold with your real app.</p>",
     "      </div>",
     "      <div class=${cardContentClass()}>",
@@ -486,7 +500,7 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "    <h1 class=\"text-2xl font-semibold mb-6\">Settings</h1>",
     "    <div class=${cardClass()}>",
     "      <div class=${cardHeaderClass()}>",
-    "        <h3 class=${cardTitleClass()}>Account</h3>",
+    "        <h2 class=${cardTitleClass()}>Account</h2>",
     "        <p class=${cardDescriptionClass()}>Your basic profile information.</p>",
     "      </div>",
     "      <div class=${cardContentClass()}>",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.35",
+  "version": "0.10.36",
   "type": "module",
   "description": "webjs CLI - dev, start, create, db",
   "bin": {

package/templates/.agents/rules/workflow.md

@@ -157,7 +157,7 @@ self-review loop.
   explicit fields plus constructor body assignments instead of parameter
   properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is
   used, the dev server fails at strip time and returns a 500 pointing at the
-  `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and
+  `no-non-erasable-typescript` lint rule. WebJs is buildless end-to-end and
   has no bundler fallback.
 - Web components render into light DOM by default (so Tailwind / global CSS
   apply directly). Opt in to shadow DOM per component with

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

@@ -149,7 +149,7 @@ each change must include.
 
 - No build step: source files are served as ES modules. Don't introduce
   build tools or bundlers in the critical path.
-- **Erasable TypeScript only.** The runtime strips types via `module.stripTypeScriptTypes` (Node's built-in, or `amaro` on Bun) (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and has no bundler fallback.
+- **Erasable TypeScript only.** The runtime strips types via `module.stripTypeScriptTypes` (Node's built-in, or `amaro` on Bun) (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. WebJs is buildless end-to-end and has no bundler fallback.
 - Tagged template: html`<div>${value}</div>` with css`...` for styles.
 - **Tailwind-first styling.** Tailwind utilities are the strong default for pages AND light-DOM components (the default DOM mode): layout, spacing, color (via `@theme` tokens), typography, borders, radius, shadows, interaction states. Light DOM does not scope, so utilities apply directly. The lit reflex to scope CSS (`static styles = css\`...\``) or write an inline `<style>` with semantic class names (`.hero`, `.card`) in a light-DOM component is wrong: the scoped block needs `static shadow = true`, and inline class names leak globally. When a utility bundle repeats, extract a `lib/utils/ui.ts` helper returning an `html` fragment, not a CSS class. Reserve raw CSS for the allowlist (design tokens / `@theme`, `@property` + `@keyframes`, `::-webkit-scrollbar`, `prefers-reduced-motion`, complex `color-mix()` / gradients); when unavoidable in a light-DOM component, prefix every class selector with the component tag. Shadow-DOM components (`static shadow = true`) legitimately author `static styles = css\`...\`` for scoped CSS; don't use inline `style="..."` there.
 - **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 theme with no 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 expect. Reach for opacity modifiers (`bg-primary/10`, `hover:bg-primary/90`) before adding a token; add one the canonical way (a `--x` var plus a `--color-x: var(--x)` line in `@theme inline`).

package/templates/AGENTS.md

@@ -342,7 +342,7 @@ app/                     ROUTING ONLY: thin route adapters (import from modules/
                          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,
+  features/<name>/       single-feature demos (routing, boundaries, components,
                          server-actions, optimistic-ui, async-render,
                          directives, route-handler, forms, metadata, caching,
                          env, client-router, service-worker); prune what you skip
@@ -405,9 +405,10 @@ instrumentation-client.ts  optional client boot hook, runs first before app modu
 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).
+  (routing, boundaries, 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).
 
@@ -501,7 +502,7 @@ an npm `prestart` hook.
 
 ### Running on Bun instead of Node
 
-webjs runs on **Node 24+ or Bun**. The same `package.json` scripts work on
+WebJs runs on **Node 24+ or Bun**. The same `package.json` scripts work on
 either; to run under Bun, force it with `--bun` so the server executes on Bun
 rather than the `webjs` bin's Node shebang:
 
@@ -1384,7 +1385,7 @@ composition, so a nested shell ends up dropped by the HTML parser.
    If you turn `erasableSyntaxOnly` off and use non-erasable syntax,
    the dev server fails at strip time and returns a 500 naming the
    file and pointing at the `no-non-erasable-typescript` lint rule.
-   webjs is buildless end-to-end and has no bundler fallback. The
+   WebJs is buildless end-to-end and has no bundler fallback. The
    `erasable-typescript-only` convention check warns when the flag
    is missing or set to false.
 9. **No em-dashes (U+2014) anywhere, and no hyphen or semicolon used

package/templates/CONVENTIONS.md

@@ -317,7 +317,7 @@ 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,
+demos, one webjs concept each (routing, boundaries, 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
@@ -430,7 +430,7 @@ features and examples as reference, never blindly up front. This is a no-op for
 ## Sensible defaults
 
 <!-- OVERRIDE -->
-webjs uses sensible defaults. Environment
+WebJs uses sensible defaults. Environment
 variables control infrastructure (no config files needed):
 
 | Environment variable | Effect |
@@ -1066,7 +1066,7 @@ auth middleware.
 
 <!-- OVERRIDE -->
 
-webjs pages work without JavaScript by design. Read-paths render to
+WebJs pages work without JavaScript by design. Read-paths render to
 real HTML on the server. Write-paths run through plain `<form>` plus
 server actions, and navigation is a real `<a href>`. Every web component
 is SSR'd too. Its `render()` runs on the server, so the component's
@@ -1248,7 +1248,7 @@ is better). See `agent-docs/advanced.md` for the full API.
     constructor(x: number) { this.x = x; }
   }
   ```
-  If you turn `erasableSyntaxOnly` off and use non-erasable syntax, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and has no bundler fallback. The `erasable-typescript-only` convention check warns when the flag is off.
+  If you turn `erasableSyntaxOnly` off and use non-erasable syntax, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. WebJs is buildless end-to-end and has no bundler fallback. The `erasable-typescript-only` convention check warns when the flag is off.
 - No semicolons (or with semicolons, pick one and stay consistent)
 - `const` by default, `let` when needed, never `var`
 - Prefer `async/await` over `.then()` chains

package/templates/gallery/app/features/boundaries/crash/page.ts

@@ -0,0 +1,7 @@
+// A page that throws a real render error, so the nearest error.ts boundary
+// (../error.ts) catches it. In a real app an unexpected throw (a failed query,
+// a bug) lands here; expected failures should return an ActionResult or throw
+// notFound() / forbidden() instead.
+export default function Crash() {
+  throw new Error('demo: this page threw during render');
+}

package/templates/gallery/app/features/boundaries/error.ts

@@ -0,0 +1,16 @@
+// error.ts is the error boundary for this segment's subtree. A render-time
+// exception in a sibling or deeper page (see crash/page.ts) is caught here and
+// rendered scoped to this boundary, so outer layouts stay alive. The default
+// export receives { error, ...ctx }; in production only error.message is sent.
+import { html } from '@webjsdev/core';
+
+export default function BoundariesError({ error }: { error: Error }) {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Something went wrong</h1>
+    <p class="text-muted-foreground mb-4">
+      This segment's <code class="font-mono">error.ts</code> boundary caught a
+      render error: <code class="font-mono">${error?.message ?? 'unknown'}</code>.
+    </p>
+    <p><a class="text-primary" href="/features/boundaries">Back to boundaries</a></p>
+  `;
+}

package/templates/gallery/app/features/boundaries/gated/forbidden.ts

@@ -0,0 +1,18 @@
+// The nearest 403 boundary for a thrown forbidden(). A forbidden.ts default-
+// exports a function returning a TemplateResult, rendered at status 403 in place
+// of the page that threw. Nearest wins: this one (inside gated/) beats any
+// forbidden.ts higher up the tree. Keep the message actionable for an
+// authenticated user who lacks permission.
+import { html } from '@webjsdev/core';
+
+export default function Forbidden() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">403 Forbidden</h1>
+    <p class="text-muted-foreground mb-4">
+      You are signed in but do not have permission to view this page. This is the
+      nearest <code class="font-mono">forbidden.ts</code> boundary, rendered
+      because the page threw <code class="font-mono">forbidden()</code>.
+    </p>
+    <p><a class="text-primary" href="/features/boundaries">Back to boundaries</a></p>
+  `;
+}

package/templates/gallery/app/features/boundaries/gated/page.ts

@@ -0,0 +1,10 @@
+// A page that throws forbidden(). In a real app you would call this only when
+// an authenticated user lacks permission (checked against the session). Here it
+// throws unconditionally so the demo always shows the 403 boundary. The nearest
+// forbidden.ts (this folder's sibling) renders in place of this page at status
+// 403; without a nearest one the framework renders a default 403 page.
+import { forbidden } from '@webjsdev/core';
+
+export default function Gated() {
+  forbidden();
+}

package/templates/gallery/app/features/boundaries/loading.ts

@@ -0,0 +1,15 @@
+// loading.ts auto-wraps the sibling page in a Suspense boundary: its default
+// export is the fallback shown while an async page (or its streamed regions)
+// resolves. The boundaries index is fast, so you rarely see this, but any async
+// page in this subtree gets this skeleton for free during navigation.
+import { html } from '@webjsdev/core';
+
+export default function BoundariesLoading() {
+  return html`
+    <div class="animate-pulse">
+      <div class="h-7 w-40 rounded bg-muted mb-4"></div>
+      <div class="h-4 w-full rounded bg-muted mb-2"></div>
+      <div class="h-4 w-3/4 rounded bg-muted"></div>
+    </div>
+  `;
+}

package/templates/gallery/app/features/boundaries/not-found.ts

@@ -0,0 +1,17 @@
+// not-found.ts is the nearest 404 boundary for this subtree. It renders both
+// for a thrown notFound() in a page below here AND for an unmatched URL under
+// /features/boundaries/ (try /features/boundaries/does-not-exist). Nearest wins,
+// so this beats the root not-found for anything in this segment.
+import { html } from '@webjsdev/core';
+
+export default function BoundariesNotFound() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">404: Not here</h1>
+    <p class="text-muted-foreground mb-4">
+      This segment's <code class="font-mono">not-found.ts</code> boundary rendered,
+      because a page threw <code class="font-mono">notFound()</code> or the URL
+      matched nothing under this segment.
+    </p>
+    <p><a class="text-primary" href="/features/boundaries">Back to boundaries</a></p>
+  `;
+}

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

@@ -0,0 +1,77 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/boundaries route), then delete this marker line. webjs check fails while the marker remains.
+// Boundaries: the four control-flow throws and their boundary files. A page (or
+// a page `action`) can THROW to short-circuit rendering, and the framework
+// renders the NEAREST matching boundary file in the route's ancestor chain
+// (innermost wins), exactly like an error boundary:
+//   notFound()      -> the nearest not-found.ts       (404)
+//   forbidden()     -> the nearest forbidden.ts       (403, authenticated but not allowed)
+//   unauthorized()  -> the nearest unauthorized.ts    (401, not authenticated)
+//   redirect(url)   -> an HTTP 3xx (no boundary file; it sends a Location)
+// Two boundaries are ROOT-ONLY, so they live at the app root, not here under a
+// feature folder: global-error.ts (the app-wide catch-all, owns its own <html>)
+// and global-not-found.ts (a 404 for a URL that matches nothing anywhere).
+//
+// This demo ships two live sub-routes. Visit each and the page throws, so you
+// see the nearest boundary render in place of the page:
+//   /features/boundaries/gated   throws forbidden()    -> gated/forbidden.ts
+//   /features/boundaries/private throws unauthorized() -> private/unauthorized.ts
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Boundaries (throws + boundary files) | features' };
+
+export default function BoundariesExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Boundaries</h1>
+    <p class="text-muted-foreground mb-4">
+      Throw a control-flow function from a page (or a page
+      <code class="font-mono">action</code>) to short-circuit the render. The
+      framework catches it and renders the nearest matching boundary file in the
+      route's chain, innermost wins.
+    </p>
+    <ul class="list-disc pl-5 mb-4">
+      <li>
+        <a class="text-primary" href="/features/boundaries/gated">/features/boundaries/gated</a>
+        throws <code class="font-mono">forbidden()</code>, caught by
+        <code class="font-mono">gated/forbidden.ts</code> (403).
+      </li>
+      <li>
+        <a class="text-primary" href="/features/boundaries/private">/features/boundaries/private</a>
+        throws <code class="font-mono">unauthorized()</code>, caught by
+        <code class="font-mono">private/unauthorized.ts</code> (401).
+      </li>
+      <li>
+        <a class="text-primary" href="/features/boundaries/crash">/features/boundaries/crash</a>
+        throws a render error, caught by this segment's
+        <code class="font-mono">error.ts</code> (500).
+      </li>
+      <li>
+        <a class="text-primary" href="/features/boundaries/does-not-exist">/features/boundaries/does-not-exist</a>
+        matches nothing, caught by the nearest
+        <code class="font-mono">not-found.ts</code> (404).
+      </li>
+    </ul>
+    <p class="text-muted-foreground text-sm mb-2">
+      <code class="font-mono">forbidden()</code> is for an authenticated user who
+      lacks permission (403); <code class="font-mono">unauthorized()</code> is for
+      a request that is not authenticated at all (401). Both import from
+      <code class="font-mono">@webjsdev/core</code> and are thrown, never returned.
+    </p>
+    <p class="text-muted-foreground text-sm mb-2">
+      Same throw model as <code class="font-mono">notFound()</code> (renders the
+      nearest <code class="font-mono">not-found.ts</code>) and
+      <code class="font-mono">redirect(url)</code> (sends an HTTP 3xx). Inside a
+      <code class="font-mono">'use server'</code> RPC action, return an
+      <code class="font-mono">ActionResult</code> for an auth failure instead of
+      throwing, since a raw throw there is a generic 500.
+    </p>
+    <p class="text-muted-foreground text-sm">
+      Two boundaries are root-only and live at the app root:
+      <code class="font-mono">app/global-error.ts</code> (the app-wide catch-all,
+      which renders its own <code class="font-mono">&lt;html&gt;</code> document)
+      and <code class="font-mono">app/global-not-found.ts</code> (a 404 for a URL
+      that matches nothing anywhere).
+    </p>
+    <p class="mt-3"><a class="text-primary" href="/">Back to the gallery</a></p>
+  `;
+}

package/templates/gallery/app/features/boundaries/private/page.ts

@@ -0,0 +1,10 @@
+// A page that throws unauthorized(). In a real app you would call this when the
+// request is not authenticated (no valid session), typically to prompt a sign-in.
+// Here it throws unconditionally so the demo always shows the 401 boundary. The
+// nearest unauthorized.ts (this folder's sibling) renders in place of this page
+// at status 401; without a nearest one the framework renders a default 401 page.
+import { unauthorized } from '@webjsdev/core';
+
+export default function Private() {
+  unauthorized();
+}

package/templates/gallery/app/features/boundaries/private/unauthorized.ts

@@ -0,0 +1,17 @@
+// The nearest 401 boundary for a thrown unauthorized(). An unauthorized.ts
+// default-exports a function returning a TemplateResult, rendered at status 401
+// in place of the page that threw. Nearest wins: this one (inside private/) beats
+// any unauthorized.ts higher up the tree. A real one usually links to sign-in.
+import { html } from '@webjsdev/core';
+
+export default function Unauthorized() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">401 Unauthorized</h1>
+    <p class="text-muted-foreground mb-4">
+      You need to sign in to view this page. This is the nearest
+      <code class="font-mono">unauthorized.ts</code> boundary, rendered because the
+      page threw <code class="font-mono">unauthorized()</code>.
+    </p>
+    <p><a class="text-primary" href="/features/boundaries">Back to boundaries</a></p>
+  `;
+}

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

@@ -8,6 +8,7 @@
 // JS off, every link is a normal full-page navigation.
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import '#modules/client-router/components/router-controls.ts';
 
 export const metadata: Metadata = { title: 'Client router (soft nav) | features' };
 
@@ -24,6 +25,8 @@ export default function ClientRouterExample() {
       <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 mb-2">Or drive it from JS with <code class="font-mono">navigate()</code> / <code class="font-mono">revalidate()</code>:</p>
+    <router-controls></router-controls>
     <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

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

@@ -2,6 +2,7 @@
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
 import '#modules/components/components/counter-card.ts';
+import '#modules/components/components/reactive-meter.ts';
 
 export const metadata: Metadata = { title: 'Components (signals + slots) | features' };
 
@@ -10,5 +11,7 @@ export default function ComponentsExample() {
     <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>
+    <p class="text-muted-foreground mt-6 mb-2">Shadow DOM (scoped <code class="font-mono">css</code>) plus the rest of the signals API (<code class="font-mono">computed</code>, <code class="font-mono">effect</code>, <code class="font-mono">batch</code>):</p>
+    <reactive-meter></reactive-meter>
   `;
 }

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

@@ -42,7 +42,7 @@ export default function FileStorageExample({
       <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
+      <input type="file" name="file" required aria-label="Choose a file to upload"
         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>
@@ -54,7 +54,7 @@ export default function FileStorageExample({
       ? 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>
+          <span class="text-muted-foreground">(${size} bytes)</span>
           <a class="text-primary no-underline ml-2" href="/features/file-storage/file/${key}">download</a>
         </div>`
       : ''}

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

@@ -26,7 +26,7 @@ const field = (label: string, name: string, input: unknown, error?: string) => h
   </div>
 `;
 
-const inputCls = 'w-full bg-background border border-border rounded-xl px-3 py-2 text-[15px] text-foreground outline-none transition-colors focus:border-primary placeholder:text-muted-foreground/70';
+const inputCls = 'w-full bg-background border border-border rounded-xl px-3 py-2 text-[15px] text-foreground outline-none transition-colors focus:border-primary placeholder:text-muted-foreground';
 
 export default function FormsFeature({ searchParams, actionData }: { searchParams: Record<string, string | undefined>; actionData?: Result }) {
   if (searchParams.sent) {

package/templates/gallery/app/features/routing/[id]/page.ts

@@ -12,12 +12,16 @@
 // params, so PageProps<'/features/routing/[id]'>['params'] narrows to
 // { id: string } automatically. Rename the folder and the type follows; pass a
 // route literal that does not exist and it is a compile error.
-import { html } from '@webjsdev/core';
+import { html, notFound } from '@webjsdev/core';
 import type { PageProps } from '@webjsdev/core';
 
 export default async function RoutingParam({ params }: PageProps<'/features/routing/[id]'>) {
   // The Next-style await also works; `params.id` sync would be identical.
   const { id } = await params;
+  // Throw notFound() to short-circuit into the nearest not-found boundary (404).
+  // Here the reserved id "missing" stands in for "no such record"; in a real app
+  // you throw this after a DB lookup returns nothing. Try /features/routing/missing.
+  if (id === 'missing') notFound();
   return html`
     <h1 class="text-h2 font-bold mb-4">Route param</h1>
     <p>The <code>[id]</code> segment is: <strong>${id}</strong></p>
@@ -28,6 +32,14 @@ export default async function RoutingParam({ params }: PageProps<'/features/rout
       <code class="font-mono">params</code> is awaitable too:
       <code class="font-mono">const { id } = await params</code> works, same value.
     </p>
+    <p class="text-muted-foreground text-sm mt-3">
+      Throwing wins over rendering: <a class="text-primary" href="/features/routing/missing">/features/routing/missing</a>
+      throws <code class="font-mono">notFound()</code> and renders the nearest
+      not-found boundary at 404. See the
+      <a class="text-primary" href="/features/boundaries">Boundaries</a> demo for
+      <code class="font-mono">forbidden()</code> and
+      <code class="font-mono">unauthorized()</code>.
+    </p>
     <p class="mt-3"><a class="text-primary" href="/features/routing">Back</a></p>
   `;
 }

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

@@ -43,5 +43,13 @@ export default function RoutingExample() {
       <code class="font-mono">redirect()</code> on the server, call
       <code class="font-mono">navigate()</code> on the client.
     </p>
+    <p class="text-muted-foreground text-sm mt-3">
+      A page can also THROW to short-circuit rendering:
+      <code class="font-mono">notFound()</code> (404),
+      <code class="font-mono">forbidden()</code> (403), and
+      <code class="font-mono">unauthorized()</code> (401), each rendering the
+      nearest matching boundary file. See the
+      <a class="text-primary" href="/features/boundaries">Boundaries</a> demo.
+    </p>
   `;
 }

package/templates/gallery/app/manifest.ts

@@ -0,0 +1,22 @@
+// webjs-scaffold-placeholder. Metadata route. Keep and adapt it, or prune it
+// (delete this file), then delete this marker line. webjs check fails while the
+// marker remains.
+//
+// app/manifest.ts serves /manifest.json (the web app manifest). The default
+// export returns an object, serialized to JSON. Adapt the name, colors, and
+// icons to your app; pair it with the opt-in service worker for an installable
+// PWA. See agent-docs/service-worker.md. (Gallery files are copied verbatim, so
+// set the real app name here by hand rather than expecting substitution.)
+export default function Manifest() {
+  return {
+    name: 'webjs app',
+    short_name: 'webjs app',
+    start_url: '/',
+    display: 'standalone',
+    background_color: '#ffffff',
+    theme_color: '#1c1613',
+    icons: [
+      { src: '/favicon.svg', sizes: 'any', type: 'image/svg+xml' },
+    ],
+  };
+}

package/templates/gallery/app/robots.ts

@@ -0,0 +1,16 @@
+// webjs-scaffold-placeholder. Metadata route. Keep and adapt it, or prune it
+// (delete this file), then delete this marker line. webjs check fails while the
+// marker remains.
+//
+// app/robots.ts serves /robots.txt. The default export returns a string (served
+// as text/plain) or an object. This example allows all crawlers and points them
+// at the sitemap. Tighten the rules (Disallow paths) for a real app.
+const SITE_URL = (process.env.SITE_URL || 'http://localhost:8080').replace(/\/$/, '');
+
+export default function Robots() {
+  return [
+    'User-agent: *',
+    'Allow: /',
+    `Sitemap: ${SITE_URL}/sitemap.xml`,
+  ].join('\n');
+}

package/templates/gallery/app/sitemap.ts

@@ -0,0 +1,23 @@
+// webjs-scaffold-placeholder. Metadata route. Keep and adapt it to your real
+// routes, or prune it (delete this file), then delete this marker line. webjs
+// check fails while the marker remains.
+//
+// app/sitemap.ts serves /sitemap.xml. The default export is a (possibly async)
+// server function; `sitemap(entries)` from @webjsdev/server serializes a
+// spec-valid XML sitemap. In a real app, build the entries from your content
+// (a query over posts/products), so new content is discoverable without editing
+// this file. Here it lists the gallery's static routes as an example.
+import { sitemap } from '@webjsdev/server';
+
+const SITE_URL = (process.env.SITE_URL || 'http://localhost:8080').replace(/\/$/, '');
+
+export default function Sitemap() {
+  const routes = ['/', '/features/routing', '/features/boundaries'];
+  return sitemap(
+    routes.map((path) => ({
+      url: `${SITE_URL}${path}`,
+      changeFrequency: 'weekly' as const,
+      priority: path === '/' ? 1.0 : 0.7,
+    })),
+  );
+}

package/templates/gallery/modules/client-router/components/router-controls.ts

@@ -0,0 +1,24 @@
+// Programmatic client navigation. `navigate(url)` does the same soft, in-place
+// swap an <a> click does, but from an event handler (after a save, a wizard
+// step, etc.). `revalidate(url?)` evicts the browser snapshot cache so the next
+// visit refetches fresh HTML instead of the cached page. Both are client-only
+// (they run in the browser), so a component is the right home; a page/layout
+// never hydrates. With JS off this component is inert, so keep real navigation
+// on plain <a href> and use navigate() only for JS-driven flows.
+import { WebComponent, html, navigate, revalidate } from '@webjsdev/core';
+
+export class RouterControls extends WebComponent {
+  render() {
+    return html`
+      <div class="flex gap-3 items-center">
+        <button
+          @click=${() => navigate('/features/client-router/second')}
+          class="inline-flex items-center px-4 py-2 rounded-xl bg-card border border-border text-foreground font-medium text-sm cursor-pointer transition-colors hover:border-border-strong">navigate() to page two</button>
+        <button
+          @click=${() => revalidate()}
+          class="text-muted-foreground font-medium text-sm cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">revalidate() the snapshot cache</button>
+      </div>
+    `;
+  }
+}
+RouterControls.register('router-controls');

package/templates/gallery/modules/components/components/counter-card.ts

@@ -24,7 +24,7 @@ export class CounterCard extends WebComponent({
         <slot></slot>
         <div class="flex items-baseline gap-2">
           <span class="text-[2.5rem] font-bold tabular-nums leading-none text-foreground">${this.count.get()}</span>
-          <span class="text-sm text-muted-foreground/70">${this.label}</span>
+          <span class="text-sm text-muted-foreground">${this.label}</span>
         </div>
         <button @click=${() => this.count.set(this.count.get() + 1)}
           class="w-fit 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]">Increment</button>

package/templates/gallery/modules/components/components/reactive-meter.ts

@@ -0,0 +1,64 @@
+// A shadow-DOM component: `static shadow = true` scopes `static styles = css\`\``
+// to this element (bare selectors do not leak out), the one place the lit reflex
+// to scope CSS is right in webjs. It also shows the rest of the signals API:
+// `computed` (a derived signal), `effect` (a browser-side reaction that runs on
+// change), and `batch` (coalesce several writes into ONE re-render).
+import { WebComponent, html, css, signal, computed, effect, batch } from '@webjsdev/core';
+
+export class ReactiveMeter extends WebComponent {
+  static shadow = true;
+  static styles = css`
+    .row { display: flex; align-items: center; gap: 8px; }
+    button {
+      padding: 6px 12px; border-radius: 10px; border: 1px solid #8883;
+      background: transparent; color: inherit; cursor: pointer; font: inherit;
+    }
+    .val { font-variant-numeric: tabular-nums; font-weight: 600; }
+    .muted { opacity: 0.6; font-size: 13px; }
+  `;
+
+  private count = signal(0);
+  // computed: recomputed lazily when count changes, cached otherwise.
+  private doubled = computed(() => this.count.get() * 2);
+  private lastLogged = signal('');
+  private disposeEffect?: () => void;
+
+  connectedCallback() {
+    super.connectedCallback();
+    // effect: runs now and again whenever a signal it reads changes. Browser-only
+    // (SSR never calls connectedCallback), so it is the place for reactive
+    // side effects.
+    this.disposeEffect = effect(() => {
+      this.lastLogged.set('count is ' + this.count.get());
+    });
+  }
+  disconnectedCallback() {
+    super.disconnectedCallback?.();
+    this.disposeEffect?.();
+  }
+
+  private bump(n: number) {
+    this.count.set(this.count.get() + n);
+  }
+  // batch: both writes commit together, so the component re-renders ONCE.
+  private reset() {
+    batch(() => {
+      this.count.set(0);
+      this.lastLogged.set('reset');
+    });
+  }
+
+  render() {
+    return html`
+      <div class="row">
+        <button @click=${() => this.bump(-1)}>-1</button>
+        <span class="val">${this.count.get()}</span>
+        <button @click=${() => this.bump(1)}>+1</button>
+        <span class="muted">doubled: ${this.doubled.get()}</span>
+        <button @click=${() => this.reset()}>reset</button>
+      </div>
+      <p class="muted">${this.lastLogged.get()}</p>
+    `;
+  }
+}
+ReactiveMeter.register('reactive-meter');

package/templates/gallery/modules/directives/components/directive-demo.ts

@@ -2,9 +2,13 @@
 // `repeat` keys a list so DOM nodes are REUSED across reorders instead of being
 // recreated (use it for keyed lists that reorder; plain `.map()` is fine for
 // static lists). `watch(signal)` does a fine-grained DOM swap of ONE node when
-// the signal changes, without re-running the whole template.
+// the signal changes, without re-running the whole template. The second card
+// shows more of the set: `live` (a controlled input), `ref` + `createRef` (a
+// handle to a DOM node), `until` (a pending fallback for a promise),
+// `unsafeHTML` (trusted raw HTML, NEVER user input), and `keyed` (force a fresh
+// subtree when a key changes).
 import { WebComponent, signal, html } from '@webjsdev/core';
-import { repeat, watch } from '@webjsdev/core/directives';
+import { repeat, watch, live, until, keyed, unsafeHTML, ref, createRef } from '@webjsdev/core/directives';
 
 interface Item { id: number; label: string }
 
@@ -17,6 +21,14 @@ export class DirectiveDemo extends WebComponent {
     { id: 3, label: 'Charlie' },
   ]);
   private ticks = signal(0);
+  // A controlled value (for `live`) and a key (for `keyed`).
+  private text = signal('type here');
+  private variant = signal(0);
+  // A handle to the input node, attached by `ref` in the browser.
+  private inputRef = createRef<HTMLInputElement>();
+  // Created ONCE (not per render), so `until` keeps the resolved value across
+  // re-renders instead of flashing back to the fallback each time.
+  private asyncValue: Promise<string> = this.later();
 
   private reverse() {
     this.items.set(this.items.get().slice().reverse());
@@ -25,27 +37,60 @@ export class DirectiveDemo extends WebComponent {
     const id = nextId++;
     this.items.set([...this.items.get(), { id, label: 'Item ' + id }]);
   }
+  private focusInput() {
+    this.inputRef.value?.focus();
+  }
+  // A promise that resolves after a tick, so `until` shows its fallback first.
+  private later(): Promise<string> {
+    return new Promise((resolve) => setTimeout(() => resolve('resolved!'), 400));
+  }
 
   render() {
+    const variant = this.variant.get();
     return html`
-      <div class="grid gap-4 max-w-[420px]">
-        <div class="flex gap-2">
-          <button @click=${() => this.reverse()}
-            class="px-3.5 py-1.5 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]">Reverse</button>
-          <button @click=${() => this.add()}
-            class="px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground font-medium text-sm cursor-pointer transition-colors hover:border-border-strong">Add</button>
+      <div class="grid gap-6 max-w-[420px]">
+        <div class="grid gap-4">
+          <div class="flex gap-2">
+            <button @click=${() => this.reverse()}
+              class="px-3.5 py-1.5 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]">Reverse</button>
+            <button @click=${() => this.add()}
+              class="px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground font-medium text-sm cursor-pointer transition-colors hover:border-border-strong">Add</button>
+          </div>
+          <!-- repeat keyed by item.id: reversing reuses the existing <li> nodes. -->
+          <ul class="grid gap-2 list-none m-0 p-0">
+            ${repeat(this.items.get(), (it: Item) => it.id, (it: Item) => html`
+              <li class="flex items-center gap-2 px-3 py-2 rounded-xl bg-card border border-border text-[15px] text-foreground">
+                <span class="text-muted-foreground tabular-nums text-[13px]">#${it.id}</span>${it.label}
+              </li>
+            `)}
+          </ul>
+          <!-- watch(signal) swaps only this node when ticks changes. -->
+          <button @click=${() => this.ticks.set(this.ticks.get() + 1)}
+            class="w-fit text-sm text-muted-foreground cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">ticks: ${watch(this.ticks)}</button>
+        </div>
+
+        <div class="grid gap-3 border-t border-border pt-4">
+          <!-- live keeps the input's DOM value tracking the signal even after the
+               user edits it, so it stays a controlled input. ref hands you the
+               node via inputRef.value once it is attached in the browser. -->
+          <div class="flex gap-2">
+            <input
+              ${ref(this.inputRef)}
+              aria-label="Editable text for the ref focus demo"
+              class="flex-1 px-3 py-1.5 rounded-xl bg-card border border-border text-[15px] text-foreground"
+              .value=${live(this.text.get())}
+              @input=${(e: Event) => this.text.set((e.target as HTMLInputElement).value)}>
+            <button @click=${() => this.focusInput()}
+              class="px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground text-sm cursor-pointer transition-colors hover:border-border-strong">Focus</button>
+          </div>
+          <!-- until shows the fallback until the promise resolves. -->
+          <p class="text-sm text-muted-foreground">async: ${until(this.asyncValue, 'loading...')}</p>
+          <!-- keyed discards and rebuilds this subtree when the key changes;
+               unsafeHTML injects trusted, author-written HTML (NEVER user input). -->
+          <button @click=${() => this.variant.set(variant + 1)}
+            class="w-fit text-sm text-muted-foreground cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">rekey</button>
+          ${keyed(variant, html`<div class="text-[15px] text-foreground">${unsafeHTML('<em>fresh subtree</em>')} #${variant}</div>`)}
         </div>
-        <!-- repeat keyed by item.id: reversing reuses the existing <li> nodes. -->
-        <ul class="grid gap-2 list-none m-0 p-0">
-          ${repeat(this.items.get(), (it: Item) => it.id, (it: Item) => html`
-            <li class="flex items-center gap-2 px-3 py-2 rounded-xl bg-card border border-border text-[15px] text-foreground">
-              <span class="text-muted-foreground/70 tabular-nums text-[13px]">#${it.id}</span>${it.label}
-            </li>
-          `)}
-        </ul>
-        <!-- watch(signal) swaps only this node when ticks changes. -->
-        <button @click=${() => this.ticks.set(this.ticks.get() + 1)}
-          class="w-fit text-sm text-muted-foreground cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">ticks: ${watch(this.ticks)}</button>
       </div>
     `;
   }

package/templates/gallery/modules/rate-limit/components/rate-probe.ts

@@ -38,7 +38,7 @@ export class RateProbe extends WebComponent {
             <li class="flex items-center justify-between px-3 py-2 rounded-xl bg-card border border-border text-sm">
               <span class="text-muted-foreground">#${p.n}</span>
               <span class="font-mono ${p.status === 429 ? 'text-destructive' : 'text-primary'}">${p.status === 429 ? '429 limited' : '200 ok'}</span>
-              <span class="text-muted-foreground/70 text-[13px]">remaining: ${p.remaining}</span>
+              <span class="text-muted-foreground text-[13px]">remaining: ${p.remaining}</span>
             </li>
           `)}
         </ul>

package/templates/gallery/modules/server-actions/components/greeter.ts

@@ -18,7 +18,7 @@ export class Greeter extends WebComponent {
         <form @submit=${(e: SubmitEvent) => this.run(e)}
           class="flex items-center gap-2 p-2 pl-4 rounded-2xl bg-card border border-border">
           <input name="name" placeholder="your name" autocomplete="off"
-            class="flex-1 min-w-0 bg-transparent border-0 outline-none text-foreground text-[15px] placeholder:text-muted-foreground/70 py-1.5" />
+            class="flex-1 min-w-0 bg-transparent border-0 outline-none text-foreground text-[15px] placeholder:text-muted-foreground py-1.5" />
           <button type="submit"
             class="shrink-0 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]">Greet</button>
         </form>

package/templates/gallery/modules/todo/components/todo-app.ts

@@ -82,7 +82,7 @@ export class TodoApp extends WebComponent({
             </span>
             <div class="grid gap-0.5">
               <h2 class="m-0 text-[1.4rem] font-bold tracking-[-0.02em] leading-none text-foreground">Tasks</h2>
-              <p class="m-0 text-[13px] text-muted-foreground/70 leading-none">${done} of ${list.length} done</p>
+              <p class="m-0 text-[13px] text-muted-foreground leading-none">${done} of ${list.length} done</p>
             </div>
             <span class="ml-auto text-[13px] font-semibold tabular-nums text-muted-foreground">${pct}%</span>
           </div>
@@ -97,7 +97,7 @@ export class TodoApp extends WebComponent({
           class="flex items-center gap-2 p-2 pl-4 rounded-2xl bg-card border border-border shadow-[0_1px_0_0_color-mix(in_oklch,var(--foreground)_5%,transparent)]">
           <input type="hidden" name="intent" value="create" />
           <input name="title" required maxlength="280" autocomplete="off" placeholder="What needs doing?"
-            class="flex-1 min-w-0 bg-transparent border-0 outline-none text-foreground text-[15px] placeholder:text-muted-foreground/70 py-1.5" />
+            class="flex-1 min-w-0 bg-transparent border-0 outline-none text-foreground text-[15px] placeholder:text-muted-foreground py-1.5" />
           <button type="submit"
             class="shrink-0 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]">Add</button>
         </form>
@@ -120,17 +120,17 @@ export class TodoApp extends WebComponent({
                 </button>
                 <!-- The title is a <label for> the toggle: clicking the text toggles
                      the task (works on JS and no-JS paths, and screen readers). -->
-                <label for="t-${todo.id}" class="flex-1 min-w-0 text-[15px] leading-snug break-words cursor-pointer select-none ${todo.completed ? 'line-through text-muted-foreground/70' : 'text-foreground'}">${todo.title}</label>
+                <label for="t-${todo.id}" class="flex-1 min-w-0 text-[15px] leading-snug break-words cursor-pointer select-none ${todo.completed ? 'line-through text-muted-foreground' : 'text-foreground'}">${todo.title}</label>
                 <!-- Delete: a proper icon button, revealed on row hover / focus. -->
                 <button type="submit" name="intent" value="delete" aria-label="Delete task"
                   @click=${(e: Event) => this.removeTodo(e, todo)}
-                  class="shrink-0 grid place-items-center w-7 h-7 rounded-lg border-0 bg-transparent text-muted-foreground/70 cursor-pointer opacity-0 group-hover:opacity-100 focus:opacity-100 transition-all hover:text-destructive hover:bg-[color-mix(in_oklch,var(--color-destructive)_12%,transparent)]">
+                  class="shrink-0 grid place-items-center w-7 h-7 rounded-lg border-0 bg-transparent text-muted-foreground cursor-pointer opacity-0 group-hover:opacity-100 focus:opacity-100 transition-all hover:text-destructive hover:bg-[color-mix(in_oklch,var(--color-destructive)_12%,transparent)]">
                   <svg viewBox="0 0 24 24" class="w-4 h-4 stroke-current fill-none" style="stroke-width:2;stroke-linecap:round;stroke-linejoin:round"><path d="M18 6 6 18M6 6l12 12"/></svg>
                 </button>
               </form>
             </li>
           `) : html`
-            <li class="text-center text-muted-foreground/70 text-sm py-14 border border-dashed border-border rounded-2xl">No tasks yet. Add your first one above.</li>
+            <li class="text-center text-muted-foreground text-sm py-14 border border-dashed border-border rounded-2xl">No tasks yet. Add your first one above.</li>
           `}
         </ul>
       </section>