@webjsdev/cli 0.10.67 → 0.10.69

package/templates/partials/agents-playbook-fullstack.md

@@ -1,135 +1,571 @@
-## Build a full-stack app (default template)
-
-This scaffold ships a browsable feature gallery to learn from: single-concept
-demos under `app/features/`, the `app/examples/todo` app, and an example design
-system under `components/ui/`, with logic in `modules/`. Build in this order.
-
-### 1. Study the gallery, then clear it
-
-Read the demos under `app/features/` (and `app/examples/todo`) that match what
-you are building, so you copy the real idiom: server actions, queries,
-optimistic UI, component hydration, design tokens. Then run
-`npm run gallery:clear` to shed the whole gallery and reset `app/page.ts` and
-`app/layout.ts` to a blank slate. The clear also removes the example
-`components/ui/` primitives, the demo `todos` table, and the demo migrations;
-it keeps the agent skill, the database wiring, and `lib/utils/cn.ts` (needed by
-`npx webjsdev ui add`). The skill teaches the same patterns, so the gallery is
-a runnable copy you study first, not something you lose.
-
-### 2. Model the data
-
-Define real models in `db/schema.server.ts`, then run `npm run db:generate` and
-`npm run db:migrate` (required after the clear, which removed the demo table and
-migrations). Write a seed script at `db/seed.server.ts` and run
-`npm run db:seed` so list and detail pages render real rows while you build,
-instead of empty states. Put reads in `modules/<feature>/queries/*.server.ts`
-and writes in `modules/<feature>/actions/*.server.ts`, one function per file.
-
-### 3. Build a token-based design system
-
-Full reference: `.agents/skills/webjs/references/styling.md`.
-
-- Define your color tokens as CSS custom properties in `app/layout.ts`, each
-  written ONCE with the native CSS `light-dark(LIGHT, DARK)` function, so light
-  and dark modes come from one declaration.
-- Define at least: `--background`, `--foreground`, `--card`, `--primary`,
-  `--secondary`, `--muted`, `--muted-foreground`, `--accent`, `--border`,
-  `--ring`, `--destructive`. Add the matching `*-foreground` pair for each
-  surface token you use, following the styling guide's reference palette.
-- Consume colors ONLY as token utilities: `bg-background`, `text-foreground`,
-  `bg-card`, `border-border`, `text-primary`, `text-muted-foreground`,
-  `bg-destructive`.
-- NEVER put a raw un-themed Tailwind color (`red-500`, `blue-600`, `gray-100`)
-  on an element or a `@webjsdev/ui` helper.
-- Add an inline theme-detection script in the layout `<head>` so the first
-  paint matches the saved theme with no flash.
-
-### 4. Use the UI kit, do not hand-roll primitives
-
-Pull primitives with `npx webjsdev ui add <name>`; the source is copied into
-`components/ui/`, so you own it fully and can add, remove, restructure, or theme
-it however your app needs. Do NOT guess a helper or tag signature. Inspect the
-copied file `components/ui/<name>.ts`, or run
-`npx webjsdev ui view <name>`, for the exact exported names, variants, and
-sizes. The kit has two tiers:
-
-- **Tier 1, class helpers** for static primitives (button, card, input, badge,
-  native-select, textarea). Spread the helper onto a native element, for example
-  `class=${buttonClass({ variant: 'outline', size: 'sm' })}`.
-- **Tier 2, custom elements** for stateful controls and overlays (`<ui-tabs>`,
-  `<ui-dialog>`, `<ui-dropdown-menu>`, `<ui-tooltip>`, sonner toasts). Use the
-  registered tag; it owns its ARIA, focus trap, and keyboard navigation out of
-  the box. Never hand-author a tab strip or a modal when a Tier-2 element
-  covers it.
-
-Full reference: `.agents/skills/webjs/references/ui-kit.md`.
-
-### 5. Build a multi-page app (MPA), not a single page
-
-Structure the product as real routes, not one page that swaps client state:
-
-- `/` a home or overview page.
-- `/<resource>` a list page with search, filters, sorting, and a create form or
-  modal.
-- `/<resource>/[id]` a detail page for one item.
-- a couple of additional feature pages as the product needs.
-
-Give `app/layout.ts` a navbar that links the main pages, pinned with
-`position: fixed` (never `position: sticky`, which flickers on iOS during a
-client-router navigation), and reserve its height on the content with a
-`--header-height` offset. In a list or table, clicking a row or card navigates
-to that item's detail page. Wrap each row action button (edit, delete, status)
-so its handler calls `event.stopPropagation()`, letting the button run its own
-action without also triggering the row navigation.
-
-### 6. Build components for interactivity
-
-Pages and layouts (`app/**/page.ts`, `app/**/layout.ts`) are server-only HTML
-generators, so put every interactive behavior inside a `WebComponent` custom
-element. Declare a component's reactive properties in the base-class factory,
-never as a class-field initializer (`items = []` clobbers the reactive
-accessor). Use the shorthand for primitives
-(`extends WebComponent({ name: String, count: Number, open: Boolean })`) and the
-`prop<T>()` helper for typed objects and arrays
-(`extends WebComponent({ items: prop<Item[]>(Array), user: prop<User>(Object) })`).
-
-### 7. Verify before you call it done
-
-Run `npm run ci` and fix what it reports. It is one command for every gate,
-the step list declared in `package.json` under `webjs.ci`, with a result line
-per step:
-
-- `webjs check` (correctness: no browser-import or boundary violation).
-- `webjs doctor` (project health). It fails on whatever `package.json`
-  `webjs.doctor.gate` marks `error`, plus the two hard toolchain checks that
-  are fatal with no gate entry, `NODE_VERSION` and `TSCONFIG_ERASABLE`.
-- `webjs typecheck` (zero type errors).
-- A dependency audit.
-- The server, browser, and e2e test layers for the features you built.
-
-The GitHub workflow runs the same list, so a green local run predicts CI.
-While iterating, `npm run ci -- --only Tests` runs one layer. Then
-`npm run css:build` (compile Tailwind).
-
-Then boot `npm run dev`, confirm every page route returns HTTP 200, and open
-every route you changed in a real browser and play through its states: `check`
-and `typecheck` pass even when a layout collapses, so the browser is the real
-check for UI work.
+## Build an app (full-stack template)
+
+### Build steps
+
+Everything a typical app needs (pages, forms, validation, auth, owner-scoped
+CRUD, a component, Drizzle) is in this file, so build straight from it instead
+of exploring. Write in a few large steps (one shell heredoc or one write per
+group of files), not one file per turn.
+
+1. Branch, clear the demo gallery, and add the UI kit, in one command:
+   `git checkout -b feat/<name> && npm run gallery:clear && npx webjsdev ui add button input label textarea native-select card badge`.
+   The gallery (`app/features/`, `app/examples/`, the demo `modules/`) is only a
+   demo: never read it, everything it teaches is below.
+2. Write `db/schema.server.ts` (replace the whole file: its `users` table is a
+   placeholder), then `npm run db:generate && npm run db:migrate`.
+3. Write every `modules/` file (auth, queries, actions, components, utils).
+4. Write `app/layout.ts` and `app/page.ts` (replace both whole; no need to
+   read them first), every other page, `app/not-found.ts`, and
+   `test/<feature>/*.test.ts`.
+5. `npm run check && npm run typecheck && npm run test:server`, and fix what
+   they report.
+6. Walk the app once in a real browser. `curl` cannot submit a bound form
+   (the form carries a hidden action field), so use Playwright, which is
+   installed (if Chromium is missing: `npx playwright install chromium`).
+   First write one script, `walk.mjs` in the app folder, that signs up and
+   drives each feature once with `page.getByLabel(...)` and
+   `page.getByRole('button', { name })`. With JavaScript on, a submit is
+   applied in place, so wait for its outcome (`await page.waitForURL(...)` or
+   `await page.getByText('...').waitFor()`), never a fixed timeout. Save a
+   phone-width and a desktop-width screenshot under `/tmp`. Then start
+   `PORT=<port> npm run dev > dev.log 2>&1 &` (`*.log` is gitignored), run
+   `node walk.mjs`, look at the screenshots, fix what the walk shows in the
+   app, stop the server you started, and delete `walk.mjs`.
+7. Commit (see Git below).
+
+### How WebJs works
+
+- **Pages and layouts run only on the server.** They return `html` and never
+  hydrate: an `@click` in a page does nothing. Interactivity lives in a
+  `WebComponent` custom element; a page imports the component file to
+  register it and writes its tag.
+- **`*.server.ts` is the server boundary.** With `'use server';` as the first
+  line, its exported async functions are server actions: a page calls them
+  directly on the server, a component calls them over RPC (the import becomes
+  a typed stub). WITHOUT `'use server'` the file is a server-only utility (the
+  DB, secrets, `node:*`, `createAuth`): import it only from other `.server.ts`
+  files, `route.ts` or `middleware.ts`, never from a page, layout or component
+  (it crashes the browser). So a page reaches data and the session only
+  through `'use server'` queries.
+- **Forms post to actions.** `<form action=${someAction}>` is the whole wiring
+  (no `method`, no `fetch`, works without JavaScript; with JavaScript the router
+  applies the result in place). The action receives the `FormData` and returns:
+  `{ success: true, redirect: '/path' }` (a 303 to that path), or
+  `{ success: false, error?, fieldErrors?, status? }`, which re-renders the
+  same page (422) with the result on the page's `actionData`;
+  `actionData.values` already holds every submitted text field. A returned
+  `Response` (for example from `signIn`) is sent as is.
+- **Control flow:** `notFound()` and `redirect(url)` from `@webjsdev/core`
+  throw; use them in pages, layouts and form actions. In a `route.ts` return a
+  `Response` instead, and in an action called over RPC return
+  `{ success: false, error }` instead of throwing.
+
+### File map
+
+```
+app/layout.ts                 root layout: the only file that writes <head> content
+app/page.ts                   /
+app/<seg>/[id]/page.ts        dynamic route; params.id is a string
+app/<seg>/[id]/edit/page.ts   nested route
+app/not-found.ts              the 404 page, also rendered by notFound()
+app/<path>/route.ts           HTTP endpoint: export async function GET(req, { params })
+modules/<feature>/queries/<verb-noun>.server.ts   reads, 'use server', one function per file
+modules/<feature>/actions/<verb-noun>.server.ts   writes, 'use server', one function per file
+modules/<feature>/components/<tag>.ts             one custom element per file
+modules/<feature>/utils/*.ts, types.ts            pure browser-safe helpers and types
+lib/utils/*.ts                app-wide browser-safe helpers
+db/schema.server.ts           tables; `db` is in db/connection.server.ts
+test/<feature>/*.test.ts      server tests (node:test), run by `npm run test:server`
+```
+
+Import app files through the `#` root alias with the `.ts` extension:
+`import { db } from '#db/connection.server.ts'`.
+
+### Worked example: a signed-in CRUD feature
+
+Each block is a whole file. Copy the shape and rename (`posts` becomes your
+resource). Child resources (a project's tasks) follow the same pattern: the
+child table references the parent with `onDelete: 'cascade'`, and every query
+and action checks that the parent belongs to the signed-in user.
+
+```ts
+// db/schema.server.ts (columns.server.ts provides table, pk, text, integer, createdAt, index)
+import { defineRelations } from 'drizzle-orm';
+import { table, pk, text, integer, createdAt, index } from './columns.server.ts';
+import { POST_STATUSES } from '#modules/posts/types.ts';
+
+export const users = table('users', {
+  id: pk(),
+  email: text().notNull().unique(),
+  passwordHash: text().notNull(),
+  createdAt: createdAt(),
+});
+export const posts = table('posts', {
+  id: pk(),
+  ownerId: integer().notNull().references(() => users.id, { onDelete: 'cascade' }),
+  title: text().notNull(),
+  body: text().notNull().default(''),
+  status: text({ enum: POST_STATUSES }).notNull().default('draft'),
+  publishOn: text(), // 'YYYY-MM-DD' from <input type="date">, or null
+  createdAt: createdAt(),
+}, (t) => [index(t.ownerId)]);
+export const relations = defineRelations({ users, posts }, () => ({}));
+export type User = typeof users.$inferSelect;
+export type Post = typeof posts.$inferSelect;
+```
+
+```ts
+// modules/posts/types.ts (browser-safe: components import this, never the schema)
+export const POST_STATUSES = ['draft', 'review', 'published'] as const;
+export type PostStatus = (typeof POST_STATUSES)[number];
+export interface StatusCounts { draft: number; review: number; published: number; total: number }
+```
+
+```ts
+// lib/utils/form.ts
+import { html } from '@webjsdev/core';
+import { labelClass } from '#components/ui/label.ts';
+import { inputClass } from '#components/ui/input.ts';
+
+/** What a failed form action hands back to the page as `actionData`. */
+export interface FormState { error?: string; fieldErrors?: Record<string, string>; values?: Record<string, string> }
+export const isEmail = (s: string) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s);
+export const str = (fd: FormData, k: string) => String(fd.get(k) ?? '').trim();
+export const toId = (v: unknown) => { const n = Number(v); return Number.isInteger(n) && n > 0 ? n : null; };
+
+/** A labelled input with its server error under it and the typed value kept. */
+export function field(o: { label: string; name: string; type?: string; value?: string; error?: string; required?: boolean }) {
+  return html`
+    <div class="grid gap-1.5">
+      <label for=${o.name} class=${labelClass()}>${o.label}</label>
+      <input id=${o.name} name=${o.name} type=${o.type ?? 'text'} value=${o.value ?? ''} ?required=${o.required}
+        aria-invalid=${o.error ? 'true' : 'false'} class=${inputClass()}>
+      ${o.error ? html`<p class="text-sm text-destructive">${o.error}</p>` : ''}
+    </div>`;
+}
+```
+
+Auth uses the built-in `createAuth` (a signed session cookie) and `node:crypto`
+scrypt. No extra package is needed.
+
+```ts
+// modules/auth/password.server.ts
+import { scrypt, randomBytes, timingSafeEqual } from 'node:crypto';
+import { promisify } from 'node:util';
+const scryptAsync = promisify(scrypt);
+export async function hashPassword(pw: string) {
+  const salt = randomBytes(16).toString('hex');
+  return salt + ':' + ((await scryptAsync(pw, salt, 64)) as Buffer).toString('hex');
+}
+export async function verifyPassword(pw: string, stored: string) {
+  const [salt, key] = stored.split(':');
+  return timingSafeEqual((await scryptAsync(pw, salt, 64)) as Buffer, Buffer.from(key, 'hex'));
+}
+```
+
+```ts
+// modules/auth/auth.server.ts (server-only: no 'use server')
+import { createAuth, Credentials } from '@webjsdev/server';
+import { db } from '#db/connection.server.ts';
+import { verifyPassword } from './password.server.ts';
+
+const secret = process.env.AUTH_SECRET;
+if (!secret) throw new Error('AUTH_SECRET is not set');
+export const { auth, signIn, signOut } = createAuth({
+  secret,
+  pages: { signIn: '/signin', error: '/signin' },
+  providers: [Credentials({
+    async authorize(c: { email: string; password: string }) {
+      const user = await db.query.users.findFirst({ where: { email: c.email } });
+      if (!user || !(await verifyPassword(c.password, user.passwordHash))) return null;
+      return { id: String(user.id), email: user.email };
+    },
+  })],
+});
+export interface SessionUser { id: number; email: string }
+export async function getUser(): Promise<SessionUser | null> {
+  const u = (await auth())?.user;
+  return u?.id ? { id: Number(u.id), email: String(u.email) } : null;
+}
+```
+
+```ts
+// modules/auth/queries/current-user.server.ts (for the layout and public pages)
+'use server';
+import { getUser, type SessionUser } from '../auth.server.ts';
+export async function currentUser(): Promise<SessionUser | null> {
+  return getUser();
+}
+
+// modules/auth/queries/require-user.server.ts (call first in every signed-in page)
+'use server';
+import { redirect } from '@webjsdev/core';
+import { getUser, type SessionUser } from '../auth.server.ts';
+export async function requireUser(): Promise<SessionUser> {
+  return (await getUser()) ?? redirect('/signin');
+}
+```
+
+```ts
+// modules/auth/actions/sign-up.server.ts
+'use server';
+import { db } from '#db/connection.server.ts';
+import { users } from '#db/schema.server.ts';
+import { isEmail, str } from '#lib/utils/form.ts';
+import { hashPassword } from '../password.server.ts';
+import { signIn } from '../auth.server.ts';
+
+export async function signUp(fd: FormData) {
+  const email = str(fd, 'email').toLowerCase();
+  const password = String(fd.get('password') ?? '');
+  const fieldErrors: Record<string, string> = {};
+  if (!isEmail(email)) fieldErrors.email = 'Enter a valid email address.';
+  if (password.length < 8) fieldErrors.password = 'Password must be at least 8 characters.';
+  if (!fieldErrors.email && (await db.query.users.findFirst({ where: { email } }))) {
+    fieldErrors.email = 'An account with this email already exists.';
+  }
+  if (Object.keys(fieldErrors).length) return { success: false, fieldErrors };
+  await db.insert(users).values({ email, passwordHash: await hashPassword(password) });
+  return signIn('credentials', { email, password }, { redirectTo: '/posts' }); // sets the cookie, 302
+}
+```
+
+Sign-in is the same shape: look the user up, `verifyPassword`, return
+`{ success: false, error: 'Invalid email or password.' }` on a mismatch, else
+`return signIn('credentials', { email, password }, { redirectTo: '/posts' })`.
+Sign-out is an action bound to a form in the layout:
+
+```ts
+// modules/auth/actions/sign-out.server.ts
+'use server';
+import { signOut } from '../auth.server.ts';
+export async function signOutUser(_fd: FormData) {
+  return signOut({ redirectTo: '/signin' }); // clears the cookie, 302
+}
+```
+
+```ts
+// modules/posts/utils/validate-post.ts (pure: shared by create and update, unit-tested)
+import { str } from '#lib/utils/form.ts';
+import { POST_STATUSES, type PostStatus } from '../types.ts';
+export interface PostInput { title: string; body: string; status: PostStatus; publishOn: string | null }
+export function validatePost(fd: FormData) {
+  const values = { title: str(fd, 'title'), body: str(fd, 'body'), status: str(fd, 'status') || 'draft', publishOn: str(fd, 'publishOn') };
+  const fieldErrors: Record<string, string> = {};
+  if (!values.title) fieldErrors.title = 'Title is required.';
+  if (!(POST_STATUSES as readonly string[]).includes(values.status)) fieldErrors.status = 'Pick a status.';
+  if (values.publishOn && !/^\d{4}-\d{2}-\d{2}$/.test(values.publishOn)) fieldErrors.publishOn = 'Use a valid date.';
+  if (Object.keys(fieldErrors).length) return { ok: false as const, fieldErrors, values };
+  const data: PostInput = { ...values, status: values.status as PostStatus, publishOn: values.publishOn || null };
+  return { ok: true as const, data };
+}
+```
+
+Reads use the relational API (`db.query.<table>.findMany/findFirst` with an
+object `where` and `orderBy`) and always filter by the owner:
+
+```ts
+// modules/posts/queries/get-post.server.ts (list-posts.server.ts is the same with findMany + orderBy: { createdAt: 'desc' })
+'use server';
+import { db } from '#db/connection.server.ts';
+import type { Post } from '#db/schema.server.ts';
+import { getUser } from '#modules/auth/auth.server.ts';
+import { toId } from '#lib/utils/form.ts';
+
+/** The post when it exists AND belongs to the signed-in user, else null (the page throws notFound()). */
+export async function getPost(id: string): Promise<Post | null> {
+  const user = await getUser();
+  const postId = toId(id);
+  if (!user || !postId) return null;
+  return (await db.query.posts.findFirst({ where: { id: postId, ownerId: user.id } })) ?? null;
+}
+```
+
+```ts
+// modules/posts/queries/count-posts.server.ts (one grouped query, never one per row)
+'use server';
+import { count, eq } from 'drizzle-orm';
+import { db } from '#db/connection.server.ts';
+import { posts } from '#db/schema.server.ts';
+import { getUser } from '#modules/auth/auth.server.ts';
+import type { StatusCounts } from '../types.ts';
+
+export async function countPosts(): Promise<StatusCounts> {
+  const c: StatusCounts = { draft: 0, review: 0, published: 0, total: 0 };
+  const user = await getUser();
+  if (!user) return c;
+  const rows = await db.select({ status: posts.status, n: count() }).from(posts)
+    .where(eq(posts.ownerId, user.id)).groupBy(posts.status);
+  for (const r of rows) { c[r.status] = r.n; c.total += r.n; }
+  return c;
+}
+```
+
+Writes use the query builder with `eq` / `and`, and put the owner in the
+`where` so another user's id changes nothing. `create-post.server.ts` is
+`validatePost`, then `db.insert(posts).values({ ...v.data, ownerId: user.id }).returning()`,
+then `{ success: true, redirect: '/posts/' + post.id }`. `delete-post.server.ts`
+reads the id from a hidden input and returns `{ success: true, redirect: '/posts' }`.
+
+```ts
+// modules/posts/actions/update-post.server.ts
+'use server';
+import { and, eq } from 'drizzle-orm';
+import { db } from '#db/connection.server.ts';
+import { posts } from '#db/schema.server.ts';
+import { getUser } from '#modules/auth/auth.server.ts';
+import { toId } from '#lib/utils/form.ts';
+import { validatePost } from '../utils/validate-post.ts';
+
+export async function updatePost(fd: FormData) {
+  const user = await getUser();
+  const id = toId(fd.get('id'));
+  if (!user || !id) return { success: false, error: 'Not found.', status: 404 };
+  const v = validatePost(fd);
+  if (!v.ok) return { success: false, fieldErrors: v.fieldErrors, values: v.values };
+  const rows = await db.update(posts).set(v.data).where(and(eq(posts.id, id), eq(posts.ownerId, user.id))).returning();
+  if (!rows.length) return { success: false, error: 'Not found.', status: 404 };
+  return { success: true, redirect: `/posts/${id}` };
+}
+```
+
+An action a component calls over RPC takes a typed object, checks it, and
+returns a result (it never throws or redirects):
+
+```ts
+// modules/posts/actions/set-post-status.server.ts
+'use server';
+import { and, eq } from 'drizzle-orm';
+import { db } from '#db/connection.server.ts';
+import { posts } from '#db/schema.server.ts';
+import { getUser } from '#modules/auth/auth.server.ts';
+import { POST_STATUSES, type PostStatus } from '../types.ts';
+
+export interface SetStatusInput { id: number; status: PostStatus }
+export async function setPostStatus(input: SetStatusInput) {
+  const user = await getUser();
+  if (!user) return { success: false, error: 'Sign in first.', status: 401 };
+  if (!POST_STATUSES.includes(input.status)) return { success: false, error: 'Bad status.', status: 400 };
+  const rows = await db.update(posts).set({ status: input.status })
+    .where(and(eq(posts.id, Number(input.id)), eq(posts.ownerId, user.id))).returning();
+  return rows.length ? { success: true } : { success: false, error: 'Not found.', status: 404 };
+}
+```
+
+A component declares reactive properties in the `WebComponent({...})` factory
+(attributes arrive kebab-cased: `postId` is `post-id`), keeps local state in
+signals, and binds events with an unquoted `@event=${fn}`:
+
+```ts
+// modules/posts/components/post-status.ts
+import { WebComponent, html, signal } from '@webjsdev/core';
+import { setPostStatus } from '../actions/set-post-status.server.ts';
+import { POST_STATUSES, type PostStatus } from '../types.ts';
+import { labelClass } from '#components/ui/label.ts';
+import { nativeSelectClass } from '#components/ui/native-select.ts';
+
+/** Status select that saves on change over RPC, with no page reload. */
+export class PostStatusSelect extends WebComponent({ postId: Number, status: String }) {
+  note = signal('');
+  async onChange(e: Event) {
+    const select = e.target as HTMLSelectElement;
+    const before = this.status;
+    this.status = select.value;
+    const res = await setPostStatus({ id: this.postId, status: select.value as PostStatus });
+    if (res.success) this.note.set('Saved');
+    else { this.status = before; select.value = before; this.note.set(res.error ?? 'Could not save'); }
+  }
+  render() {
+    const id = `status-${this.postId}`;
+    return html`
+      <div class="flex items-center gap-2">
+        <label for=${id} class=${labelClass()}>Status</label>
+        <select id=${id} class=${nativeSelectClass()} @change=${(e: Event) => this.onChange(e)}>
+          ${POST_STATUSES.map((s) => html`<option value=${s} ?selected=${s === this.status}>${s}</option>`)}
+        </select>
+        <span class="text-xs text-muted-foreground" aria-live="polite">${this.note.get()}</span>
+      </div>`;
+  }
+}
+PostStatusSelect.register('post-status');
+```
+
+```ts
+// app/layout.ts
+import { html, asset } from '@webjsdev/core';
+import type { LayoutProps } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
+import { currentUser } from '#modules/auth/queries/current-user.server.ts';
+import { signOutUser } from '#modules/auth/actions/sign-out.server.ts';
+
+export const metadata = { title: { default: 'Posts', template: '%s | Posts' } };
+export default async function RootLayout({ children }: LayoutProps) {
+  const user = await currentUser();
+  return html`
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link rel="stylesheet" href=${asset('/public/tailwind.css')}>
+    <script>if (matchMedia('(prefers-color-scheme: dark)').matches) document.documentElement.classList.add('dark');</script>
+    <style>
+      :root {
+        color-scheme: light dark;
+        --background: light-dark(#ffffff, #14161a); --foreground: light-dark(#17191c, #e6e8eb);
+        --card: light-dark(#f7f8fa, #1c1f24); --card-foreground: var(--foreground);
+        --primary: light-dark(#2f5bd3, #8fb0ff); --primary-foreground: light-dark(#ffffff, #0b1530);
+        --secondary: light-dark(#eef0f3, #2a2e34); --secondary-foreground: var(--foreground);
+        --muted: light-dark(#f1f3f5, #23272d); --muted-foreground: light-dark(#5b626b, #9aa1aa);
+        --accent: light-dark(#e9edf5, #2a3140); --accent-foreground: var(--foreground);
+        --border: light-dark(#e2e5e9, #343a42); --input: var(--border); --ring: light-dark(#8aa4e8, #5b78c4);
+        --destructive: light-dark(#c0362c, #f28b82);
+      }
+      body { margin: 0; background: var(--background); color: var(--foreground); font: 15px/1.6 system-ui, sans-serif; }
+    </style>
+    <header class="fixed inset-x-0 top-0 z-40 h-14 border-b border-border bg-background/95 backdrop-blur">
+      <nav class="mx-auto flex h-full max-w-4xl items-center gap-4 px-4">
+        <a href="/" class="font-semibold text-foreground no-underline">Posts</a>
+        ${user ? html`
+          <span class="ml-auto hidden text-sm text-muted-foreground sm:inline">${user.email}</span>
+          <form action=${signOutUser} class="ml-auto sm:ml-0"><button class=${buttonClass({ variant: 'outline', size: 'sm' })}>Sign out</button></form>`
+        : html`<a href="/signin" class="ml-auto text-sm">Sign in</a>`}
+      </nav>
+    </header>
+    <main class="mx-auto min-h-dvh max-w-4xl px-4 pb-16 pt-20 text-foreground">${children}</main>`;
+}
+```
+
+```ts
+// app/page.ts
+import { redirect } from '@webjsdev/core';
+import { currentUser } from '#modules/auth/queries/current-user.server.ts';
+export default async function Home() {
+  redirect((await currentUser()) ? '/posts' : '/signin');
+}
+```
+
+A page with a form reads `actionData` (typed with `FormState`). The sign-in
+and sign-up pages are this shape too, with `if (await currentUser()) redirect('/posts');`
+first and `actionData.error` shown above the fields.
+
+```ts
+// app/posts/page.ts
+import { html } from '@webjsdev/core';
+import type { PageProps } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
+import { cardClass } from '#components/ui/card.ts';
+import { field, type FormState } from '#lib/utils/form.ts';
+import { requireUser } from '#modules/auth/queries/require-user.server.ts';
+import { listPosts } from '#modules/posts/queries/list-posts.server.ts';
+import { countPosts } from '#modules/posts/queries/count-posts.server.ts';
+import { createPost } from '#modules/posts/actions/create-post.server.ts';
+
+export const metadata = { title: 'Your posts' };
+export default async function PostsPage({ actionData }: PageProps<'/posts'> & { actionData?: FormState }) {
+  await requireUser();
+  const [items, counts] = await Promise.all([listPosts(), countPosts()]);
+  const e = actionData?.fieldErrors ?? {};
+  const v = actionData?.values ?? {};
+  return html`
+    <h1 class="text-2xl font-semibold">Your posts</h1>
+    <p class="mt-1 text-sm text-muted-foreground">${counts.total} total, ${counts.published} published</p>
+    <form action=${createPost} class="${cardClass()} mt-6 grid gap-3 p-4 sm:grid-cols-[1fr_auto] sm:items-end">
+      ${field({ label: 'Title', name: 'title', value: v.title, error: e.title, required: true })}
+      <button class=${buttonClass()}>Create post</button>
+    </form>
+    <ul class="mt-6 grid gap-3 sm:grid-cols-2">
+      ${items.map((p) => html`
+        <li class="${cardClass()} p-4">
+          <a href="/posts/${p.id}" class="font-medium text-foreground">${p.title}</a>
+          <p class="mt-1 text-sm text-muted-foreground">${p.status}</p>
+        </li>`)}
+    </ul>
+    ${items.length ? '' : html`<p class="mt-6 text-muted-foreground">No posts yet.</p>`}`;
+}
+```
+
+```ts
+// app/posts/[id]/page.ts
+import { html, notFound } from '@webjsdev/core';
+import type { PageProps } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
+import { requireUser } from '#modules/auth/queries/require-user.server.ts';
+import { getPost } from '#modules/posts/queries/get-post.server.ts';
+import { deletePost } from '#modules/posts/actions/delete-post.server.ts';
+import '#modules/posts/components/post-status.ts'; // registers <post-status>
+
+export default async function PostPage({ params }: PageProps<'/posts/[id]'>) {
+  await requireUser();
+  const post = await getPost(params.id);
+  if (!post) notFound();
+  return html`
+    <h1 class="text-2xl font-semibold">${post.title}</h1>
+    ${post.body ? html`<p class="mt-3 whitespace-pre-line">${post.body}</p>` : ''}
+    <div class="mt-6 flex flex-wrap items-center gap-3">
+      <post-status post-id=${post.id} status=${post.status}></post-status>
+      <a href="/posts/${post.id}/edit" class=${buttonClass({ variant: 'outline', size: 'sm' })}>Edit</a>
+      <form action=${deletePost} onsubmit="return confirm('Delete this post?')">
+        <input type="hidden" name="id" value=${post.id}>
+        <button class=${buttonClass({ variant: 'destructive', size: 'sm' })}>Delete</button>
+      </form>
+    </div>`;
+}
+```
+
+The edit page loads the row the same way, pre-fills from it
+(`const v = actionData?.values ?? { title: post.title, ... }`), and posts a
+hidden `id` to `updatePost`. A `<textarea class=${textareaClass()}>` holds its
+value as text content; a `<select class=${nativeSelectClass()}>` marks the
+current option with `?selected=${s === v.status}`. Both need a `<label for>`.
+
+```ts
+// app/not-found.ts
+import { html } from '@webjsdev/core';
+export default function NotFound() {
+  return html`<h1 class="text-2xl font-semibold">Not found</h1><p class="mt-2 text-muted-foreground"><a href="/">Go home</a></p>`;
+}
+```
+
+```ts
+// test/posts/validate-post.test.ts
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { validatePost } from '#modules/posts/utils/validate-post.ts';
+const fd = (o: Record<string, string>) => { const f = new FormData(); for (const [k, v] of Object.entries(o)) f.set(k, v); return f; };
+test('a post needs a title', () => {
+  const r = validatePost(fd({ title: '  ' }));
+  assert.equal(r.ok ? '' : r.fieldErrors.title, 'Title is required.');
+});
+```
+
+### Look and the UI kit
+
+- The palette is the token block in the layout's `<style>`, each colour
+  written once as `light-dark(LIGHT, DARK)`; `public/input.css` maps the tokens
+  into Tailwind. Pick values that fit the product, and style only with token
+  utilities:
+  `bg-background text-foreground bg-card text-card-foreground bg-primary
+  text-primary-foreground bg-muted text-muted-foreground border-border
+  text-destructive ring-ring`. Never a raw colour such as `bg-blue-600`.
+- Pin the header with `position: fixed` (never `sticky`) and offset the
+  content by its height, as the layout above does. Mobile first: one column
+  that widens at `sm:` / `md:`.
+- The kit copies class helpers into `components/ui/` (you own them; no need to
+  open them): `buttonClass({ variant?: 'default' | 'destructive' | 'outline' |
+  'secondary' | 'ghost' | 'link', size?: 'default' | 'xs' | 'sm' | 'lg' |
+  'icon' })`, `inputClass()`, `textareaClass()`, `labelClass()`,
+  `nativeSelectClass()`, `cardClass({ size?: 'default' | 'sm' })`,
+  `badgeClass({ variant?: 'default' | 'secondary' | 'destructive' | 'outline' })`.
+  Use them as `class=${buttonClass({ variant: 'outline' })}` on native
+  elements. Stateful widgets (dialog, tabs, dropdown menu, tooltip, toasts) are
+  custom elements: `npx webjsdev ui add dialog`, then `npx webjsdev ui view dialog`
+  for the tags.
 
 ### Commands
 
 ```sh
-npm install
-npm run gallery:clear        # shed the demo gallery before building a real app
-npm run dev                  # dev server at http://localhost:8080
-npm run start                # production server
-npm test                     # unit + browser tests
-npm run typecheck
-npm run css:build            # compile Tailwind
-npm run ci                   # every gate, one command (the webjs.ci steps in package.json)
-npm run check                # correctness checks
-npm run doctor               # project health (severity per check: webjs.doctor.gate)
-npx webjsdev ui add <name>   # copy a ui primitive into components/ui/
-npx webjsdev ui view <name>  # inspect a primitive's exact signature
-npm run db:generate && npm run db:migrate
+npm run dev                    # dev server; PORT=<port> to choose the port
+npm run db:generate && npm run db:migrate   # after every schema change
+npm run check                  # framework rules (boundaries, forms, components)
+npm run typecheck              # TypeScript
+npm run test:server            # node:test files under test/
+npm run ci                     # every gate, before you push
+npx webjsdev ui add <name>     # copy a UI kit primitive into components/ui/
 ```