ucode-agent 1.6.0 → 1.7.0

package/src/tools/symbols.js

@@ -0,0 +1,218 @@
+/**
+ * symbols.js — a map of what this codebase declares, so "where is the tip
+ * calculated" is one lookup rather than five greps.
+ *
+ * grep finds every line that mentions a name; almost all of them are uses,
+ * and the one that matters is the declaration. This reads each source file
+ * once and records only the declarations: functions, classes, components,
+ * types, and the route a Next.js page answers on.
+ *
+ * The scan is by pattern, not by a parser. A parser would be exact but would
+ * mean carrying TypeScript itself and paying its start-up on every lookup;
+ * declarations are one of the few things regular expressions read reliably,
+ * because they sit at the start of a line in formatted code. What this can
+ * miss is a declaration written unusually — and a miss costs a grep, which
+ * is where we started.
+ *
+ * The index is held per directory and rebuilt when a file's modified time
+ * moves, so an edit is picked up without a rescan of everything.
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { resolveIn, guard, result, walk } from './shared.js';
+
+/** Files worth reading for declarations. */
+const SOURCE = /\.(?:[cm]?[jt]sx?|py)$/i;
+
+/** How much of a file to read; a declaration past this is a generated file's. */
+const MAX_BYTES = 400_000;
+
+const PATTERNS = [
+  // export function foo(...) / export default function foo(...)
+  { kind: 'function', re: /^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s*\*?\s*([A-Za-z_$][\w$]*)/ },
+  // class Foo / export class Foo
+  { kind: 'class', re: /^\s*(?:export\s+)?(?:default\s+)?(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)/ },
+  // const foo = (...) => / const foo = async (...) => / const foo = function
+  { kind: 'function', re: /^\s*(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*(?::[^=]+)?=>/ },
+  { kind: 'function', re: /^\s*(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s+)?function/ },
+  // type Foo = / interface Foo / enum Foo
+  { kind: 'type', re: /^\s*(?:export\s+)?type\s+([A-Za-z_$][\w$]*)\s*[<=]/ },
+  { kind: 'type', re: /^\s*(?:export\s+)?interface\s+([A-Za-z_$][\w$]*)/ },
+  { kind: 'type', re: /^\s*(?:export\s+)?(?:const\s+)?enum\s+([A-Za-z_$][\w$]*)/ },
+  // Python
+  { kind: 'function', re: /^\s*(?:async\s+)?def\s+([A-Za-z_][\w]*)/ },
+  { kind: 'class', re: /^\s*class\s+([A-Za-z_][\w]*)/ },
+];
+
+/** A capitalised function in a .tsx file is a component, and worth saying so. */
+const isComponent = (name, rel) => /^[A-Z]/.test(name) && /\.[jt]sx$/i.test(rel);
+
+/**
+ * The URL a Next.js app-router file answers on: src/app/blog/[slug]/page.tsx
+ * is /blog/[slug]. Route groups in brackets-as-parens are not part of the path.
+ */
+export function routeFor(rel) {
+  const m = rel.replace(/\\/g, '/').match(/(?:^|\/)app\/(.*)\/(page|route|layout)\.[jt]sx?$/i);
+  if (!m) {
+    if (/(?:^|\/)app\/(page|route|layout)\.[jt]sx?$/i.test(rel.replace(/\\/g, '/'))) return '/';
+    return null;
+  }
+  const url = m[1].split('/').filter((s) => s && !/^\(.*\)$/.test(s)).join('/');
+  return `/${url}`;
+}
+
+/** Every declaration in one file's text, with the line it sits on. */
+export function declarationsIn(rel, text) {
+  const found = [];
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.length > 400) continue;
+    for (const { kind, re } of PATTERNS) {
+      const m = line.match(re);
+      if (!m) continue;
+      const name = m[1];
+      found.push({
+        name,
+        kind: isComponent(name, rel) && kind === 'function' ? 'component' : kind,
+        file: rel,
+        line: i + 1,
+        text: line.trim().slice(0, 160),
+      });
+      break; // one declaration to a line
+    }
+  }
+  return found;
+}
+
+const indexes = new Map(); // root -> { files: Map<rel, {at, symbols}> }
+
+/**
+ * Read the declarations of every source file under `root`, reusing what was
+ * read before for files whose modified time has not moved.
+ */
+export async function buildIndex(root) {
+  let index = indexes.get(root);
+  if (!index) { index = { files: new Map() }; indexes.set(root, index); }
+
+  const rels = (await walk(root, {})).filter((rel) => SOURCE.test(rel));
+  const seen = new Set();
+
+  await Promise.all(rels.map(async (rel) => {
+    seen.add(rel);
+    const abs = path.join(root, rel);
+    let stat;
+    try { stat = await fs.stat(abs); } catch { return; }
+    if (stat.size > MAX_BYTES) return;
+    const had = index.files.get(rel);
+    if (had && had.at === stat.mtimeMs) return; // unchanged since last time
+    const text = await fs.readFile(abs, 'utf8').catch(() => null);
+    if (text === null) return;
+    index.files.set(rel, { at: stat.mtimeMs, symbols: declarationsIn(rel, text) });
+  }));
+
+  for (const rel of [...index.files.keys()]) if (!seen.has(rel)) index.files.delete(rel);
+
+  const symbols = [];
+  for (const { symbols: s } of index.files.values()) symbols.push(...s);
+  return { symbols, fileCount: index.files.size };
+}
+
+/** Forget what was read, so the next lookup starts clean. */
+export function clearIndex() { indexes.clear(); }
+
+const KINDS = new Set(['function', 'class', 'type', 'component']);
+
+/**
+ * Where a name is declared. An exact match wins; failing that, anything
+ * containing it, so a half-remembered name still lands.
+ */
+export async function findSymbol({ name, kind, path: p = '.' }) {
+  const wanted = String(name ?? '').trim();
+  if (!wanted) {
+    return result('Pass the name of a function, component, class or type to look for.', 'nothing to look for');
+  }
+
+  const target = resolveIn(p || '.', 'find_symbol', 'path');
+  await guard(target, `read ${target.abs}`);
+
+  const { symbols, fileCount } = await buildIndex(target.abs);
+  const pool = kind && KINDS.has(kind) ? symbols.filter((s) => s.kind === kind) : symbols;
+
+  const lower = wanted.toLowerCase();
+  let hits = pool.filter((s) => s.name === wanted);
+  let how = 'exactly';
+  if (!hits.length) {
+    hits = pool.filter((s) => s.name.toLowerCase() === lower);
+    how = 'ignoring case';
+  }
+  if (!hits.length) {
+    hits = pool.filter((s) => s.name.toLowerCase().includes(lower));
+    how = 'containing';
+  }
+
+  if (!hits.length) {
+    return result(
+      `Nothing declared as "${wanted}" in ${target.show} (read ${fileCount} source files).\n` +
+      'It may be imported from a package, spelled differently, or built at runtime — grep will find uses.',
+      'not declared here'
+    );
+  }
+
+  hits.sort((a, b) => a.name.length - b.name.length || a.file.localeCompare(b.file));
+  const shown = hits.slice(0, 25);
+  const lines = shown.map((s) => {
+    const route = routeFor(s.file);
+    return `${s.file}:${s.line}  ${s.kind}  ${s.name}${route ? `  [route ${route}]` : ''}\n    ${s.text}`;
+  });
+
+  const more = hits.length > shown.length ? `\n[${hits.length - shown.length} more]` : '';
+  return result(
+    `Declared ${how} "${wanted}":\n\n${lines.join('\n')}${more}`,
+    `${hits.length} declaration${hits.length === 1 ? '' : 's'}`
+  );
+}
+
+/**
+ * What a file declares, and what a folder's files declare — the shape of the
+ * code without reading all of it.
+ */
+export async function outline({ path: p = '.' }) {
+  const target = resolveIn(p || '.', 'outline', 'path');
+  await guard(target, `read ${target.abs}`);
+
+  const stat = await fs.stat(target.abs).catch(() => null);
+  if (stat?.isFile()) {
+    const text = await fs.readFile(target.abs, 'utf8').catch(() => '');
+    const found = declarationsIn(target.show, text);
+    if (!found.length) return result(`${target.show} declares nothing this can see.`, 'nothing declared');
+    return result(
+      `${target.show}\n` + found.map((s) => `  ${s.line}: ${s.kind} ${s.name}`).join('\n'),
+      `${found.length} declaration${found.length === 1 ? '' : 's'}`
+    );
+  }
+
+  const { symbols, fileCount } = await buildIndex(target.abs);
+  if (!symbols.length) return result(`No declarations found under ${target.show}.`, 'nothing declared');
+
+  const byFile = new Map();
+  for (const s of symbols) {
+    if (!byFile.has(s.file)) byFile.set(s.file, []);
+    byFile.get(s.file).push(s);
+  }
+
+  const files = [...byFile.keys()].sort();
+  const shown = files.slice(0, 60);
+  const body = shown.map((f) => {
+    const route = routeFor(f);
+    const names = byFile.get(f).map((s) => s.name).slice(0, 12).join(', ');
+    return `${f}${route ? `  [route ${route}]` : ''}\n  ${names}`;
+  });
+
+  const more = files.length > shown.length ? `\n[${files.length - shown.length} more files]` : '';
+  return result(
+    `${symbols.length} declarations across ${fileCount} files in ${target.show}:\n\n${body.join('\n')}${more}`,
+    `${symbols.length} declarations`
+  );
+}

