@graph8/sdk 0.308.1 → 0.357.0

package/README.md

@@ -7,6 +7,8 @@ The most comprehensive GTM SDK. One `npm install`. Every graph8 capability.
 > two client layers, safety tiers, errors and tested recipes, and links a per-area reference for every
 > operation in [`docs/api/`](docs/api/README.md). It ships with the package, so it matches this version.
 > Run `npx @graph8/sdk init-agent` to point Claude Code, Codex and Cursor in your project at it automatically.
+>
+> Blocks (copy-in components and hooks per feature): `npx @graph8/sdk list`, `search <text>`, `add <block>[/<Component>]`, `create <stack> <dir>` (a whole Next.js app: `npx @graph8/sdk create starter my-app`), and `doctor` to check your key, scopes and subscription. Each takes `--help`.
 
 ## Install
 
@@ -483,6 +485,85 @@ const { data: objects } = await service.request<{ data: unknown[] }>('/api/v1/ap
 > The `g8.objects` resource above uses an API key for native workspace objects;
 > it does not substitute for app-token authorization.
 
+## Build a competitor in one command
+
+A stack is a ready-made Next.js app: the `/api/g8` proxy (your API key stays on the server), an app shell, and one screen per feature, copied into your repo so you and your agent can edit it.
+
+```bash
+npx @graph8/sdk create mailchimp my-app   # then: cd my-app && cp .env.local.example .env.local && npm run dev
+```
+
+| Stack | Screens |
+|---|---|
+| `starter` | An empty app: proxy, shell and one landing page |
+| `mailchimp` | Contacts, companies, forms, submissions, lists, suppressions, newsletter, subscribers, nurture |
+| `clay` | Contacts, companies, lists, suppressions, prospect search, bulk enrichment, workbench |
+| `6sense` | Contacts, companies, intent feed, website visitors, competitor tracker |
+| `intercom` | Contacts, companies, web chat conversations, mailboxes, AI inbox, AI agents |
+| `outreach` | Contacts, companies, lists, mailboxes, sequences, inbox, dialer, call log, meetings, analytics |
+| `apollo` | Outreach's screens plus prospect search, enrichment, intent, visitors, deals and integrations |
+| `gong` | Contacts, companies, lists, dialer, call log, meetings, coaching feed, analytics |
+| `salesforce` | Contacts, companies, custom objects, lists, lifecycle, deals, quotes, analytics, workflows, copilot, integrations |
+| `hubspot` | The full CRM and marketing suite: forms, newsletter, nurture, web chat, sequences, inbox, pages, lifecycle, deals, quotes, workflows |
+
+Every available stack is proven by `npm run build && npm run e2e:create -- <stack>`, which packs the SDK, scaffolds the app with the built CLI, installs it and requires `next build` to pass. More stacks appear here as their blocks land; `create` refuses a stack that is not available yet.
+
+## UI kit (`@graph8/sdk/ui`)
+
+The React component kit and design tokens behind the graph8 app (primitives, light and dark
+tokens, Tailwind v4, React 18 or 19, no Next.js requirement), shipped as a subpath of this package.
+It is optional: `import ... from "@graph8/sdk"` never loads it.
+
+Install the peers only if you use the kit:
+
+```bash
+npm install @graph8/sdk react react-dom \
+  @radix-ui/react-avatar @radix-ui/react-collapsible @radix-ui/react-context-menu \
+  @radix-ui/react-dialog @radix-ui/react-label @radix-ui/react-separator @radix-ui/react-slider \
+  @radix-ui/react-slot @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-tooltip \
+  @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities \
+  class-variance-authority clsx lucide-react react-resizable-panels recharts tailwind-merge vaul
+```
+
+Version notes: `react-resizable-panels` must be v4 or newer (the kit uses its `Group`/`Separator` API).
+`recharts` 2.15+ and 3 both run, but the chart primitive is written against the recharts 2 types, so
+recharts 3 apps that type-check library declarations (`skipLibCheck: false`) may see type errors from
+`chart.d.ts`. `tailwind-merge` should be v3 to know the Tailwind v4 class names the kit uses; older
+versions still install but may merge conflicting classes wrongly.
+
+```tsx
+import { Button, Card, CardHeader, CardTitle, CardContent } from "@graph8/sdk/ui";
+import { Dialog, DialogContent } from "@graph8/sdk/ui/primitives/dialog"; // single primitive
+```
+
+**Styles: pick one import (skipping this renders every component unstyled).**
+
+| Import | Gives you | Use when |
+|---|---|---|
+| `@graph8/sdk/ui/theme.css` | tokens + `@theme inline` + dark/hover variants + `@source` | you run Tailwind v4 |
+| `@graph8/sdk/ui/styles.css` | tokens + pre-compiled utilities (no preflight reset) | you do not run Tailwind |
+| `@graph8/sdk/ui/tokens.css` | custom properties only (`:root`, `.dark`) | you want just the palette |
+
+```css
+@import "tailwindcss";
+@import "@graph8/sdk/ui/theme.css";
+```
+
+`theme.css` declares `@source "../dist/ui"`, which is what lets Tailwind v4 (it skips `node_modules`)
+see the class names inside the kit. Dark mode is class-based: put `class="dark"` on `<html>` or any subtree.
+
+React Server Components: client primitives keep their own `"use client"` directive. These seven need
+no client runtime and work directly in a Server Component:
+
+<!-- UI_SERVER_SAFE_LIST -->
+`Breadcrumb`, `Button`, `Card`, `Input`, `Item`, `Skeleton`, `Textarea`
+<!-- /UI_SERVER_SAFE_LIST -->
+
+`Sortable`'s short aliases (`Root`, `Item`, ...) are reachable only through
+`@graph8/sdk/ui/primitives/sortable`. `content-state`, `confirm-dialog` and `skeletons` are app composites
+and are not shipped. The kit is generated from the graph8 app (`npm run generate:ui` in `sdk/js`) and CI
+fails on drift; do not edit `src/ui` or `styles/` by hand.
+
 ## Auth Modes
 
 | Mode | Key | Use case |

package/blocks/README.md

@@ -0,0 +1,32 @@
+# graph8 SDK blocks
+
+A block is **editable source** for one product feature (contacts table, sequence builder, inbox...):
+React components, hooks and server-side SDK recipes, plus a manifest (`block.json`). A coding agent
+copies the block into the customer's Next.js app, so the customer owns and edits the code. Nothing here
+is imported from `node_modules` at runtime.
+
+```
+blocks/<id>/block.json        manifest (schema: blocks/block.schema.json, type: blocks/block.types.ts)
+blocks/<id>/README.md         the flow: what happens in what order, which ids pass where, tiers
+blocks/<id>/components/*.tsx  UI, copied into the app
+blocks/<id>/hooks/*.ts        data hooks, copied into the app
+blocks/<id>/lib/*.ts          plain modules
+blocks/<id>/server/*.ts       server-only files (route handlers)
+blocks/<id>/recipes/*.ts      server-side SDK recipes, type-checked in CI
+stacks/<id>.json              a named, ordered set of blocks + navigation
+```
+
+`blocks/_foundation/` is the block with id `foundation`; every other block depends on it.
+
+## What CI guarantees
+
+`operations`, component `tiers` and `scopes` are derived from the API contract and verified by
+`tests/blocks/`: an operation that does not exist, a tier that drifted, a missing file, a dependency
+cycle or an import that is not a declared peer dependency fails the build. Every component, hook, lib,
+server file and recipe is type-checked against the SDK sources.
+
+Blocks build their screens with `@graph8/sdk/ui`, and so does the foundation's `ConfirmSpendDialog` (a
+Radix Dialog, so it stacks correctly inside other dialogs and sheets). The rest of the foundation is plain
+JSX and `className`. An app that installs the foundation must therefore import the UI kit CSS
+(`@graph8/sdk/ui/styles.css`) and have the kit's optional peers installed: the foundation's `ui-styles`
+prerequisite says how to verify it.

