@webjsdev/cli 0.10.45 → 0.10.46

package/templates/gallery/modules/gallery/nav.ts

@@ -0,0 +1,79 @@
+/**
+ * The gallery's demo index, ONE source of truth for both the home cards and the
+ * left sidebar (so they can never drift). A browser-safe data module (no server
+ * imports, no client globals): the home flattens the groups into its card grid,
+ * and <gallery-nav> renders them grouped. gallery:clear removes this module.
+ */
+export interface NavItem { href: string; title: string; blurb: string; }
+export interface NavGroup { label: string; items: NavItem[]; }
+
+export const FEATURE_GROUPS: NavGroup[] = [
+  {
+    label: 'Routing',
+    items: [
+      { 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/metadata', title: 'Metadata', blurb: 'Static metadata plus generateMetadata(ctx), which reads the request to compute the title and Open Graph tags.' },
+    ],
+  },
+  {
+    label: 'Components',
+    items: [
+      { href: '/features/components', title: 'Components', blurb: 'The WebComponent factory, reactive props, instance signals, and slot projection in light DOM.' },
+      { href: '/features/directives', title: 'Directives', blurb: 'The lit-html directive set: repeat for keyed lists, watch(signal) for a fine-grained node swap.' },
+      { href: '/features/async-render', title: 'Async render', blurb: 'A component that awaits server data in async render(), so the resolved value is in the first paint.' },
+    ],
+  },
+  {
+    label: 'Data & actions',
+    items: [
+      { 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/route-handler', title: 'Route handlers', blurb: 'A server-only route.ts HTTP endpoint returning JSON, the WebJs equivalent of a Next route handler.' },
+      { href: '/features/forms', title: 'Forms', blurb: 'A no-JS progressive-enhancement form posting to the page action, with server-side validation errors.' },
+      { href: '/features/optimistic-ui', title: 'Optimistic UI', blurb: 'The imperative optimistic(signal, value, action) flip: instant update, automatic rollback on failure.' },
+    ],
+  },
+  {
+    label: 'Client & streaming',
+    items: [
+      { href: '/features/client-router', title: 'Client router', blurb: 'Automatic soft navigation: fragment-only fetches, hover prefetch, scroll restore, and graceful no-JS fallback.' },
+      { href: '/features/view-transitions', title: 'View transitions', blurb: 'The opt-in view-transition meta cross-fades a soft navigation, with a data-webjs-permanent element persisted across the swap.' },
+      { href: '/features/streaming', title: 'Streaming actions', blurb: 'A use-server action that returns an async generator, streamed to the call site token by token with for await.' },
+      { href: '/features/stream', title: 'Stream updates', blurb: 'The <webjs-stream> element: renderStream() applies surgical append / replace / remove DOM updates by target id, no region redraw.' },
+      { href: '/features/suspense', title: 'Suspense boundary', blurb: 'The <webjs-suspense> element: a first-paint fallback for a SLOW component, with the resolved content streamed in.' },
+      { href: '/features/frames', title: 'Frames', blurb: 'A webjs-frame region that swaps a filtered sub-list in place from a link, shipping zero component JS, with a no-JS full-nav fallback.' },
+    ],
+  },
+  {
+    label: 'Real-time',
+    items: [
+      { href: '/features/websockets', title: 'WebSockets', blurb: 'A WS(ws, req) route endpoint plus the connectWS() client, echoing messages over a live socket.' },
+      { 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.' },
+    ],
+  },
+  {
+    label: 'Auth & sessions',
+    items: [
+      { href: '/features/auth', title: 'Auth', blurb: 'Password login on createAuth, a signed session cookie, and a real protected route that redirects anonymous visitors to login.' },
+      { 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.' },
+    ],
+  },
+  {
+    label: 'Built-ins',
+    items: [
+      { href: '/features/caching', title: 'Caching', blurb: 'export const revalidate caches the page HTML per URL, with the safety rule for when a shared cache is allowed.' },
+      { href: '/features/env', title: 'Env vars', blurb: 'The server-only vs WEBJS_PUBLIC_ boundary, read during SSR so secrets never reach the browser.' },
+      { 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/service-worker', title: 'Service worker', blurb: 'The opt-in offline enhancement, registered from a browser-only lifecycle hook (never a page or layout).' },
+    ],
+  },
+];
+
+/** The whole example apps (composed features), shown after the single-feature demos. */
+export const EXAMPLES: NavItem[] = [
+  { 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.' },
+];
+
+/** Flattened single-feature list (for the home card grid). */
+export const FEATURES: NavItem[] = FEATURE_GROUPS.flatMap((g) => g.items);

package/templates/gallery/modules/optimistic-ui/components/like-button.ts

@@ -9,6 +9,8 @@
 // see the declarative optimistic(host, { source, update }) + .add() form in the
 // /examples/todo app.
 import { WebComponent, signal, optimistic, html } from '@webjsdev/core';
+import { cn } from '#lib/utils/cn.ts';
+import { buttonClass } from '#components/ui/button.ts';
 import { likePost } from '../actions/like-post.server.ts';
 
 export class LikeButton extends WebComponent {
@@ -23,9 +25,25 @@ export class LikeButton extends WebComponent {
 
   render() {
     const liked = this.liked.get();
+    // Build ON the design system, do not re-implement it. The like toggle IS the
+    // button variants: unliked reads as `secondary` (card surface), liked as
+    // `default` (primary fill). So compose buttonClass() for the base + colors +
+    // focus ring + cursor, then override only the genuinely bespoke bits with cn()
+    // (which tailwind-merges): a pill radius over the helper's rounded-xl, and a
+    // border on the liked state. The border is GEOMETRY, not decoration: the
+    // `secondary` variant carries a 1px border and `default` carries none, so under
+    // box-sizing border-box an auto-width inline-flex button would change its outer
+    // size by ~1px each toggle (a small label jitter). Re-adding `border
+    // border-primary` keeps a 1px border in both states so the pill stays put. On
+    // the primary fill that border color matches the fill, so it reads as invisible,
+    // doing only the no-jitter job. Only the heart SVG stays fully custom.
     return html`
       <button @click=${() => this.toggle()} aria-pressed=${liked ? 'true' : 'false'}
-        class="inline-flex items-center gap-2 px-4 py-2 rounded-full font-semibold text-sm border cursor-pointer transition-all active:scale-[0.97] ${liked ? 'bg-primary text-primary-foreground border-primary' : 'bg-card text-foreground border-border hover:border-border-strong'}">
+        class=${cn(
+          buttonClass({ variant: liked ? 'default' : 'secondary' }),
+          'rounded-full',
+          liked && 'border border-primary',
+        )}>
         <svg viewBox="0 0 24 24" class="w-4 h-4 ${liked ? 'fill-current stroke-none' : 'fill-none stroke-current'}" style="stroke-width:2;stroke-linecap:round;stroke-linejoin:round"><path d="M20.8 4.6a5.5 5.5 0 0 0-7.8 0L12 5.7l-1-1.1a5.5 5.5 0 0 0-7.8 7.8l1.1 1L12 21l7.7-7.6 1.1-1a5.5 5.5 0 0 0 0-7.8Z"/></svg>
         ${liked ? 'Liked' : 'Like'}
       </button>

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

@@ -5,6 +5,7 @@
 // import and call instead). The button is the interactivity signal, so this
 // component ships and hydrates.
 import { WebComponent, signal, html } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 
 interface Probe { n: number; status: number; remaining: string }
 
@@ -32,7 +33,7 @@ export class RateProbe extends WebComponent {
     return html`
       <div class="grid gap-4 max-w-[420px]">
         <button @click=${() => this.ping()}
-          class="w-fit px-3.5 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]">Ping the endpoint</button>
+          class="${buttonClass({ size: 'sm' })} w-fit">Ping the endpoint</button>
         <ul class="grid gap-1.5 list-none m-0 p-0">
           ${this.log.get().map((p) => html`
             <li class="flex items-center justify-between px-3 py-2 rounded-xl bg-card border border-border text-sm">

package/templates/gallery/modules/route-handler/components/rich-data.ts

@@ -6,6 +6,7 @@
 // (it runs in the browser), so it lives in a component; with JS off this button
 // is inert and the page still reads.
 import { WebComponent, signal, html, richFetch } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 
 interface RichPayload { at: Date; ip: string; requestId: string; cookieCount: number }
 
@@ -22,7 +23,7 @@ export class RichData extends WebComponent {
     return html`
       <div class="flex items-center gap-3 text-[15px]">
         <button @click=${() => this.load()}
-          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]">richFetch() the route</button>
+          class=${buttonClass({ size: 'sm' })}>richFetch() the route</button>
         <span class="text-muted-foreground">${this.line.get()}</span>
       </div>
     `;

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

@@ -1,6 +1,9 @@
 // Calls the 'use server' action via a normal import (the RPC stub). Never
 // hand-write fetch(); importing the action IS the API.
 import { WebComponent, signal, html } from '@webjsdev/core';
+import { cardClass } from '#components/ui/card.ts';
+import { buttonClass } from '#components/ui/button.ts';
+import { bareInputClass } from '#components/ui/input.ts';
 import { greet } from '../actions/greet.server.ts';
 
 export class Greeter extends WebComponent {
@@ -21,13 +24,13 @@ export class Greeter extends WebComponent {
     return html`
       <div class="grid gap-3 max-w-[420px]">
         <form @submit=${(e: SubmitEvent) => this.run(e)}
-          class="flex items-center gap-2 p-2 pl-4 rounded-2xl bg-card border border-border">
+          class="${cardClass()} flex items-center gap-2 p-2 pl-4">
           <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 py-1.5" />
+            class=${bareInputClass()} />
           <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>
+            class="${buttonClass()} shrink-0">Greet</button>
         </form>
-        <p class="m-0 text-sm text-muted-foreground">The action is gated by requireAuth. <a class="text-primary" href="/features/auth/login">Sign in</a> to greet; signed out returns a real 401.</p>
+        <p class="m-0 text-sm text-muted-foreground">The action is gated by requireAuth. <a class="text-primary underline underline-offset-2" href="/features/auth/login">Sign in</a> to greet; signed out returns a real 401.</p>
         ${this.msg.get() ? html`<p class="m-0 font-semibold text-foreground">${this.msg.get()}</p>` : ''}
       </div>
     `;

package/templates/gallery/modules/stream/components/stream-demo.ts

@@ -12,6 +12,7 @@
 // That is the whole point: out-of-band updates that a signal re-render or a frame
 // region-swap would clobber.
 import { WebComponent, html, renderStream } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 
 // Build a <webjs-stream> payload string. It is a plain string (NOT an html``
 // template), so interpolating the row markup here is fine. `remove` needs no
@@ -30,11 +31,15 @@ export class StreamDemo extends WebComponent {
   // component and blow away the streamed-in rows.
   #n = 2;
 
-  append() {
+  // NOTE the method names: NOT append() / prepend(). Those are native
+  // ParentNode methods, and WebJs instruments them on every light-DOM host for
+  // the slot API (#1021), so a component method of the same name is shadowed and
+  // never runs. Name your handlers something else (see muscle-memory-gotchas).
+  appendRow() {
     this.#n++;
     renderStream(streamPayload('append', 'stream-list', row(`row-${this.#n}`, `Row ${this.#n} (appended)`)));
   }
-  prepend() {
+  prependRow() {
     this.#n++;
     renderStream(streamPayload('prepend', 'stream-list', row(`row-${this.#n}`, `Row ${this.#n} (prepended)`)));
   }
@@ -53,12 +58,12 @@ export class StreamDemo extends WebComponent {
   }
 
   render() {
-    const btn = 'px-3 py-1.5 rounded-lg bg-card border border-border text-sm font-medium text-foreground cursor-pointer transition-colors hover:border-border-strong';
+    const btn = buttonClass({ variant: 'secondary', size: 'xs' });
     return html`
       <div class="grid gap-4 max-w-[460px]">
         <div class="flex flex-wrap gap-2">
-          <button class=${btn} @click=${() => this.append()}>Append</button>
-          <button class=${btn} @click=${() => this.prepend()}>Prepend</button>
+          <button class=${btn} @click=${() => this.appendRow()}>Append</button>
+          <button class=${btn} @click=${() => this.prependRow()}>Prepend</button>
           <button class=${btn} @click=${() => this.replaceFirst()}>Replace Row 1</button>
           <button class=${btn} @click=${() => this.removeSecond()}>Remove Row 2</button>
           <button class=${btn} @click=${() => this.reset()}>Reset</button>

package/templates/gallery/modules/streaming/components/token-stream.ts

@@ -6,6 +6,8 @@
 // the button is inert and the empty output renders (streaming is inherently a
 // JS behaviour), so nothing here breaks the no-JS first paint.
 import { WebComponent, signal, html } from '@webjsdev/core';
+import { cardClass } from '#components/ui/card.ts';
+import { buttonClass } from '#components/ui/button.ts';
 import { streamTokens } from '../actions/stream-tokens.server.ts';
 
 export class TokenStream extends WebComponent {
@@ -29,16 +31,21 @@ export class TokenStream extends WebComponent {
 
   render() {
     const busy = this.busy.get();
+    const output = this.output.get();
+    // Only reserve the output area once streaming starts (or has produced text),
+    // so an idle demo has no empty box below the button.
     return html`
-      <div class="rounded-2xl border border-border bg-card p-5">
+      <div class="${cardClass()} p-5">
         <button
           @click=${() => this.run()}
           ?disabled=${busy}
-          class="inline-flex items-center px-4 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm transition-all hover:bg-primary/90 active:scale-[0.97] disabled:opacity-60"
+          class=${buttonClass()}
         >
           ${busy ? 'streaming…' : 'Stream tokens'}
         </button>
-        <pre class="mt-4 whitespace-pre-wrap font-mono text-sm text-foreground min-h-[3rem]">${this.output.get()}</pre>
+        ${busy || output
+          ? html`<pre class="mt-4 whitespace-pre-wrap font-mono text-sm text-foreground">${output}</pre>`
+          : ''}
       </div>
     `;
   }

package/templates/gallery/modules/suspense/components/slow-fact.ts

@@ -7,11 +7,12 @@
 // navigation too). Same component either way; the boundary is what changes the
 // SSR behaviour from block to stream.
 import { WebComponent, html } from '@webjsdev/core';
+import { cardClass } from '#components/ui/card.ts';
 
 export class SlowFact extends WebComponent {
   async render() {
     await new Promise((r) => setTimeout(r, 900));
-    return html`<p class="rounded-2xl border border-border bg-card p-5 text-foreground">
+    return html`<p class="${cardClass()} p-5 text-foreground">
       The answer, after a slow lookup, is <strong>42</strong>.
     </p>`;
   }

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

@@ -10,6 +10,10 @@
 // one coherent theme. Prefer these tokens (and opacity modifiers like
 // bg-primary/90) over ad-hoc colors.
 import { WebComponent, prop, optimistic, html } from '@webjsdev/core';
+import { cardClass } from '#components/ui/card.ts';
+import { buttonClass } from '#components/ui/button.ts';
+import { bareInputClass } from '#components/ui/input.ts';
+import { cn } from '#lib/utils/cn.ts';
 import { createTodo } from '../actions/create-todo.server.ts';
 import { toggleTodo } from '../actions/toggle-todo.server.ts';
 import { deleteTodo } from '../actions/delete-todo.server.ts';
@@ -94,12 +98,12 @@ export class TodoApp extends WebComponent({
         <!-- Add: a real <form> so it works with JS off (posts to the page action);
              with JS, @submit intercepts and runs the optimistic path. -->
         <form method="post" action="" @submit=${(e: SubmitEvent) => this.add(e)}
-          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)]">
+          class="${cardClass()} flex items-center gap-2 p-2 pl-4 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 py-1.5" />
+            class=${bareInputClass()} />
           <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>
+            class="${buttonClass()} shrink-0">Add</button>
         </form>
 
         <ul class="list-none m-0 p-0 grid gap-2">
@@ -124,7 +128,7 @@ export class TodoApp extends WebComponent({
                 <!-- 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 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=${cn(buttonClass({ variant: 'destructive', size: 'none' }), 'w-7 h-7 rounded-lg opacity-0 group-hover:opacity-100 focus:opacity-100')}>
                   <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>

package/templates/gallery/modules/websockets/components/ws-echo.ts

@@ -5,6 +5,8 @@
 // component renders its disconnected state, so with JS off the page still reads
 // (a live socket has no no-JS equivalent, which is the honest fallback here).
 import { WebComponent, signal, html, connectWS, renderStream } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
+import { inputClass } from '#components/ui/input.ts';
 
 export class WsEcho extends WebComponent {
   private connected = signal(false);
@@ -59,9 +61,9 @@ export class WsEcho extends WebComponent {
         </div>
         <form @submit=${(e: SubmitEvent) => this.send(e)} class="flex gap-2">
           <input name="msg" autocomplete="off" placeholder="Say something"
-            class="flex-1 px-3 py-2 rounded-xl bg-card border border-border text-foreground text-sm outline-none focus:border-border-strong" />
+            class=${inputClass('flex-1 min-w-0')} />
           <button type="submit"
-            class="px-3.5 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]">Send</button>
+            class=${buttonClass({ size: 'sm' })}>Send</button>
         </form>
         <ul class="grid gap-1.5 list-none m-0 p-0">
           ${this.lines.get().map((line) => html`
@@ -70,7 +72,7 @@ export class WsEcho extends WebComponent {
         </ul>
         <div class="grid gap-2 border-t border-border pt-4">
           <button @click=${() => this.applyStreamUpdate()}
-            class="w-fit 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">renderStream() an element-level update</button>
+            class="${buttonClass({ variant: 'secondary', size: 'sm' })} w-fit">renderStream() an element-level update</button>
           <ul id="ws-stream-log" class="grid gap-1.5 list-none m-0 p-0"></ul>
         </div>
       </div>

package/templates/public/favicon.svg

@@ -1,5 +1,12 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32" role="img" aria-label="WebJs">
-  <rect width="32" height="32" rx="7" fill="#e9edf0"/>
-  <path d="M8 11.5l4.5 4.5L8 20.5" fill="none" stroke="#1e2226" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"/>
-  <line x1="15.5" y1="21.5" x2="23" y2="21.5" stroke="#1e2226" stroke-width="2.6" stroke-linecap="round"/>
+  <!-- Matches the gallery navbar brand mark (a rounded square with a
+       foreground -> muted-foreground gradient), using the DARK-theme token
+       values (#dee2e6 -> #94989c) so it reads on a dark browser tab bar. -->
+  <defs>
+    <linearGradient id="wj" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#dee2e6"/>
+      <stop offset="1" stop-color="#94989c"/>
+    </linearGradient>
+  </defs>
+  <rect width="32" height="32" rx="10" fill="url(#wj)"/>
 </svg>

package/templates/scripts/clear-gallery.mjs

@@ -9,18 +9,38 @@
 // same patterns and SURVIVES this reset, so nothing is lost), then run this
 // once to shed the gallery, then grow the app in place.
 //
-// It removes the gallery routes + modules + demo metadata routes, resets
-// app/page.ts to a minimal home, and drops the demo `todos` table plus the auth
-// card's `passwordHash` column from the schema. It KEEPS the agent skill
-// (.agents/skills/webjs/), the layout, the database wiring, the theme toggle, and
-// the example `users` table. It is a one-time reset: if the gallery is already
-// gone (no app/features/) it does nothing, so a rerun never clobbers an app you
-// built.
-import { rmSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+// It strips the app down to a TRULY BAREBONES blank slate: it removes the
+// gallery routes + modules + demo metadata routes, the gallery's example design
+// system (components/ui/), the example theme-toggle component, the example test
+// suite (test/hello/), and every empty leftover dir, then resets app/page.ts to
+// a minimal home AND app/layout.ts to a blank-slate base (the gallery's navbar,
+// theme toggle, Google Fonts, AND design-token palette dropped: the reset layout
+// carries NO design system, just the OS light/dark system colours, so the agent
+// builds the palette as its own, guided by the skill), and drops the demo `todos`
+// table plus the auth card's `passwordHash` column from the schema. It KEEPS only
+// the buildable base: the agent skill (.agents/skills/webjs/), the reset root
+// layout (the Tailwind wiring + a system-colour base, no tokens), the database
+// wiring, the example `users` table, and `lib/utils/cn.ts` (the `webjs ui add`
+// prerequisite).
+//
+// Why strip so much: the demos, the design system, and the example component /
+// tests are all EXAMPLES to learn FROM, not a base to inherit. Leaving them
+// nudges the implementing agent to lean on the scaffold's choices instead of
+// building the app's own. The DURABLE knowledge is the pattern itself, which
+// lives in the skill (.agents/skills/webjs/, re-read every session): learn it
+// from the gallery here, then after this reset build your own (run
+// `webjs ui add <name>` for UI primitives, cn.ts is kept for it) themed to your
+// app. It is a one-time reset: if the gallery is already gone (no app/features/)
+// it does nothing, so a rerun never clobbers an app you built.
+import { rmSync, rmdirSync, existsSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 
 const root = process.cwd();
 const rm = (p) => { if (existsSync(join(root, p))) { rmSync(join(root, p), { recursive: true, force: true }); return true; } return false; };
+// Remove a directory ONLY if it exists and is empty (used to clean the empty
+// parents a partial gallery removal leaves behind, e.g. app/api after its lone
+// auth handler is gone). Never touches a dir that still holds files.
+const pruneEmpty = (p) => { const abs = join(root, p); if (existsSync(abs) && readdirSync(abs).length === 0) { rmdirSync(abs); return true; } return false; };
 
 // Guard: the gallery is identified by app/features/. If it is absent, the gallery
 // was already cleared (or this is not a gallery scaffold), so exit before any
@@ -40,13 +60,26 @@ const galleryPaths = [
   'app/icon.ts', 'app/apple-icon.ts', 'app/manifest.ts', 'app/opengraph-image.ts',
   'app/twitter-image.ts', 'app/robots.ts', 'app/sitemap.ts',
   'app/global-error.ts', 'app/global-not-found.ts',
+  // The gallery's EXAMPLE design system. Removed so the reset app is a blank
+  // slate: the agent builds its own components/ui/ (run `webjs ui add`, cn.ts is
+  // kept), learning the pattern from the skill, not inheriting the gallery's.
+  'components/ui',
+  // Example scaffold artifacts (invariant 2): the theme-toggle component and the
+  // example test suite are things to learn from, not the agent's app. Removed
+  // for a true blank slate; the root layout is reset to a minimal base below
+  // (which drops its toggle wiring). The agent writes its own tests + components.
+  'components/theme-toggle.ts', 'test/hello',
+  // The gallery's markup-chunk helpers. Their only users (the feature pages +
+  // the features/examples layouts) are removed above, so drop the example file
+  // too; cn.ts + dom.ts (real infrastructure) stay under lib/utils/.
+  'lib/utils/ui.ts',
 ];
 // 2) The gallery's feature modules (by name). `auth` is the auth card's server
 // modules (createAuth config, password hashing, signup action, current-user
 // query), pruned with the rest of the card.
 const galleryModules = [
   'async-render', 'auth', 'broadcast', 'caching', 'client-router', 'components',
-  'directives', 'file-storage', 'frames', 'optimistic-ui', 'rate-limit',
+  'directives', 'file-storage', 'frames', 'gallery', 'optimistic-ui', 'rate-limit',
   'route-handler', 'server-actions', 'sessions', 'stream', 'streaming', 'suspense',
   'todo', 'websockets',
 ].map((m) => `modules/${m}`);
@@ -71,17 +104,51 @@ if (existsSync(schemaPath)) {
   writeFileSync(schemaPath, s);
 }
 
-// 5) Drop generated migrations + the dev database so the next db:generate is
+// 5) Reset the root layout to a blank-slate base. The gallery layout ships a
+// navbar, a theme toggle, Google Fonts, and a full design-token palette; a blank
+// slate should inherit NONE of that, so OVERWRITE it with a minimal layout that
+// carries no design system: the Tailwind stylesheet + OS light/dark system
+// colours (Canvas / CanvasText) + a bare <main>. The agent then builds the
+// palette (CSS tokens + @theme + a light-dark() theme) as its own, guided by
+// .agents/skills/webjs/references/styling.md.
+// GUARD: overwrite only while the layout still carries the gallery's own navbar
+// brand. A hand-customised layout (the brand removed / replaced) is the user's
+// work, so it is KEPT and only the dangling references to the removed
+// theme-toggle file are stripped surgically.
+const layoutPath = join(root, 'app/layout.ts');
+if (existsSync(layoutPath)) {
+  const current = readFileSync(layoutPath, 'utf8');
+  if (current.includes('WebJs Gallery')) {
+    writeFileSync(layoutPath, MINIMAL_LAYOUT());
+  } else {
+    console.log('app/layout.ts looks customised; keeping it (only the theme-toggle wiring is stripped).');
+    writeFileSync(
+      layoutPath,
+      current
+        .replace(/^import '#components\/theme-toggle\.ts';\n/m, '')
+        .replace(/^\s*<theme-toggle><\/theme-toggle>\n?/m, ''),
+    );
+  }
+}
+
+// 6) Drop generated migrations + the dev database so the next db:generate is
 // clean against the reset schema (safe: the scaffold has no real data yet).
 rm('db/migrations');
 for (const f of ['db/dev.db', 'db/dev.db-shm', 'db/dev.db-wal']) rm(f);
 
-console.log(`Gallery cleared (${removed} paths removed). The agent skill and your database wiring are kept.`);
+// 7) Prune the empty leftover dirs a partial removal left behind, so the reset
+// tree is a clean blank slate: app/api (held only the gallery auth handler),
+// test/unit + test/e2e (empty base placeholders), and test/ itself once its
+// example suites are gone. modules/ + components/ are kept as empty build
+// targets (the reset home + `webjs ui add` land there). Order matters: prune the
+// children before test/ so it reads as empty.
+for (const d of ['app/api', 'test/unit', 'test/e2e', 'test']) if (pruneEmpty(d)) removed++;
+
+console.log(`Gallery cleared (${removed} paths removed). The agent skill and your database wiring are kept. Build your own design system: run \`npx webjsdev ui add <name>\` and theme it (see .agents/skills/webjs/references/styling.md).`);
 console.log('Next: regenerate the database (db:generate then db:migrate), then start the dev server and build your app in app/ and modules/.');
 
 function MINIMAL_PAGE() {
   return `import { html } from '@webjsdev/core';
-import '#components/theme-toggle.ts';
 
 export const metadata = {
   title: 'Home',
@@ -89,19 +156,59 @@ export const metadata = {
 
 export default function Home() {
   return html\`
-    <div class="fixed top-4 right-4 z-10"><theme-toggle></theme-toggle></div>
     <div class="max-w-2xl mx-auto px-6 py-24 flex flex-col items-center text-center gap-6">
       <h1 class="text-4xl font-bold tracking-tight m-0">Your app</h1>
-      <p class="text-base text-muted-foreground leading-relaxed m-0">
-        The gallery is cleared. This is <code class="text-[0.9em] text-foreground">app/page.ts</code>. Build your
-        app from here. The guide is <code class="text-[0.9em] text-foreground">.agents/skills/webjs/SKILL.md</code>.
+      <p class="text-base leading-relaxed m-0 opacity-70">
+        The gallery is cleared. This is <code class="text-[0.9em]">app/page.ts</code>. Build your
+        app from here. The guide is <code class="text-[0.9em]">.agents/skills/webjs/SKILL.md</code>.
       </p>
-      <nav class="flex items-center gap-5 text-sm text-muted-foreground">
-        <a href="https://docs.webjs.dev" class="hover:text-foreground transition-colors no-underline">Docs</a>
-        <a href="https://github.com/webjsdev/webjs" class="hover:text-foreground transition-colors no-underline">GitHub</a>
+      <nav class="flex items-center gap-5 text-sm opacity-70">
+        <a href="https://docs.webjs.dev" target="_blank" rel="noopener" class="hover:opacity-100 transition-opacity no-underline">Docs</a>
+        <a href="https://github.com/webjsdev/webjs" target="_blank" rel="noopener" class="hover:opacity-100 transition-opacity no-underline">GitHub</a>
       </nav>
     </div>
   \`;
 }
 `;
 }
+
+function MINIMAL_LAYOUT() {
+  return `import { html } from '@webjsdev/core';
+
+/**
+ * Root layout: the ONLY file that writes the document shell. It links the
+ * Tailwind stylesheet and renders \${children} in a bare container. This is a
+ * BLANK SLATE with no design system: it uses the OS light/dark system colours
+ * (Canvas / CanvasText) so it reads fine immediately, and it is where YOU build
+ * the app's look. The recommended setup, CSS custom-property tokens mapped into
+ * Tailwind via @theme (so bg-background / text-foreground work), a DRY
+ * light-dark() palette, a header/nav, and the ui class helpers, is taught in
+ * .agents/skills/webjs/references/styling.md. Run \`npx webjsdev ui add <name>\`
+ * to pull primitives, then theme them here.
+ */
+
+// Favicon via metadata.icons so the framework emits the <link> into <head> (a
+// hand-written <link> in the template body is ignored by browsers).
+export const metadata = { icons: '/public/favicon.svg' };
+
+export default function RootLayout({ children }: { children: unknown }) {
+  return html\`
+    <meta name="color-scheme" content="light dark">
+    <link rel="stylesheet" href="/public/tailwind.css">
+    <style>
+      html, body { margin: 0; }
+      body {
+        background: Canvas;
+        color: CanvasText;
+        font: 15px/1.6 ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+        -webkit-font-smoothing: antialiased;
+        -moz-osx-font-smoothing: grayscale;
+      }
+    </style>
+    <main class="min-h-dvh max-w-3xl mx-auto px-6 py-10">
+      \${children}
+    </main>
+  \`;
+}
+`;
+}