package/src/tools/types.js

@@ -0,0 +1,179 @@
+/**
+ * types.js — asking the app's own TypeScript what something actually is.
+ *
+ * The model guesses at APIs. It writes `user.fullName` because that is what
+ * the property ought to be called, and finds out from a build forty seconds
+ * later that it is `displayName`. Every editor solves this by asking a
+ * language service, and the answer is already installed: the project's own
+ * TypeScript, the same version and the same tsconfig that its build uses.
+ *
+ * So this loads the project's typescript — never one of ours, which would
+ * answer for a different version of the language — and keeps a language
+ * service open on it. Asking is then a few milliseconds, and the answer is
+ * the one the build will give.
+ *
+ * A project without TypeScript installed gets a plain sentence saying so.
+ * Nothing is installed to make this work.
+ */
+
+import { promises as fs } from 'node:fs';
+import { statSync, readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { resolveIn, guard, result } from './shared.js';
+
+/** The nearest folder above `from` holding both a tsconfig and a typescript. */
+export function projectRootFor(from, root) {
+  let dir = path.resolve(from);
+  const stop = path.resolve(root);
+  for (;;) {
+    if (existsSync(path.join(dir, 'tsconfig.json'))) return dir;
+    const up = path.dirname(dir);
+    if (up === dir || !dir.startsWith(stop)) return null;
+    dir = up;
+  }
+}
+
+/** The project's own typescript, or null if it has none. */
+async function loadTypeScript(projectDir) {
+  let dir = projectDir;
+  for (;;) {
+    const entry = path.join(dir, 'node_modules', 'typescript', 'lib', 'typescript.js');
+    if (existsSync(entry)) {
+      const mod = await import(pathToFileURL(entry).href);
+      return mod.default ?? mod;
+    }
+    const up = path.dirname(dir);
+    if (up === dir) return null;
+    dir = up;
+  }
+}
+
+const services = new Map(); // project dir -> { ts, service, versions }
+
+/**
+ * A language service for this project, made once and kept. Files are read
+ * from disk and their version is their modified time, so an edit made by the
+ * model is seen on the next question without rebuilding anything.
+ */
+async function serviceFor(projectDir) {
+  const had = services.get(projectDir);
+  if (had) return had;
+
+  const ts = await loadTypeScript(projectDir);
+  if (!ts) return null;
+
+  const configPath = path.join(projectDir, 'tsconfig.json');
+  const read = ts.readConfigFile(configPath, ts.sys.readFile);
+  const parsed = ts.parseJsonConfigFileContent(read.config ?? {}, ts.sys, projectDir);
+
+  const versions = new Map();
+  const versionOf = (file) => {
+    try { return String(statSync(file).mtimeMs); } catch { return '0'; }
+  };
+
+  const host = {
+    getScriptFileNames: () => parsed.fileNames,
+    getScriptVersion: (file) => {
+      const now = versionOf(file);
+      versions.set(file, now);
+      return now;
+    },
+    getScriptSnapshot: (file) => {
+      try { return ts.ScriptSnapshot.fromString(readFileSync(file, 'utf8')); } catch { return undefined; }
+    },
+    getCurrentDirectory: () => projectDir,
+    getCompilationSettings: () => parsed.options,
+    getDefaultLibFileName: (options) => ts.getDefaultLibFilePath(options),
+    fileExists: ts.sys.fileExists,
+    readFile: ts.sys.readFile,
+    readDirectory: ts.sys.readDirectory,
+    directoryExists: ts.sys.directoryExists,
+    getDirectories: ts.sys.getDirectories,
+  };
+
+  const made = { ts, service: ts.createLanguageService(host, ts.createDocumentRegistry()), versions };
+  services.set(projectDir, made);
+  return made;
+}
+
+/** Forget the open services, so the next question starts fresh. */
+export function clearServices() { services.clear(); }
+
+/** Character offset of `symbol` used as a name, preferring a given line. */
+export function offsetOf(text, symbol, line) {
+  const re = new RegExp(`(?<![\\w$])${symbol.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')}(?![\\w$])`, 'g');
+  const hits = [...text.matchAll(re)].map((m) => m.index);
+  if (!hits.length) return -1;
+  if (!line) return hits[0];
+  const lineStart = text.split('\n').slice(0, line - 1).join('\n').length;
+  // The occurrence nearest the line asked about.
+  return hits.reduce((best, at) =>
+    Math.abs(at - lineStart) < Math.abs(best - lineStart) ? at : best, hits[0]);
+}
+
+/**
+ * What TypeScript says a name is: its exact type or signature, the docs
+ * written on it, and where it is defined.
+ */
+export async function typeOf({ path: p, symbol, line }) {
+  const wanted = String(symbol ?? '').trim();
+  if (!wanted) return result('Pass the name of something in the file to ask about.', 'nothing to ask about');
+
+  const target = resolveIn(p, 'type_of', 'path');
+  await guard(target, `read ${target.abs}`);
+
+  const text = await fs.readFile(target.abs, 'utf8').catch(() => null);
+  if (text === null) return result(`Could not read ${target.show}.`, 'unreadable');
+
+  const projectDir = projectRootFor(path.dirname(target.abs), path.parse(target.abs).root);
+  if (!projectDir) {
+    return result(
+      `${target.show} is not inside a TypeScript project (no tsconfig.json above it), so there is ` +
+      'no type information to give. Read the file, or the package it comes from.',
+      'not a typescript project'
+    );
+  }
+
+  const made = await serviceFor(projectDir);
+  if (!made) {
+    return result(
+      `This project has no TypeScript installed, so nothing can answer what ${wanted} is. ` +
+      'Once its packages are installed, ask again.',
+      'typescript not installed'
+    );
+  }
+
+  const { ts, service } = made;
+  const at = offsetOf(text, wanted, line);
+  if (at < 0) {
+    return result(`"${wanted}" does not appear in ${target.show}.`, 'not in this file');
+  }
+
+  const info = service.getQuickInfoAtPosition(target.abs, at);
+  if (!info) {
+    return result(
+      `TypeScript has nothing to say about ${wanted} in ${target.show} — usually that means the file ` +
+      'has an error above this point, or the project has not been installed.',
+      'no type information'
+    );
+  }
+
+  const signature = ts.displayPartsToString(info.displayParts);
+  const docs = ts.displayPartsToString(info.documentation ?? []);
+
+  let where = '';
+  const defs = service.getDefinitionAtPosition(target.abs, at) ?? [];
+  if (defs.length) {
+    const d = defs[0];
+    const rel = path.relative(projectDir, d.fileName).replace(/\\/g, '/');
+    const body = readFileSync(d.fileName, 'utf8').slice(0, d.textSpan.start);
+    where = `\n\nDefined in ${rel}:${body.split('\n').length}`;
+  }
+
+  return result(
+    `${signature}${docs ? `\n\n${docs}` : ''}${where}\n\n` +
+    'This is from the project\'s own TypeScript, so it is what the build will say.',
+    signature.split('\n')[0].slice(0, 80)
+  );
+}

package/src/ui/theme.js

@@ -252,7 +252,11 @@ export function asLabel(text) {
   return String(text ?? '')
     .trim()
     .replace(/\s+/g, ' ')
-    .replace(/(?<=[\w)\]"'`])[.。]+$/, '');
+    // A trailing stop, from a model's sentence or a tool's own output
+    // ("Building…", "Completing…"), is noise on a one-line label. A dot that
+    // is the argument itself — "Listing ." — is not, so a word has to come
+    // before it.
+    .replace(/(?<=[\w)\]"'`])[.。…]+$/, '');
 }
 
 /**

package/templates/blocks/app-shell.tsx

@@ -0,0 +1,81 @@
+"use client";
+
+import { ReactNode, useState } from "react";
+import Link from "next/link";
+import { Button } from "@/components/ui/button";
+import { Sheet, SheetContent, SheetTitle, SheetTrigger } from "@/components/ui/sheet";
+
+export type NavItem = { href: string; label: string; icon?: ReactNode };
+
+/**
+ * The frame every page sits in: a sidebar on a wide screen, the same nav
+ * behind a button on a phone. One list of links drives both, so they cannot
+ * drift apart.
+ */
+export function AppShell({
+  nav,
+  current,
+  title,
+  children,
+}: {
+  nav: NavItem[];
+  current?: string;
+  title: string;
+  children: ReactNode;
+}) {
+  const [open, setOpen] = useState(false);
+
+  const links = (onNavigate?: () => void) => (
+    <nav className="space-y-1" aria-label="Main">
+      {nav.map((item) => {
+        const active = current === item.href;
+        return (
+          <Link
+            key={item.href}
+            href={item.href}
+            onClick={onNavigate}
+            aria-current={active ? "page" : undefined}
+            className={
+              active
+                ? "flex items-center gap-3 rounded-md bg-muted px-3 py-2 text-sm font-medium"
+                : "flex items-center gap-3 rounded-md px-3 py-2 text-sm text-muted-foreground transition-colors hover:bg-muted/60 hover:text-foreground"
+            }
+          >
+            {item.icon}
+            {item.label}
+          </Link>
+        );
+      })}
+    </nav>
+  );
+
+  return (
+    <div className="flex min-h-svh">
+      <aside className="hidden w-60 shrink-0 border-r p-4 md:block">
+        <div className="mb-6 px-3 text-sm font-semibold tracking-tight">{title}</div>
+        {links()}
+      </aside>
+
+      <div className="flex min-w-0 flex-1 flex-col">
+        <header className="flex h-14 items-center gap-3 border-b px-4 md:px-6">
+          <Sheet open={open} onOpenChange={setOpen}>
+            <SheetTrigger asChild>
+              <Button variant="ghost" size="sm" className="md:hidden" aria-label="Open menu">
+                Menu
+              </Button>
+            </SheetTrigger>
+            <SheetContent side="left" className="w-64 p-4">
+              <SheetTitle className="mb-6 px-3 text-sm font-semibold">{title}</SheetTitle>
+              {links(() => setOpen(false))}
+            </SheetContent>
+          </Sheet>
+          <span className="text-sm font-medium md:hidden">{title}</span>
+        </header>
+
+        <main className="min-w-0 flex-1 p-4 md:p-8">
+          <div className="mx-auto w-full max-w-6xl space-y-8">{children}</div>
+        </main>
+      </div>
+    </div>
+  );
+}

package/templates/blocks/data-table.tsx

@@ -0,0 +1,117 @@
+"use client";
+
+import { useMemo, useState, ReactNode } from "react";
+import { Input } from "@/components/ui/input";
+import {
+  Table, TableBody, TableCell, TableHead, TableHeader, TableRow,
+} from "@/components/ui/table";
+
+export type Column<T> = {
+  key: keyof T & string;
+  header: string;
+  /** Right-align and tabular-nums, for money and counts. */
+  numeric?: boolean;
+  render?: (row: T) => ReactNode;
+};
+
+/**
+ * A table of things you can search and sort.
+ *
+ * Sorting and filtering happen here, over rows already in memory: it is the
+ * right shape up to a few thousand rows and the wrong one past that, where
+ * the server should be doing both.
+ */
+export function DataTable<T extends { id: string | number }>({
+  rows,
+  columns,
+  searchPlaceholder = "Search…",
+  empty,
+}: {
+  rows: T[];
+  columns: Column<T>[];
+  searchPlaceholder?: string;
+  empty?: ReactNode;
+}) {
+  const [query, setQuery] = useState("");
+  const [sort, setSort] = useState<{ key: string; asc: boolean } | null>(null);
+
+  const shown = useMemo(() => {
+    const needle = query.trim().toLowerCase();
+    let out = needle
+      ? rows.filter((row) =>
+          columns.some((c) => String(row[c.key] ?? "").toLowerCase().includes(needle)))
+      : rows.slice();
+    if (sort) {
+      out.sort((a, b) => {
+        const x = a[sort.key as keyof T];
+        const y = b[sort.key as keyof T];
+        if (typeof x === "number" && typeof y === "number") return sort.asc ? x - y : y - x;
+        return sort.asc
+          ? String(x ?? "").localeCompare(String(y ?? ""))
+          : String(y ?? "").localeCompare(String(x ?? ""));
+      });
+    }
+    return out;
+  }, [rows, columns, query, sort]);
+
+  const toggle = (key: string) =>
+    setSort((s) => (s?.key === key ? { key, asc: !s.asc } : { key, asc: true }));
+
+  return (
+    <div className="space-y-4">
+      <Input
+        value={query}
+        onChange={(e) => setQuery(e.target.value)}
+        placeholder={searchPlaceholder}
+        className="max-w-xs"
+        aria-label={searchPlaceholder}
+      />
+
+      <div className="overflow-x-auto rounded-lg border">
+        <Table>
+          <TableHeader>
+            <TableRow>
+              {columns.map((c) => (
+                <TableHead key={c.key} className={c.numeric ? "text-right" : undefined}>
+                  <button
+                    type="button"
+                    onClick={() => toggle(c.key)}
+                    className="inline-flex items-center gap-1 hover:text-foreground"
+                    aria-label={`Sort by ${c.header}`}
+                  >
+                    {c.header}
+                    <span aria-hidden className="text-xs text-muted-foreground">
+                      {sort?.key === c.key ? (sort.asc ? "↑" : "↓") : ""}
+                    </span>
+                  </button>
+                </TableHead>
+              ))}
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {shown.length === 0 ? (
+              <TableRow>
+                <TableCell colSpan={columns.length} className="h-28 text-center text-sm text-muted-foreground">
+                  {query ? `Nothing matches “${query}”.` : empty ?? "Nothing here yet."}
+                </TableCell>
+              </TableRow>
+            ) : (
+              shown.map((row) => (
+                <TableRow key={row.id}>
+                  {columns.map((c) => (
+                    <TableCell
+                      key={c.key}
+                      className={c.numeric ? "text-right tabular-nums" : undefined}
+                    >
+                      {c.render ? c.render(row) : String(row[c.key] ?? "")}
+                    </TableCell>
+                  ))}
+                </TableRow>
+              ))
+            )}
+          </TableBody>
+        </Table>
+      </div>
+    </div>
+  );
+}

package/templates/blocks/empty-state.tsx

@@ -0,0 +1,41 @@
+import { ReactNode } from "react";
+import { Button } from "@/components/ui/button";
+
+/**
+ * What a list looks like before anything is in it.
+ *
+ * An empty screen is where people decide whether a product is working or
+ * broken, so this says which it is and offers the one action that fills it.
+ */
+export function EmptyState({
+  icon,
+  title,
+  description,
+  actionLabel,
+  onAction,
+}: {
+  icon?: ReactNode;
+  title: string;
+  description?: string;
+  actionLabel?: string;
+  onAction?: () => void;
+}) {
+  return (
+    <div className="flex flex-col items-center justify-center rounded-lg border border-dashed px-6 py-16 text-center">
+      {icon ? (
+        <div className="mb-4 flex size-11 items-center justify-center rounded-full bg-muted text-muted-foreground">
+          {icon}
+        </div>
+      ) : null}
+      <h3 className="text-base font-medium">{title}</h3>
+      {description ? (
+        <p className="mt-1.5 max-w-sm text-sm text-muted-foreground text-pretty">{description}</p>
+      ) : null}
+      {actionLabel ? (
+        <Button className="mt-6" onClick={onAction}>
+          {actionLabel}
+        </Button>
+      ) : null}
+    </div>
+  );
+}

package/templates/blocks/page-header.tsx

@@ -0,0 +1,27 @@
+import { ReactNode } from "react";
+
+/**
+ * The top of a page: what it is, what it is for, and what you can do here.
+ * Actions sit on the right on a wide screen and wrap underneath on a phone.
+ */
+export function PageHeader({
+  title,
+  description,
+  actions,
+}: {
+  title: string;
+  description?: string;
+  actions?: ReactNode;
+}) {
+  return (
+    <div className="flex flex-col gap-4 border-b pb-6 sm:flex-row sm:items-end sm:justify-between">
+      <div className="space-y-1.5">
+        <h1 className="text-2xl font-semibold tracking-tight text-balance">{title}</h1>
+        {description ? (
+          <p className="max-w-2xl text-sm text-muted-foreground text-pretty">{description}</p>
+        ) : null}
+      </div>
+      {actions ? <div className="flex shrink-0 items-center gap-2">{actions}</div> : null}
+    </div>
+  );
+}