package/blocks/_foundation/README.md

@@ -0,0 +1,78 @@
+# foundation
+
+Shared base every other block depends on. Install it first (the CLI does it for you).
+
+## What you get
+
+| File | What it is |
+|---|---|
+| `lib/g8-client.ts` | Browser caller: `g8Get/g8Post/g8Put/g8Patch/g8Delete` -> your own `/api/g8/...` proxy. No API key. Returns the API envelope `{ data, pagination? }`, throws `G8Error`. |
+| `server/proxy.ts` | `createG8Proxy(config)`: the logic of the proxy (forwarding, allowlist, `authorize` hook). |
+| `server/route.ts` | Installs as `app/api/g8/[...path]/route.ts` and mounts the proxy. |
+| `hooks/use-g8-query.ts` | `useG8Query(fetcher, deps)` -> `{ data, error, loading, refetch }`. Latest request wins. |
+| `hooks/use-g8-mutation.ts` | `useG8Mutation(fn)` -> `{ mutate, mutateAsync, data, error, loading, reset }`. |
+| `hooks/use-paginated.ts` | `usePaginated(fetchPage, deps)` -> `{ items, hasMore, loadMore, reload, loading, loadingMore, error }`. Follows `pagination.next_cursor`. |
+| `hooks/use-job-poll.ts` | `useJobPoll(fetchStatus, { isTerminal })` -> `{ status, done, polling, error, start, stop }`. For jobs: the API has no streams, so poll with backoff. |
+| `components/confirm-spend-dialog.tsx` | `ConfirmSpendDialog`: shows tier, estimated credits, recipients, before a billable/external/destructive call. |
+| `components/api-error.tsx` | `ApiError`: shows `detail`, 422 field errors, request id, retry. |
+| `components/empty-state.tsx` | `EmptyState`: empty list with a first step. |
+
+## Flow of every call
+
+1. A component calls a hook: `useG8Query((signal) => g8Get("/contacts", { limit: 50 }, { signal }), [])`.
+2. `g8-client` requests `/api/g8/contacts?limit=50` on your own origin.
+3. The route handler checks `authorize`, then `allowedPrefixes`, then forwards to
+   `${G8_API_URL ?? "https://be.graph8.com"}/api/v1/contacts?limit=50` with `Authorization: Bearer $G8_API_KEY`.
+4. The response (status, body, request id) comes back unchanged; failures become `G8Error`.
+
+Ids that pass between calls always come from a previous response (a list's `id` into the next call's
+path). Never invent one.
+
+## Tiers: when to confirm
+
+Every operation has a tier (`read`, `write`, `billable`, `external`, `destructive`); each component's
+`tiers` in `block.json` is derived from the contract. Before a component triggers a `billable`,
+`external` or `destructive` operation, open `ConfirmSpendDialog` (`tierRequiresConfirmation(tier)` tells
+you). Say what will happen and how much: credits, recipients, records.
+
+```tsx
+<ConfirmSpendDialog open={open} tier="external" title="Send to 240 contacts" recipients={240}
+  confirming={send.loading} onConfirm={() => send.mutate(...)} onCancel={() => setOpen(false)} />
+```
+
+## Proxy security model
+
+The browser never sees the API key. It lives in `G8_API_KEY` on the server (never `NEXT_PUBLIC_*`).
+
+But the proxy route is **exactly as powerful as the key**: anyone who can reach `/api/g8` can do whatever
+the key can. So:
+
+The proxy therefore **refuses every request (500) until you configure it**:
+
+1. **`authorize`** (required): check YOUR session and return a 401/403 `Response` to refuse.
+2. **`allowedPrefixes`** (required): the API areas the UI actually uses (`["contacts", "companies"]`).
+   Anything else gets a 403. Prefixes match whole path segments.
+3. **Use the narrowest key**: scopes of the installed blocks only (each `block.json` lists them).
+4. **Agency keys and the org**: the browser's `X-Target-Org-Id` is NOT forwarded by default, because an
+   app session does not authorize switching between client orgs. Decide the org on the server from the
+   session: `targetOrgId: async (req) => (await getSession(req))?.g8OrgId`. (`allowTargetOrgHeader: true`
+   forwards the browser's header; do not use it with end-user traffic.)
+5. Local prototypes only: `dangerouslyAllowUnauthenticated: true` and `dangerouslyAllowAllPaths: true`
+   switch the two gates off. Never ship them.
+
+What the proxy does on its own: rejects `..`, encoded slashes and empty segments (400); forwards only
+`content-type`, `accept`, `accept-language` and `idempotency-key` (never the browser's cookies or
+`Authorization`); strips hop-by-hop headers, `set-cookie` and `location` from the response; does not follow
+redirects (an upstream 3xx becomes a 502); caps the request body at 5 MiB (413), enforced while streaming so
+an oversized upload is never held whole in memory; returns 500 with a clear message if `G8_API_KEY` is unset
+and a generic 502 if graph8 is unreachable. The key is never logged, echoed or included in any response.
+
+## Prerequisites
+
+- `G8_API_KEY` in the server env; verify with `recipes/verify-proxy-key.ts`.
+- `@graph8/sdk/ui/styles.css` imported in the app, plus the UI kit's optional peers (`ConfirmSpendDialog` uses the kit's Dialog).
+- Next.js App Router, React 18+, the `@/*` import alias (files install under `g8/`, imported as `@/g8/...`).
+
+## Defaults the agent should ask about
+
+- How the proxy knows a caller is a signed-in user of the app (`authorize`), and which API areas to allow: **ask the person**. The proxy will not run until both are set.

