@webjsdev/cli 0.10.29 → 0.10.31

package/templates/gallery/modules/async-render/components/server-clock.ts

@@ -0,0 +1,26 @@
+// async render() awaits server data directly in the leaf component. Three
+// decoupled concerns to know (see AGENTS.md "Async render"):
+//   1. SSR always BLOCKS, so the resolved data is in the first paint with no
+//      fallback markup (progressive-enhancement safe, readable with JS off).
+//   2. The client re-fetch default is stale-while-revalidate (old content stays
+//      until the new render resolves, no blank flash).
+//   3. renderFallback() is the OPTIONAL re-fetch loading UI, never first paint.
+// Reach for async render() when request-time SERVER data belongs in the first
+// paint; reach for a Task / signals for genuinely client-only data.
+import { WebComponent, html } from '@webjsdev/core';
+import { serverGreeting } from '../queries/server-greeting.server.ts';
+
+export class ServerClock extends WebComponent {
+  // A bare async-render component (no other client signal) is ELIDED, since its
+  // SSR'd HTML is already the complete output. `static refresh = true` opts into
+  // keeping the on-load re-fetch so the module ships (drop it for request-stable
+  // data you are happy to leave server-rendered).
+  static refresh = true;
+
+  async render() {
+    const info = await serverGreeting();
+    return html`<p class="font-mono text-sm">server rendered this at
+      <strong>${info.at}</strong> (pid ${info.pid})</p>`;
+  }
+}
+ServerClock.register('server-clock');

package/templates/gallery/modules/async-render/queries/server-greeting.server.ts

@@ -0,0 +1,9 @@
+'use server';
+// A GET 'use server' query a component awaits directly inside `async render()`.
+// It returns request-time SERVER data the client cannot know, which is exactly
+// what async render() is for (the resolved value lands in the first paint).
+export const method = 'GET';
+
+export async function serverGreeting(): Promise<{ at: string; pid: number }> {
+  return { at: new Date().toISOString(), pid: process.pid };
+}

package/templates/gallery/modules/broadcast/components/broadcast-feed.ts

@@ -0,0 +1,61 @@
+// A shared broadcast room. Same connectWS() client as the websockets demo, but
+// the server fans each message out to all connected sockets, so every open tab
+// shows the same feed. The socket opens in connectedCallback (browser-only) and
+// closes in disconnectedCallback. At SSR it renders the disconnected state, so
+// the page still reads with JS off (a live feed has no no-JS equivalent).
+import { WebComponent, signal, html, connectWS } from '@webjsdev/core';
+
+export class BroadcastFeed extends WebComponent {
+  private connected = signal(false);
+  private lines = signal<string[]>([]);
+  #conn: ReturnType<typeof connectWS> | null = null;
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.#conn = connectWS('/features/broadcast/feed', {
+      onOpen: () => this.connected.set(true),
+      onClose: () => this.connected.set(false),
+      onMessage: (msg: unknown) => this.lines.set([...this.lines.get(), String(msg)]),
+    });
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.#conn?.close();
+    this.#conn = null;
+  }
+
+  private send(e: SubmitEvent) {
+    e.preventDefault();
+    const form = e.target as HTMLFormElement;
+    const input = form.elements.namedItem('msg') as HTMLInputElement;
+    const text = input.value.trim();
+    if (!text) return;
+    this.#conn?.send(text);
+    input.value = '';
+  }
+
+  render() {
+    const on = this.connected.get();
+    return html`
+      <div class="grid gap-4 max-w-[420px]">
+        <div class="flex items-center gap-2 text-sm">
+          <span class="w-2 h-2 rounded-full ${on ? 'bg-primary' : 'bg-muted-foreground/40'}"></span>
+          <span class="text-muted-foreground">${on ? 'in the room' : 'connecting (the live room needs JavaScript)'}</span>
+        </div>
+        <form @submit=${(e: SubmitEvent) => this.send(e)} class="flex gap-2">
+          <input name="msg" autocomplete="off" placeholder="Message everyone"
+            class="flex-1 px-3 py-2 rounded-xl bg-card border border-border text-foreground text-sm outline-none focus:border-border-strong" />
+          <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>
+        </form>
+        <ul class="grid gap-1.5 list-none m-0 p-0">
+          ${this.lines.get().map((line) => html`
+            <li class="px-3 py-2 rounded-xl bg-card border border-border text-[15px] text-foreground">${line}</li>
+          `)}
+        </ul>
+      </div>
+    `;
+  }
+}
+BroadcastFeed.register('broadcast-feed');

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

