@webjsdev/cli 0.10.35 → 0.10.37

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
@@ -539,6 +539,8 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     'test/hello/browser/hello.test.js',
     'test/hello/e2e/hello.test.ts',
     'web-test-runner.config.js',
+    // Optional boot-time APM hook (setOnError). Delete if unused.
+    'instrumentation.ts',
     // Environment variables
     '.env.example',
     // Project-level gitignore (node_modules, .webjs, .env, OS junk).
@@ -581,7 +583,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 +1181,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 +1361,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.' },
@@ -1379,6 +1383,7 @@ const features = [
   { href: '/features/broadcast', title: 'Broadcast', blurb: 'Fan a message out to every connected client on a WebSocket path, so all open tabs stay in sync.' },
   { href: '/features/rate-limit', title: 'Rate limiting', blurb: 'The rateLimit() middleware scoped to one endpoint, returning a 429 with Retry-After past the window.' },
   { href: '/features/file-storage', title: 'File storage', blurb: 'A no-JS multipart upload streamed into the FileStore, then served back through a streaming route.' },
+  { href: '/features/sessions', title: 'Sessions', blurb: 'A signed-cookie session applied by a segment middleware, read and written per visitor with getSession() in a route.' },
 ];
 const examples = [
   { href: '/examples/todo', title: 'Optimistic todo', blurb: 'A whole app composing several features: the declarative optimistic() list API, progressive-enhancement forms, accessible labels, the modules split, and SQLite.' },
@@ -1437,7 +1442,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 +1459,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.' },
@@ -1476,6 +1482,7 @@ const features = [
   { href: '/features/broadcast', title: 'Broadcast', blurb: 'Fan a message out to every connected client on a WebSocket path, so all open tabs stay in sync.' },
   { href: '/features/rate-limit', title: 'Rate limiting', blurb: 'The rateLimit() middleware scoped to one endpoint, returning a 429 with Retry-After past the window.' },
   { href: '/features/file-storage', title: 'File storage', blurb: 'A no-JS multipart upload streamed into the FileStore, then served back through a streaming route.' },
+  { href: '/features/sessions', title: 'Sessions', blurb: 'A signed-cookie session applied by a segment middleware, read and written per visitor with getSession() in a route.' },
 ];
 const examples = [
   { href: '/examples/todo', title: 'Optimistic todo', blurb: 'A whole app composing several features: the declarative optimistic() list API, progressive-enhancement forms, accessible labels, the modules split, and SQLite.' },

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/`. */
@@ -83,10 +88,19 @@ export async function writeSaasFiles(appDir, opts = {}) {
 
   // lib/auth.server.ts
   await writeFile(join(appDir, 'lib', 'auth.server.ts'), [
-    "import { createAuth, Credentials } from '@webjsdev/server';",
+    "import { createAuth, Credentials, GitHub, Google } from '@webjsdev/server';",
     "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({",
@@ -96,8 +110,14 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "        return { id: String(user.id), name: user.name, email: user.email };",
     "      },",
     "    }),",
+    "    // OAuth providers: add GitHub / Google sign-in by setting the matching",
+    "    // env vars. Each preset (GitHub(), Google()) reads AUTH_<PROVIDER>_ID /",
+    "    // _SECRET, so they only activate once configured and a fresh scaffold",
+    "    // still boots with just Credentials.",
+    "    ...(process.env.AUTH_GITHUB_ID ? [GitHub({ clientId: process.env.AUTH_GITHUB_ID, clientSecret: process.env.AUTH_GITHUB_SECRET })] : []),",
+    "    ...(process.env.AUTH_GOOGLE_ID ? [Google({ clientId: process.env.AUTH_GOOGLE_ID, clientSecret: process.env.AUTH_GOOGLE_SECRET })] : []),",
     "  ],",
-    "  secret: process.env.AUTH_SECRET,",
+    "  secret: authSecret,",
     "});",
     "",
   ].join('\n'));
@@ -324,7 +344,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 +413,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 +480,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 +506,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.37",
   "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/apple-icon.ts

@@ -0,0 +1,17 @@
+// 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/apple-icon.ts serves /apple-icon (the Apple touch icon iOS uses when a
+// visitor adds the site to their home screen). Apple expects a 180x180 square
+// with no rounded corners (iOS rounds them). Same shape as icon.ts: return a
+// Response with the exact content type. Swap the inline SVG for your real mark.
+export default function AppleIcon() {
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="180" height="180" viewBox="0 0 180 180">
+    <rect width="180" height="180" fill="#1c1613"/>
+    <text x="90" y="120" font-family="system-ui, sans-serif" font-size="104" font-weight="700" fill="#ff8a3d" text-anchor="middle">w</text>
+  </svg>`;
+  return new Response(svg, {
+    headers: { 'content-type': 'image/svg+xml', 'cache-control': 'public, max-age=3600' },
+  });
+}

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

@@ -1,14 +1,24 @@
 // 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 { html, Suspense } 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' };
 
+// A slow server region. Suspense flushes the fallback on the first byte and
+// streams the resolved content in when it settles, so a slow query does not
+// block the whole page's first paint. Multiple boundaries stream concurrently.
+async function slowRegion() {
+  await new Promise((r) => setTimeout(r, 800));
+  return html`<p class="text-foreground">Streamed in after the first byte.</p>`;
+}
+
 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>
+    <p class="text-muted-foreground mt-6 mb-2">For a SLOW region where blocking the first byte hurts, wrap it in <code class="font-mono">Suspense</code> to stream it instead:</p>
+    ${Suspense({ fallback: html`<p class="text-muted-foreground">loading slow region…</p>`, children: slowRegion() })}
   `;
 }

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/caching/page.ts

@@ -8,6 +8,7 @@
 // use HTTP Cache-Control + ETag (conditional GET).
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import '#modules/caching/components/cache-buster.ts';
 
 export const metadata: Metadata = { title: 'Caching (revalidate) | features' };
 
@@ -35,5 +36,13 @@ export default function CachingExample() {
       <code>revalidateTag</code>, or a GET action's
       <code>export const cache</code>.
     </p>
+    <p class="text-muted-foreground text-sm mt-6 mb-2">
+      A mutation evicts the cache on demand. Click below (it calls
+      <code class="font-mono">revalidatePath('/features/caching')</code>), then refresh:
+      the timestamp updates immediately, even inside the 10s window, because the
+      cached HTML was dropped. Without clicking, the refresh serves the cached
+      copy until the window elapses.
+    </p>
+    <cache-buster></cache-buster>
   `;
 }

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