@webjsdev/cli 0.10.30 → 0.10.32

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,25 @@
+'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.
+  //
+  // Two equivalent read styles, both fine: the relational query API
+  // (`db.query.todos.findFirst({ where: { id } })` / `findMany`, used here and in
+  // toggle-todo) reads by an object filter; the core builder
+  // (`db.select().from(todos).where(eq(todos.id, id))`) reads with the `eq()`
+  // helper. Reach for whichever fits; the relational form is terser for by-id reads.
+  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
+}

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

@@ -0,0 +1,62 @@
+// A WebSocket echo client. connectWS() (from '@webjsdev/core') opens the socket,
+// auto-reconnects with backoff, JSON-encodes/decodes, and queues sends while
+// disconnected. The connection is opened in connectedCallback (browser-only, so
+// it never runs during SSR) and closed in disconnectedCallback. At SSR the
+// 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 } from '@webjsdev/core';
+
+export class WsEcho extends WebComponent {
+  private connected = signal(false);
+  private lines = signal<string[]>([]);
+  #conn: ReturnType<typeof connectWS> | null = null;
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.#conn = connectWS('/features/websockets/echo', {
+      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 ? 'connected' : 'connecting (live echo needs JavaScript)'}</span>
+        </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" />
+          <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 font-mono">${line}</li>
+          `)}
+        </ul>
+      </div>
+    `;
+  }
+}
+WsEcho.register('ws-echo');

package/templates/lib/utils/ui.ts

@@ -16,11 +16,11 @@
  */
 import { html } from '@webjsdev/core';
 
-/** `● label` kicker: small caps, accent colour, above headings. */
+/** `● label` kicker: small caps, brand colour, above headings. */
 export function rubric(label: string, mb: 'sm' | 'md' = 'md') {
   const mbCls = mb === 'sm' ? 'mb-3' : 'mb-4';
   return html`
-    <span class="block font-mono text-[11px] leading-none font-semibold tracking-[0.2em] uppercase text-accent ${mbCls}">● ${label}</span>
+    <span class="block font-mono text-[11px] leading-none font-semibold tracking-[0.2em] uppercase text-primary ${mbCls}">● ${label}</span>
   `;
 }
 
@@ -68,10 +68,10 @@ export function banner(content: unknown) {
   `;
 }
 
-/** Inline accent link: used inside body copy and banners. */
+/** Inline brand link: used inside body copy and banners. */
 export function accentLink(href: string, label: unknown) {
   return html`
-    <a href=${href} class="text-accent font-semibold no-underline hover:underline hover:underline-offset-[3px]">${label}</a>
+    <a href=${href} class="text-primary font-semibold no-underline hover:underline hover:underline-offset-[3px]">${label}</a>
   `;
 }
 

package/templates/test/hello/browser/hello.test.js

@@ -3,6 +3,12 @@
  *
  * Run:  webjs test --browser
  *       npx wtr
+ * First run only, if Chromium is missing:  npx playwright install chromium
+ *
+ * The runner's mocha UI is `tdd`: use suite() / test() (NOT describe / it), and
+ * throw to fail (there is no chai / expect in the importmap; a tiny inline assert
+ * like the one below is the idiom). See modules/components/components/browser for
+ * a co-located COMPONENT browser test using ssrFixture.
  *
  * Tests here have full access to real browser APIs: Shadow DOM,
  * adoptedStyleSheets, IntersectionObserver, events, etc.

package/templates/web-test-runner.config.js

@@ -33,7 +33,15 @@ export default {
   // Browser tests are `.js` (web-test-runner serves them through its own test
   // framework); the components + modules they import are `.ts`, served
   // transformed by the webjs middleware below.
-  files: ['test/**/browser/**/*.test.js'],
+  // Browser tests live under any `browser/` dir: the top-level `test/<feature>/
+  // browser/`, OR co-located next to the code they exercise (a component's
+  // `modules/<feature>/components/browser/`, the modules-architecture default).
+  files: [
+    'test/**/browser/**/*.test.js',
+    'app/**/browser/**/*.test.js',
+    'modules/**/browser/**/*.test.js',
+    'components/**/browser/**/*.test.js',
+  ],
   // webjs's importmap resolves `@webjsdev/core`, the `#` app aliases, and
   // vendors, so web-test-runner must NOT rewrite bare specifiers to
   // node_modules paths.