package/blocks/_foundation/block.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "foundation",
+  "title": "Foundation",
+  "summary": "Shared base for every block: browser client, data hooks, Next.js proxy route, confirm/error/empty components.",
+  "features": ["browser-safe API calls via a server proxy", "query, mutation, pagination and job-polling hooks", "spend/send/delete confirmation dialog"],
+  "dependsOn": [],
+  "operations": [],
+  "components": [
+    {
+      "name": "ConfirmSpendDialog",
+      "file": "components/confirm-spend-dialog.tsx",
+      "purpose": "Show tier, estimated credits and recipients, and require a click, before a billable, external or destructive operation.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "ApiError",
+      "file": "components/api-error.tsx",
+      "purpose": "Inline error panel for a failed call: shows the API detail, 422 field errors, request id and a retry button.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "EmptyState",
+      "file": "components/empty-state.tsx",
+      "purpose": "Empty-list placeholder with a title, hint and an optional first-step action.",
+      "operations": [],
+      "tiers": []
+    }
+  ],
+  "hooks": [
+    { "name": "useG8Query", "file": "hooks/use-g8-query.ts", "purpose": "Load data with loading/error/data, an out-of-order guard and refetch." },
+    { "name": "useG8Mutation", "file": "hooks/use-g8-mutation.ts", "purpose": "Run a write with loading/error state and success/error callbacks." },
+    { "name": "usePaginated", "file": "hooks/use-paginated.ts", "purpose": "Cursor pagination over the API envelope (pagination.next_cursor) with load-more and reload." },
+    { "name": "useJobPoll", "file": "hooks/use-job-poll.ts", "purpose": "Poll a job-status fetcher with backoff until a terminal state (the API has no streams)." }
+  ],
+  "lib": [
+    { "file": "lib/g8-client.ts", "purpose": "Browser caller for the app's own /api/g8 proxy. Holds no key, returns the SDK envelope, throws G8Error." }
+  ],
+  "server": [
+    { "file": "server/proxy.ts", "purpose": "createG8Proxy(): forwards browser calls to the graph8 API with the server-side key, a required path allowlist and authorize hook (it refuses to run without them) and a server-side org hook.", "target": "g8/server/proxy.ts" },
+    { "file": "server/route.ts", "purpose": "The Next.js App Router catch-all route that mounts the proxy.", "target": "app/api/g8/[...path]/route.ts" }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/verify-proxy-key.ts",
+      "title": "Check the proxy's server key before shipping",
+      "when": "After setting G8_API_KEY for the proxy route; fails fast on a wrong, expired or unscoped key."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "api-key",
+      "description": "A graph8 API key with the scopes of the blocks you install, set as G8_API_KEY in the server environment (never NEXT_PUBLIC_*).",
+      "where": "app",
+      "verify": "G8_API_KEY is set in .env.local and `describeCurrentKey` succeeds (recipes/verify-proxy-key.ts)."
+    },
+    {
+      "id": "nextjs-app-router",
+      "description": "A Next.js App Router app (React 18+) with the `@/*` import alias, so `@/g8/*` resolves to the installed g8 directory.",
+      "where": "app",
+      "verify": "app/ directory exists and tsconfig.json maps \"@/*\" to the project root or src/."
+    },
+    {
+      "id": "ui-styles",
+      "description": "ConfirmSpendDialog is built on @graph8/sdk/ui (Radix Dialog in a portal). Its positioning, overlay and surface classes only exist if the app imports the UI kit CSS (`@graph8/sdk/ui/styles.css`, or tokens.css + theme.css with Tailwind scanning node_modules/@graph8/sdk/dist) and has the kit's optional peers installed (at least @radix-ui/react-dialog, lucide-react, clsx, tailwind-merge).",
+      "where": "app",
+      "verify": "app/layout.tsx (or the global CSS) imports @graph8/sdk/ui/styles.css, and `npm ls @radix-ui/react-dialog lucide-react` lists them."
+    }
+  ],
+  "scopes": [],
+  "defaults": [
+    { "decision": "Which API paths the browser may call through the proxy", "default": "Only the areas the installed blocks use (allowedPrefixes, required), not all of /api/v1", "askHuman": false },
+    { "decision": "How the proxy knows the caller is a signed-in user of the app", "default": "None: the route refuses every request until `authorize` is set", "askHuman": true },
+    { "decision": "Styling", "default": "Tailwind utility classes on plain elements; overlays (ConfirmSpendDialog) and later blocks use @graph8/sdk/ui, so import its CSS", "askHuman": false }
+  ],
+  "peerDependencies": { "react": ">=18" }
+}