@@ -0,0 +1,35 @@
+// Demonstrates the WebComponent essentials: the declare-free reactive-prop
+// factory, an instance signal for local state, a lifecycle hook, and a <slot>
+// for content projection (works in light DOM, the default). This is the core
+// component authoring shape. Styling is crafted Tailwind on the app's design
+// tokens so it stays visually coherent with the rest of the app.
+import { WebComponent, prop, signal, html } from '@webjsdev/core';
+
+export class CounterCard extends WebComponent({
+  // A reactive prop rides an HTML attribute / SSR hydration. Declared ONLY here
+  // (no `static properties`, no class-field `label = ''` which would clobber the
+  // accessor). Set defaults in the constructor.
+  label: prop(String),
+}) {
+  private count = signal(0); // instance signal: component-local state
+
+  constructor() {
+    super();
+    this.label = this.label || 'Clicks';
+  }
+
+  render() {
+    return html`
+      <div class="grid gap-4 p-5 rounded-2xl bg-card border border-border max-w-[320px]">
+        <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>
+        </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>
+      </div>
+    `;
+  }
+}
+CounterCard.register('counter-card');

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

@@ -0,0 +1,53 @@
+// The lit-html directive set webjs re-exports (from '@webjsdev/core/directives').
+// `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.
+import { WebComponent, signal, html } from '@webjsdev/core';
+import { repeat, watch } from '@webjsdev/core/directives';
+
+interface Item { id: number; label: string }
+
+let nextId = 4;
+
+export class DirectiveDemo extends WebComponent {
+  private items = signal<Item[]>([
+    { id: 1, label: 'Alpha' },
+    { id: 2, label: 'Bravo' },
+    { id: 3, label: 'Charlie' },
+  ]);
+  private ticks = signal(0);
+
+  private reverse() {
+    this.items.set(this.items.get().slice().reverse());
+  }
+  private add() {
+    const id = nextId++;
+    this.items.set([...this.items.get(), { id, label: 'Item ' + id }]);
+  }
+
+  render() {
+    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>
+        <!-- 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>
+    `;
+  }
+}
+DirectiveDemo.register('directive-demo');

package/templates/gallery/modules/file-storage/actions/store-upload.server.ts

@@ -0,0 +1,18 @@
+// 'use server' so the page's action can call it (server-side, a direct call) and
+// it never crashes the browser module that imports it (the client gets a safe
+// RPC stub, not the node:fs code). getFileStore() is the pluggable storage
+// singleton: a local diskStore rooted at <cwd>/.webjs/uploads by default
+// (gitignored), swappable for S3/R2/GCS with one setFileStore() call at boot.
+// generateKey() mints a collision-free, traversal-safe key preserving a
+// whitelisted extension.
+'use server';
+import { getFileStore, generateKey } from '@webjsdev/server';
+
+export async function storeUpload(file: File) {
+  if (!(file instanceof File) || file.size === 0) {
+    return { success: false as const, error: 'No file provided.' };
+  }
+  const key = generateKey(file.name);
+  const { size, contentType } = await getFileStore().put(key, file, { contentType: file.type });
+  return { success: true as const, data: { key, name: file.name, size, contentType } };
+}

package/templates/gallery/modules/optimistic-ui/actions/like-post.server.ts

@@ -0,0 +1,9 @@
+'use server';
+// A tiny mutation for the optimistic-UI feature demo. It validates and echoes
+// (no persistence needed to show the mechanic). In a real app this would write
+// to the db and return the saved row.
+import type { ActionResult } from '@webjsdev/server';
+
+export async function likePost(input: { liked: boolean }): Promise<ActionResult<{ liked: boolean }>> {
+  return { success: true, data: { liked: !!input?.liked } };
+}

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

@@ -0,0 +1,35 @@
+// The IMPERATIVE optimistic() form for a simple flip: set the signal to the new
+// value instantly, run the action, and roll back automatically if it rejects.
+// Use optimistic UI where the client can PREDICT the result (likes, toggles,
+// reorders, renames). Skip it where it hurts: unpredictable / server-computed
+// results, side-effectful or OAuth / payment mutations, and destructive
+// irreversible actions (confirm-first is better there).
+//
+// This is the simple-flip API. For a LIST mutation (add / remove with rollback)
+// see the declarative optimistic(host, { source, update }) + .add() form in the
+// /examples/todo app.
+import { WebComponent, signal, optimistic, html } from '@webjsdev/core';
+import { likePost } from '../actions/like-post.server.ts';
+
+export class LikeButton extends WebComponent {
+  private liked = signal(false);
+
+  private async toggle() {
+    const next = !this.liked.get();
+    // optimistic(signal, value, action) flips `liked` to `next` immediately,
+    // runs the action, and restores the old value if the action rejects.
+    await optimistic(this.liked, next, () => likePost({ liked: next }));
+  }
+
+  render() {
+    const liked = this.liked.get();
+    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'}">
+        <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>
+    `;
+  }
+}
+LikeButton.register('like-button');

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