package/blocks/_foundation/components/api-error.tsx

@@ -0,0 +1,62 @@
+"use client";
+
+import { G8Error } from "@graph8/sdk";
+
+export interface ApiErrorProps {
+  error: unknown;
+  title?: string;
+  /** Shows a Retry button. */
+  onRetry?: () => void;
+  className?: string;
+}
+
+interface FieldError {
+  loc?: unknown[];
+  msg?: string;
+}
+
+/** A readable one-line reason for any thrown value. 422 field errors are listed. */
+export function describeError(error: unknown): { message: string; fields: string[]; status?: number; requestId?: string } {
+  if (error instanceof G8Error) {
+    const fields = Array.isArray(error.detail)
+      ? (error.detail as FieldError[]).map((f) => `${(f.loc ?? []).filter((p) => p !== "body").join(".")}: ${f.msg ?? ""}`.trim())
+      : [];
+    const message =
+      typeof error.detail === "string" ? error.detail : fields.length ? "Some fields are invalid." : explain(error);
+    return { message, fields, status: error.status, requestId: error.requestId };
+  }
+  return { message: error instanceof Error ? error.message : "Something went wrong.", fields: [] };
+}
+
+function explain(error: G8Error): string {
+  if (error.status === 401) return "Your session with graph8 is not valid. Check the server API key.";
+  if (error.status === 403) return "This API key is not allowed to do that (missing scope, or the proxy blocked the path).";
+  if (error.status === 429) return "graph8 is rate limiting requests. Wait a moment and retry.";
+  if (error.status === 0) return "Could not reach the server. Check your connection.";
+  return error.message;
+}
+
+/** Inline error panel for a failed graph8 call. Always shows `detail`, not just `message`. */
+export function ApiError({ error, title = "Something went wrong", onRetry, className }: ApiErrorProps) {
+  if (error == null) return null;
+  const info = describeError(error);
+  return (
+    <div role="alert" className={`rounded border border-red-200 bg-red-50 p-4 text-sm ${className ?? ""}`}>
+      <p className="font-medium text-red-900">{title}</p>
+      <p className="mt-1 text-red-800">{info.message}</p>
+      {info.fields.length > 0 ? (
+        <ul className="mt-2 list-disc pl-5 text-red-800">
+          {info.fields.map((line) => (
+            <li key={line}>{line}</li>
+          ))}
+        </ul>
+      ) : null}
+      {info.requestId ? <p className="mt-2 text-xs text-red-700">Request id: {info.requestId}</p> : null}
+      {onRetry ? (
+        <button type="button" onClick={onRetry} className="mt-3 rounded border border-red-300 bg-white px-3 py-1 text-red-900">
+          Retry
+        </button>
+      ) : null}
+    </div>
+  );
+}

package/blocks/_foundation/components/confirm-spend-dialog.tsx

@@ -0,0 +1,142 @@
+"use client";
+
+import { useRef } from "react";
+import type { ReactNode } from "react";
+import { Dialog, DialogContent, DialogDescription, DialogTitle } from "@graph8/sdk/ui";
+
+/** The tiers that must be confirmed by a person before the call is made. */
+export type ConfirmTier = "billable" | "external" | "destructive";
+
+export interface ConfirmSpendDialogProps {
+  open: boolean;
+  tier: ConfirmTier;
+  /** What will happen, in one sentence: "Enrich 240 contacts". */
+  title: string;
+  description?: ReactNode;
+  /** Estimated credits the action will spend (billable). */
+  estimatedCredits?: number;
+  /** People who will be messaged or called (external). */
+  recipients?: number;
+  /** Records that will be removed (destructive). */
+  affected?: number;
+  confirmLabel?: string;
+  cancelLabel?: string;
+  /** Disable the buttons while the confirmed call runs. */
+  confirming?: boolean;
+  onConfirm: () => void;
+  onCancel: () => void;
+  className?: string;
+}
+
+const TIER_COPY: Record<ConfirmTier, { badge: string; confirm: string; note: string }> = {
+  billable: { badge: "Uses credits", confirm: "Spend credits", note: "This action spends credits from your balance." },
+  external: {
+    badge: "Contacts people",
+    confirm: "Send",
+    note: "This reaches real people outside your workspace and cannot be recalled.",
+  },
+  destructive: { badge: "Cannot be undone", confirm: "Delete", note: "This permanently removes data." },
+};
+
+/** True for the tiers an app should confirm before calling. read/write never need it. */
+export function tierRequiresConfirmation(tier: string): tier is ConfirmTier {
+  return tier === "billable" || tier === "external" || tier === "destructive";
+}
+
+function facts(props: ConfirmSpendDialogProps): string[] {
+  const out: string[] = [];
+  if (props.estimatedCredits != null) out.push(`About ${props.estimatedCredits.toLocaleString()} credits`);
+  if (props.recipients != null) out.push(`${props.recipients.toLocaleString()} recipients`);
+  if (props.affected != null) out.push(`${props.affected.toLocaleString()} records affected`);
+  return out;
+}
+
+/**
+ * Show what an action will cost or do BEFORE a billable, external or
+ * destructive operation runs. The operation's tier is in the block manifest
+ * (`components[].tiers`) and in `g8.api.operation(id).tier`; read/write calls
+ * do not need this dialog.
+ *
+ * Built on the UI kit's Dialog (Radix) and rendered in a portal, so it stacks
+ * correctly when opened from inside another open Dialog or Sheet: a modal sets
+ * `pointer-events: none` on the page and marks everything outside itself inert,
+ * which made a plain fixed `div` unclickable there. Radix layers nest, so this
+ * dialog is interactive, Escape closes only the top layer, focus moves into it
+ * (on Cancel, the safe choice) and returns to where it was when it closes.
+ * A stray click outside never dismisses it.
+ */
+export function ConfirmSpendDialog(props: ConfirmSpendDialogProps) {
+  const { open, tier, title, description, confirming, onConfirm, onCancel } = props;
+  const cancelRef = useRef<HTMLButtonElement>(null);
+  // Radix only restores focus to a Dialog.Trigger; this dialog is opened by state, so remember the opener.
+  const openerRef = useRef<HTMLElement | null>(null);
+  const copy = TIER_COPY[tier];
+  const summary = facts(props);
+  // Radix puts pointer-events: none on the body while a modal is open; its own
+  // layers opt back in, and the explicit style keeps that true under any host CSS.
+  const interactive = { pointerEvents: "auto" } as const;
+
+  return (
+    <Dialog open={open} onOpenChange={(next) => (!next && !confirming ? onCancel() : undefined)}>
+      <DialogContent
+        role="alertdialog"
+        showCloseButton={false}
+        data-tier={tier}
+        style={interactive}
+        className={`max-w-md sm:max-w-md bg-white p-5 shadow-xl ${props.className ?? ""}`}
+        onOpenAutoFocus={(event) => {
+          event.preventDefault();
+          openerRef.current = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+          cancelRef.current?.focus();
+        }}
+        onCloseAutoFocus={(event) => {
+          event.preventDefault();
+          const opener = openerRef.current;
+          if (opener?.isConnected) opener.focus();
+          openerRef.current = null;
+        }}
+        onInteractOutside={(event) => event.preventDefault()}
+        onEscapeKeyDown={(event) => confirming && event.preventDefault()}
+      >
+        <span className="inline-block w-fit rounded bg-gray-100 px-2 py-0.5 text-xs font-medium text-gray-700">
+          {copy.badge}
+        </span>
+        <DialogTitle className="text-base font-semibold text-gray-900">{title}</DialogTitle>
+        <DialogDescription asChild>
+          <div className="space-y-2 text-sm text-gray-600">
+            {description ? <div>{description}</div> : null}
+            {summary.length > 0 ? (
+              <ul className="list-disc pl-5 text-gray-900">
+                {summary.map((line) => (
+                  <li key={line}>{line}</li>
+                ))}
+              </ul>
+            ) : null}
+            <p>{copy.note}</p>
+          </div>
+        </DialogDescription>
+        <div className="flex justify-end gap-2">
+          <button
+            ref={cancelRef}
+            type="button"
+            disabled={confirming}
+            onClick={onCancel}
+            style={interactive}
+            className="rounded border border-gray-300 px-3 py-1.5 text-sm text-gray-700 disabled:opacity-50"
+          >
+            {props.cancelLabel ?? "Cancel"}
+          </button>
+          <button
+            type="button"
+            disabled={confirming}
+            onClick={onConfirm}
+            style={interactive}
+            className="rounded bg-gray-900 px-3 py-1.5 text-sm font-medium text-white disabled:opacity-50"
+          >
+            {confirming ? "Working..." : (props.confirmLabel ?? copy.confirm)}
+          </button>
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/blocks/_foundation/components/empty-state.tsx

@@ -0,0 +1,24 @@
+"use client";
+
+import type { ReactNode } from "react";
+
+export interface EmptyStateProps {
+  title: string;
+  description?: ReactNode;
+  /** Usually a button that creates the first record. */
+  action?: ReactNode;
+  icon?: ReactNode;
+  className?: string;
+}
+
+/** Shown when a list is empty. Say what will appear here and offer the first step. */
+export function EmptyState({ title, description, action, icon, className }: EmptyStateProps) {
+  return (
+    <div className={`flex flex-col items-center justify-center gap-2 px-6 py-12 text-center ${className ?? ""}`}>
+      {icon ? <div className="text-gray-400">{icon}</div> : null}
+      <h3 className="text-sm font-semibold text-gray-900">{title}</h3>
+      {description ? <p className="max-w-sm text-sm text-gray-500">{description}</p> : null}
+      {action ? <div className="mt-2">{action}</div> : null}
+    </div>
+  );
+}

package/blocks/_foundation/hooks/use-g8-mutation.ts

@@ -0,0 +1,88 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export interface UseG8MutationOptions<TVars, TResult> {
+  onSuccess?: (result: TResult, vars: TVars) => void;
+  onError?: (error: unknown, vars: TVars) => void;
+}
+
+export interface UseG8MutationResult<TVars, TResult> {
+  /** Run the write. Never rejects: failures land in `error` (and `onError`). Resolves undefined on failure. */
+  mutate: (vars: TVars) => Promise<TResult | undefined>;
+  /** Same, but rejects on failure, for code that wants try/catch. */
+  mutateAsync: (vars: TVars) => Promise<TResult>;
+  data: TResult | undefined;
+  error: unknown;
+  loading: boolean;
+  reset: () => void;
+}
+
+/**
+ * Wrap a write (create, update, enroll, send...) with loading and error state.
+ *
+ * Calls made while a request is in flight are still sent; the state shown is
+ * always the LATEST call's. `onSuccess`/`onError` still fire if the component
+ * unmounted meanwhile (so a toast or cache update is not lost); guard them yourself
+ * if they touch component state. To stop double submits, disable the button on
+ * `loading`, and pass a stable `idempotencyKey` for writes that may repeat.
+ *
+ *   const save = useG8Mutation((vars: { id: number }) => g8Patch(`/contacts/${vars.id}`, vars));
+ */
+export function useG8Mutation<TVars, TResult>(
+  mutation: (vars: TVars) => Promise<TResult>,
+  options: UseG8MutationOptions<TVars, TResult> = {},
+): UseG8MutationResult<TVars, TResult> {
+  const mutationRef = useRef(mutation);
+  mutationRef.current = mutation;
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const latest = useRef(0);
+  const mounted = useRef(true);
+  const [data, setData] = useState<TResult | undefined>(undefined);
+  const [error, setError] = useState<unknown>(undefined);
+  const [loading, setLoading] = useState(false);
+
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+
+  const mutateAsync = useCallback(async (vars: TVars): Promise<TResult> => {
+    const id = ++latest.current;
+    setLoading(true);
+    setError(undefined);
+    try {
+      const result = await mutationRef.current(vars);
+      if (id === latest.current && mounted.current) {
+        setData(result);
+        setLoading(false);
+      }
+      optionsRef.current.onSuccess?.(result, vars);
+      return result;
+    } catch (err) {
+      if (id === latest.current && mounted.current) {
+        setError(err);
+        setLoading(false);
+      }
+      optionsRef.current.onError?.(err, vars);
+      throw err;
+    }
+  }, []);
+
+  const mutate = useCallback(
+    (vars: TVars): Promise<TResult | undefined> => mutateAsync(vars).catch(() => undefined),
+    [mutateAsync],
+  );
+
+  const reset = useCallback(() => {
+    latest.current++;
+    setData(undefined);
+    setError(undefined);
+    setLoading(false);
+  }, []);
+
+  return { mutate, mutateAsync, data, error, loading, reset };
+}