@@ -0,0 +1,49 @@
+// A small probe for the rate-limited endpoint. Each click fetches
+// /features/rate-limit/ping and records the status plus the X-RateLimit-Remaining
+// header the middleware stamped on. This is a legitimate hand-written fetch: the
+// target is a route.ts HTTP endpoint (not a server action, which you would
+// import and call instead). The button is the interactivity signal, so this
+// component ships and hydrates.
+import { WebComponent, signal, html } from '@webjsdev/core';
+
+interface Probe { n: number; status: number; remaining: string }
+
+export class RateProbe extends WebComponent {
+  private log = signal<Probe[]>([]);
+  private busy = signal(false);
+  #n = 0;
+
+  private async ping() {
+    if (this.busy.get()) return;
+    this.busy.set(true);
+    try {
+      const res = await fetch('/features/rate-limit/ping', { headers: { accept: 'application/json' } });
+      this.#n += 1;
+      this.log.set([
+        { n: this.#n, status: res.status, remaining: res.headers.get('x-ratelimit-remaining') ?? '?' },
+        ...this.log.get(),
+      ].slice(0, 8));
+    } finally {
+      this.busy.set(false);
+    }
+  }
+
+  render() {
+    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>
+        <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">
+              <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>
+            </li>
+          `)}
+        </ul>
+      </div>
+    `;
+  }
+}
+RateProbe.register('rate-probe');

package/templates/gallery/modules/server-actions/actions/greet.server.ts

@@ -0,0 +1,12 @@
+'use server';
+// A 'use server' action IS the API: a client import is rewritten to a typed RPC
+// stub POSTing to the server. It may use server-only utilities (they run here,
+// server-side), which is why the util above stays off the client.
+import { shout } from '../utils/format.server.ts';
+import type { ActionResult } from '@webjsdev/server';
+
+export async function greet(input: { name: string }): Promise<ActionResult<{ message: string }>> {
+  const name = String(input?.name ?? '').trim();
+  if (!name) return { success: false, error: 'Name required.', status: 400 };
+  return { success: true, data: { message: shout('hello ' + name) } };
+}

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

@@ -0,0 +1,30 @@
+// 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 { greet } from '../actions/greet.server.ts';
+
+export class Greeter extends WebComponent {
+  private msg = signal('');
+  async run(e: SubmitEvent) {
+    e.preventDefault();
+    const name = String(new FormData(e.target as HTMLFormElement).get('name') ?? '');
+    const r = await greet({ name });
+    // Narrow on r.success so TS knows `data` (success) vs `error` (failure).
+    this.msg.set(r.success ? (r.data?.message ?? '') : (r.error ?? 'error'));
+  }
+  render() {
+    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">
+          <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" />
+          <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>
+        ${this.msg.get() ? html`<p class="m-0 font-semibold text-foreground">${this.msg.get()}</p>` : ''}
+      </div>
+    `;
+  }
+}
+Greeter.register('server-greeter');

package/templates/gallery/modules/server-actions/utils/format.server.ts

@@ -0,0 +1,8 @@
+// A server-only utility: a `.server.ts` file with NO 'use server' directive.
+// Its browser import is a throw-at-load stub, so NEVER import this into a page
+// or component. Reach it only from a 'use server' action / route.ts / middleware.
+// (See the server-actions section in this app's AGENTS.md for the .server.ts
+// vs 'use server' rule.)
+export function shout(s: string): string {
+  return s.trim().toUpperCase() + '!';
+}

package/templates/gallery/modules/todo/actions/create-todo.server.ts

@@ -0,0 +1,16 @@
+'use server';
+// A MUTATION (no `method` export defaults to POST: CSRF-protected, rich body).
+// Args and the returned ActionResult round-trip through webjs's serializer.
+import { db } from '#db/connection.server.ts';
+import { todos } from '#db/schema.server.ts';
+import type { Todo } from '../types.ts';
+import type { ActionResult } from '@webjsdev/server';
+
+export async function createTodo(input: { title: string }): Promise<ActionResult<Todo>> {
+  const title = String(input?.title ?? '').trim();
+  if (!title) return { success: false, error: 'A task needs a title.', status: 400 };
+  // rc.3 mutation: `.returning()` takes NO field args in rc.3 (see the Database
+  // section in this app's AGENTS.md).
+  const [row] = await db.insert(todos).values({ title }).returning();
+  return { success: true, data: row as Todo };
+}

package/templates/gallery/modules/todo/actions/delete-todo.server.ts

@@ -0,0 +1,15 @@
+'use server';
+// A MUTATION (no `method` export defaults to POST: CSRF-protected). Imported
+// directly by the client component (the import becomes a typed RPC stub); the
+// id argument and the ActionResult round-trip through webjs's serializer.
+import { eq } from 'drizzle-orm';
+import { db } from '#db/connection.server.ts';
+import { todos } from '#db/schema.server.ts';
+import type { ActionResult } from '@webjsdev/server';
+
+export async function deleteTodo(input: { id: string }): Promise<ActionResult<{ id: string }>> {
+  const id = String(input?.id ?? '');
+  if (!id) return { success: false, error: 'Missing id.', status: 400 };
+  await db.delete(todos).where(eq(todos.id, id));
+  return { success: true, data: { id } };
+}

package/templates/gallery/modules/todo/actions/toggle-todo.server.ts

@@ -0,0 +1,21 @@
+'use server';
+import { eq } from 'drizzle-orm';
+import { db } from '#db/connection.server.ts';
+import { todos } from '#db/schema.server.ts';
+import type { Todo } from '../types.ts';
+import type { ActionResult } from '@webjsdev/server';
+
+// `completed` is explicit on the JS path; omit it on the no-JS <form> path and
+// the server reads the row and flips it (so the example degrades without JS).
+export async function toggleTodo(input: { id: string; completed?: boolean }): Promise<ActionResult<Todo>> {
+  const id = String(input?.id ?? '');
+  if (!id) return { success: false, error: 'Missing id.', status: 400 };
+  let completed = input?.completed;
+  if (typeof completed !== 'boolean') {
+    const cur = await db.query.todos.findFirst({ where: { id } });
+    if (!cur) return { success: false, error: 'Not found.', status: 404 };
+    completed = !cur.completed;
+  }
+  const [row] = await db.update(todos).set({ completed }).where(eq(todos.id, id)).returning();
+  return { success: true, data: row as Todo };
+}

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

@@ -0,0 +1,140 @@
+// The interactive surface. Demonstrates: the WebComponent factory + reactive
+// prop, the DECLARATIVE optimistic() API (instant update, auto-rollback), and
+// progressive enhancement (each mutation is a <form> posting to the page action,
+// intercepted by JS for the optimistic path). All interactivity lives in a
+// component; a page/layout cannot be interactive in its own markup.
+//
+// Styling uses the shadcn-standard design tokens the @webjsdev/ui theme defines
+// (bg-card, text-foreground, bg-primary, text-muted-foreground, border-border,
+// ...), so the whole app (this component AND any `webjs ui add` component) shares
+// 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 { createTodo } from '../actions/create-todo.server.ts';
+import { toggleTodo } from '../actions/toggle-todo.server.ts';
+import { deleteTodo } from '../actions/delete-todo.server.ts';
+import type { Todo } from '../types.ts';
+
+type Op =
+  | { kind: 'add'; tempId: string; title: string }
+  | { kind: 'toggle'; id: string; completed: boolean }
+  | { kind: 'delete'; id: string };
+
+export class TodoApp extends WebComponent({
+  // A reactive prop: the SSR'd list arrives via `.todos=${todos}` and hydrates.
+  todos: prop<Todo[]>(Array),
+}) {
+  // One optimistic store, three ops. `.add(payload, promise)` applies `update`
+  // instantly and auto-releases when the promise settles (resolve OR reject),
+  // so there is no manual try-catch / rollback / temp-id bookkeeping.
+  private store = optimistic(this, {
+    source: () => this.todos ?? [],
+    update: (state: Todo[], op: Op): Todo[] => {
+      if (op.kind === 'add') return [{ id: op.tempId, title: op.title, completed: false, createdAt: new Date(), pending: true }, ...state];
+      if (op.kind === 'toggle') return state.map((t) => (t.id === op.id ? { ...t, completed: op.completed } : t));
+      return state.filter((t) => t.id !== op.id);
+    },
+  });
+
+  async add(e: SubmitEvent) {
+    e.preventDefault();
+    const form = e.target as HTMLFormElement;
+    const title = String(new FormData(form).get('title') ?? '').trim();
+    if (!title) return;
+    form.reset();
+    const tempId = crypto.randomUUID();
+    const promise = createTodo({ title });
+    this.store.add({ kind: 'add', tempId, title }, promise);
+    const r = await promise;
+    if (r.success && r.data) this.todos = [r.data, ...(this.todos ?? [])];
+  }
+
+  async toggle(e: Event, todo: Todo) {
+    e.preventDefault();
+    if (todo.pending) return;
+    const completed = !todo.completed;
+    const promise = toggleTodo({ id: todo.id, completed });
+    this.store.add({ kind: 'toggle', id: todo.id, completed }, promise);
+    const r = await promise;
+    if (r.success && r.data) { const d = r.data; this.todos = (this.todos ?? []).map((t) => (t.id === todo.id ? d : t)); }
+  }
+
+  async removeTodo(e: Event, todo: Todo) {
+    e.preventDefault();
+    if (todo.pending) return;
+    const promise = deleteTodo({ id: todo.id });
+    this.store.add({ kind: 'delete', id: todo.id }, promise);
+    const r = await promise;
+    if (r.success) this.todos = (this.todos ?? []).filter((t) => t.id !== todo.id);
+  }
+
+  render() {
+    const list = this.store.value;
+    const done = list.filter((t) => t.completed).length;
+    const pct = list.length ? Math.round((done / list.length) * 100) : 0;
+    return html`
+      <section class="w-full max-w-[540px] grid gap-5">
+        <!-- Header: a title, a live done/total count, and a progress bar. -->
+        <header class="grid gap-3">
+          <div class="flex items-center gap-3">
+            <span class="grid place-items-center w-10 h-10 rounded-2xl bg-primary/15 text-primary shrink-0">
+              <svg viewBox="0 0 24 24" class="w-5 h-5 stroke-current fill-none" style="stroke-width:2.4;stroke-linecap:round;stroke-linejoin:round"><path d="m5 13 4 4L19 7"/></svg>
+            </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>
+            </div>
+            <span class="ml-auto text-[13px] font-semibold tabular-nums text-muted-foreground">${pct}%</span>
+          </div>
+          <div class="h-1.5 rounded-full bg-muted overflow-hidden">
+            <div class="h-full rounded-full bg-primary transition-[width] duration-300" style="width:${pct}%"></div>
+          </div>
+        </header>
+
+        <!-- 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)]">
+          <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" />
+          <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>
+
+        <ul class="list-none m-0 p-0 grid gap-2">
+          ${list.length ? list.map((todo) => html`
+            <li>
+              <form method="post" action=""
+                class="group flex items-center gap-3 px-3 py-2.5 rounded-xl bg-card border border-border transition-colors hover:border-border-strong ${todo.pending ? 'opacity-55' : ''}">
+                <input type="hidden" name="id" value=${todo.id} />
+                <!-- Toggle is a submit button (degrades to a form POST no-JS); with JS
+                     @click intercepts for the optimistic toggle. The check is centered
+                     (grid place-items-center) and only visible once completed. -->
+                <button id="t-${todo.id}" type="submit" name="intent" value="toggle"
+                  aria-pressed=${todo.completed ? 'true' : 'false'}
+                  aria-label=${todo.completed ? 'Mark as not done' : 'Mark as done'}
+                  @click=${(e: Event) => this.toggle(e, todo)}
+                  class="shrink-0 grid place-items-center w-5 h-5 rounded-full border-2 cursor-pointer transition-all ${todo.completed ? 'bg-primary border-primary text-primary-foreground' : 'bg-transparent border-border-strong text-transparent hover:border-primary'}">
+                  <svg viewBox="0 0 24 24" class="w-3 h-3 stroke-current fill-none" style="stroke-width:3.4;stroke-linecap:round;stroke-linejoin:round"><path d="m5 13 4 4L19 7"/></svg>
+                </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>
+                <!-- 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)]">
+                  <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>
+          `}
+        </ul>
+      </section>
+    `;
+  }
+}
+TodoApp.register('todo-app');

package/templates/gallery/modules/todo/queries/list-todos.server.ts

@@ -0,0 +1,19 @@
+'use server';
+// A READ is a `'use server'` action so the client (and SSR) can call it via the
+// normal import (rewritten to a typed RPC stub). `method = 'GET'` rides args in
+// the URL, is CSRF-exempt, and its result is SSR-seeded so the component does
+// not re-fetch on hydration.
+import { db } from '#db/connection.server.ts';
+import type { Todo } from '../types.ts';
+
+export const method = 'GET';
+
+export async function listTodos(): Promise<Todo[]> {
+  // rc.3 read: the relational query API. `orderBy` uses the object form
+  // (`{ column: 'asc' | 'desc' }`); passing `[desc(todos.createdAt)]` with an
+  // imported column mis-compiles to a bad SQL alias in rc.3. Do NOT use
+  // `db.select({ col })` either (its projection overload trips TS2554 in rc.3).
+  // See the Database (Drizzle) section in this app's AGENTS.md.
+  const rows = await db.query.todos.findMany({ orderBy: { createdAt: 'desc' } });
+  return rows as Todo[];
+}

package/templates/gallery/modules/todo/types.ts

@@ -0,0 +1,12 @@
+// WHY a hand-written interface (not `typeof todos.$inferSelect` from the schema):
+// this type is imported by the browser-shipped <todo-app> component. A VALUE
+// import from `db/*.server.ts` would pin the component to a server module and
+// crash it at load (webjs check flags it). A browser-safe shape here is safe.
+// See the server-actions section in this app's AGENTS.md.
+export interface Todo {
+  id: string;
+  title: string;
+  completed: boolean;
+  createdAt: Date;
+  pending?: boolean; // client-only: true while an optimistic create is in flight
+}