@valyrianjs/terminal 0.1.0 → 0.1.2

package/docs/valyrian-modules.md

@@ -0,0 +1,3196 @@
+# Valyrian.js modules in terminal apps
+
+## Overview / quick picks
+
+Terminal apps need app-layer modules for state, API clients, async tasks, forms, persistence, formatting, localization, and small data helpers. The terminal adapter owns terminal UI/input/output: rendering terminal nodes, focus, keyboard and mouse dispatch, output snapshots, stream cleanup, and host integration. Valyrian.js modules own app workflows: request execution, cache lifecycle, task state, form validation, saved settings, translated labels, money values, and data shaping.
+
+This guide shows terminal-specific patterns and points you to the Valyrian.js module docs when you need complete API details.
+
+Quick picks:
+
+- Start with `valyrian.js` when you need the core runtime and component model for TSX terminal screens.
+- Use `valyrian.js/pulses` for small reactive state and transitions inside one screen.
+- Use `valyrian.js/flux-store` when updates need named operations, reducers, and workflow state.
+- Use `valyrian.js/request`, `valyrian.js/query`, and `valyrian.js/tasks` for API clients, cached reads, and longer user-started work.
+- Use `valyrian.js/forms`, `valyrian.js/native-store`, `valyrian.js/translate`, `valyrian.js/money`, and `valyrian.js/utils` for settings screens, saved preferences, labels, totals, and shaped display data.
+- Start with the single-module examples, then combine modules through the composed workflows at the end.
+
+Use `valyrian.js/translate`, `valyrian.js/money`, and `valyrian.js/utils` when a terminal screen presents product data, localized labels, totals, and shaped view models. Feed the renderer prepared display data while workflow rules stay in the app layer.
+
+## Primary module examples
+
+Each module below maps to a complete usable terminal demo. Run any file directly with Bun and quit with `Ctrl+C`. Each code block embeds the full runnable source so readers can copy, paste, and adapt the example without opening another file.
+
+### `valyrian.js`
+
+Build TSX terminal screens with the Valyrian component model. Demo app: **Terminal Command Palette**.
+
+Complete demo: **Terminal Command Palette** ([`examples/docs/module-valyrian-core.tsx`](../examples/docs/module-valyrian-core.tsx)). Run it with `bun examples/docs/module-valyrian-core.tsx`, move with `J/K`, run a command with `Enter`, reset with `R`, and quit with `Ctrl+C`.
+
+Complete runnable example:
+
+```tsx
+import { v } from "valyrian.js";
+import { Pane, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface ModuleDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+type Command = {
+  id: string;
+  name: string;
+  result: string;
+};
+
+type CommandPaletteState = {
+  selected: number;
+  result: string;
+  history: string[];
+};
+
+const COMMANDS: Command[] = [
+  { id: "open-incidents", name: "Open incident board", result: "Incident board opened" },
+  { id: "assign-oncall", name: "Assign on-call engineer", result: "On-call engineer assigned" },
+  { id: "publish-summary", name: "Publish shift summary", result: "Shift summary published" }
+];
+
+const INITIAL_RESULT = "Choose a command";
+const PANEL_STYLE = { color: "#f8fafc", background: "#111827", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#dbeafe", background: "#1e293b" };
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function clampSelection(index: number) {
+  return (index + COMMANDS.length) % COMMANDS.length;
+}
+
+const manualNode = v(Text, null, "Manual vnode: quick actions are composed with TSX rows");
+
+export function App({ state }: { state: CommandPaletteState }) {
+  return (
+    <Screen title="Terminal Command Palette">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Terminal Command Palette</Text>
+      <Pane style={PANEL_STYLE}>
+        <Text>Command Palette</Text>
+        {manualNode}
+        {COMMANDS.map((command, index) => (
+          <Text>{`${index === state.selected ? ">" : " "} ${command.name}`}</Text>
+        ))}
+        <Text>{`Result: ${state.result}`}</Text>
+        <Text>{`History: ${state.history.length ? state.history.join(" -> ") : "none"}`}</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>J/K move   Enter run command   R reset   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModuleValyrianCoreDemo(options: TerminalMountOptions = {}): ModuleDemo {
+  const state: CommandPaletteState = { selected: 0, result: INITIAL_RESULT, history: [] };
+  let running = true;
+  let session: TerminalSession;
+
+  function quit() {
+    running = false;
+    session.destroy();
+  }
+
+  function runSelectedCommand() {
+    const command = COMMANDS[state.selected];
+    state.result = command.result;
+    state.history = [...state.history.slice(-2), command.name];
+  }
+
+  function reset() {
+    state.selected = 0;
+    state.result = INITIAL_RESULT;
+    state.history = [];
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    cols: options.cols ?? 92,
+    rows: options.rows ?? 18,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "j", command: { id: "palette.next" }, scope: "global" },
+        { key: "J", command: { id: "palette.next" }, scope: "global" },
+        { key: "k", command: { id: "palette.previous" }, scope: "global" },
+        { key: "K", command: { id: "palette.previous" }, scope: "global" },
+        { key: "ENTER", command: { id: "palette.run" }, scope: "global" },
+        { key: "r", command: { id: "palette.reset" }, scope: "global" },
+        { key: "R", command: { id: "palette.reset" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "palette.next") {
+          state.selected = clampSelection(state.selected + 1);
+          return true;
+        }
+        if (command.id === "palette.previous") {
+          state.selected = clampSelection(state.selected - 1);
+          return true;
+        }
+        if (command.id === "palette.run") {
+          runSelectedCommand();
+          return true;
+        }
+        if (command.id === "palette.reset") {
+          reset();
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  return {
+    session,
+    dispatchKey(key: string) {
+      return session.dispatchKey(key);
+    },
+    output() {
+      return session.output();
+    },
+    ansiOutput() {
+      return session.ansiOutput();
+    },
+    isRunning() {
+      return running;
+    },
+    destroy() {
+      running = false;
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleValyrianCoreDemo({ runtime: "headless", cols: 92, rows: 18 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleValyrianCoreDemo();
+  }
+}
+```
+
+See the Valyrian.js documentation for the full `valyrian.js` API.
+
+### `valyrian.js/pulses`
+
+Add reactive counters, toggles, and lightweight shared state. Demo app: **Live Shift/Ticket Counter**.
+
+Complete demo: **Live Shift/Ticket Counter** ([`examples/docs/module-pulses.tsx`](../examples/docs/module-pulses.tsx)). Run it with `bun examples/docs/module-pulses.tsx`, add tickets with `A`, resolve tickets with `D`, toggle the priority lane with `P`, reset with `R`, and quit with `Ctrl+C`.
+
+Complete runnable example:
+
+```tsx
+import { createPulse } from "valyrian.js/pulses";
+import { Pane, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface ModuleDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+type ShiftPulses = {
+  open: () => number;
+  resolved: () => number;
+  priority: () => boolean;
+};
+
+const INITIAL_OPEN = 4;
+const INITIAL_RESOLVED = 1;
+const PANEL_STYLE = { color: "#f8fafc", background: "#111827", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#dbeafe", background: "#1e293b" };
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+export function App({ pulses }: { pulses: ShiftPulses }) {
+  const open = pulses.open();
+  const resolved = pulses.resolved();
+  const priority = pulses.priority();
+
+  return (
+    <Screen title="Live Shift/Ticket Counter">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Live Shift/Ticket Counter</Text>
+      <Pane style={PANEL_STYLE}>
+        <Text>Shift/Ticket Counter</Text>
+        <Text>{`Open tickets: ${open}`}</Text>
+        <Text>{`Resolved this shift: ${resolved}`}</Text>
+        <Text>{`Priority lane: ${priority ? "active" : "normal"}`}</Text>
+        <Text>{`Workload: ${open > 5 || priority ? "watch closely" : "steady"}`}</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>A add ticket   D resolve ticket   P priority lane   R reset   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModulePulsesDemo(options: TerminalMountOptions = {}): ModuleDemo {
+  const [openTickets, setOpenTickets] = createPulse(INITIAL_OPEN);
+  const [resolvedTickets, setResolvedTickets] = createPulse(INITIAL_RESOLVED);
+  const [priorityActive, setPriorityActive] = createPulse(false);
+  let running = true;
+  let session: TerminalSession;
+
+  function quit() {
+    running = false;
+    session.destroy();
+  }
+
+  function reset() {
+    setOpenTickets(INITIAL_OPEN);
+    setResolvedTickets(INITIAL_RESOLVED);
+    setPriorityActive(false);
+  }
+
+  session = mountTerminal(<App pulses={{ open: openTickets, resolved: resolvedTickets, priority: priorityActive }} />, {
+    ...options,
+    cols: options.cols ?? 92,
+    rows: options.rows ?? 16,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "a", command: { id: "tickets.add" }, scope: "global" },
+        { key: "A", command: { id: "tickets.add" }, scope: "global" },
+        { key: "d", command: { id: "tickets.resolve" }, scope: "global" },
+        { key: "D", command: { id: "tickets.resolve" }, scope: "global" },
+        { key: "p", command: { id: "tickets.priority" }, scope: "global" },
+        { key: "P", command: { id: "tickets.priority" }, scope: "global" },
+        { key: "r", command: { id: "tickets.reset" }, scope: "global" },
+        { key: "R", command: { id: "tickets.reset" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "tickets.add") {
+          setOpenTickets((value) => value + 1);
+          return true;
+        }
+        if (command.id === "tickets.resolve") {
+          setOpenTickets((value) => Math.max(0, value - 1));
+          setResolvedTickets((value) => value + 1);
+          return true;
+        }
+        if (command.id === "tickets.priority") {
+          setPriorityActive((value) => !value);
+          return true;
+        }
+        if (command.id === "tickets.reset") {
+          reset();
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  return {
+    session,
+    dispatchKey(key: string) {
+      return session.dispatchKey(key);
+    },
+    output() {
+      return session.output();
+    },
+    ansiOutput() {
+      return session.ansiOutput();
+    },
+    isRunning() {
+      return running;
+    },
+    destroy() {
+      running = false;
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModulePulsesDemo({ runtime: "headless", cols: 92, rows: 16 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModulePulsesDemo();
+  }
+}
+```
+
+See the Valyrian.js documentation for the full `valyrian.js/pulses` API.
+
+### `valyrian.js/flux-store`
+
+Model command workflows with named operations and shared app state. Demo app: **Operations Queue Manager**.
+
+Complete demo: **Operations Queue Manager** ([`examples/docs/module-flux-store.tsx`](../examples/docs/module-flux-store.tsx)). Run it with `bun examples/docs/module-flux-store.tsx`, select with `J/K`, start with `S`, mark done with `D`, block with `B`, reset with `R`, and quit with `Ctrl+C`.
+
+Complete runnable example:
+
+```tsx
+import { FluxStore } from "valyrian.js/flux-store";
+import { Pane, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface ModuleDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+type JobStatus = "queued" | "running" | "done" | "blocked";
+type Job = { name: string; status: JobStatus };
+type QueueState = { selected: number; jobs: Job[] };
+
+type QueueGetters = { doneCount: number; activeJob: string };
+type QueueStore = FluxStore & { state: QueueState; getters: QueueGetters };
+
+const INITIAL_JOBS: Job[] = [
+  { name: "Sync warehouse feed", status: "queued" },
+  { name: "Package release", status: "queued" },
+  { name: "Review failed payouts", status: "blocked" }
+];
+const PANEL_STYLE = { color: "#f8fafc", background: "#111827", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#dbeafe", background: "#1e293b" };
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function createQueueStore(): QueueStore {
+  return new FluxStore({
+    state: { selected: 0, jobs: INITIAL_JOBS.map((job) => ({ ...job })) },
+    mutations: {
+      SELECT_NEXT(state) {
+        const queueState = state as QueueState;
+        queueState.selected = (queueState.selected + 1) % queueState.jobs.length;
+      },
+      SELECT_PREVIOUS(state) {
+        const queueState = state as QueueState;
+        queueState.selected = (queueState.selected - 1 + queueState.jobs.length) % queueState.jobs.length;
+      },
+      SET_STATUS(state, status: JobStatus) {
+        const queueState = state as QueueState;
+        queueState.jobs = queueState.jobs.map((job, index) => (index === queueState.selected ? { ...job, status } : job));
+      },
+      RESET(state) {
+        const queueState = state as QueueState;
+        queueState.selected = 0;
+        queueState.jobs = INITIAL_JOBS.map((job) => ({ ...job }));
+      }
+    },
+    getters: {
+      doneCount(state) {
+        const queueState = state as QueueState;
+        return queueState.jobs.filter((job) => job.status === "done").length;
+      },
+      activeJob(state) {
+        const queueState = state as QueueState;
+        return queueState.jobs[queueState.selected].name;
+      }
+    }
+  }) as QueueStore;
+}
+
+export function App({ store }: { store: QueueStore }) {
+  return (
+    <Screen title="Operations Queue Manager">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Operations Queue Manager</Text>
+      <Pane style={PANEL_STYLE}>
+        <Text>Queue Manager</Text>
+        {store.state.jobs.map((job, index) => (
+          <Text>{`${index === store.state.selected ? ">" : " "} ${job.name} — ${job.status}`}</Text>
+        ))}
+        <Text>{`Selected: ${store.getters.activeJob}`}</Text>
+        <Text>{`Done jobs: ${store.getters.doneCount}`}</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>J/K select   S start   D mark done   B block   R reset   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModuleFluxStoreDemo(options: TerminalMountOptions = {}): ModuleDemo {
+  const store = createQueueStore();
+  let running = true;
+  let session: TerminalSession;
+
+  function quit() {
+    running = false;
+    session.destroy();
+  }
+
+  session = mountTerminal(<App store={store} />, {
+    ...options,
+    cols: options.cols ?? 92,
+    rows: options.rows ?? 18,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "j", command: { id: "queue.next" }, scope: "global" },
+        { key: "J", command: { id: "queue.next" }, scope: "global" },
+        { key: "k", command: { id: "queue.previous" }, scope: "global" },
+        { key: "K", command: { id: "queue.previous" }, scope: "global" },
+        { key: "s", command: { id: "queue.start" }, scope: "global" },
+        { key: "S", command: { id: "queue.start" }, scope: "global" },
+        { key: "d", command: { id: "queue.done" }, scope: "global" },
+        { key: "D", command: { id: "queue.done" }, scope: "global" },
+        { key: "b", command: { id: "queue.block" }, scope: "global" },
+        { key: "B", command: { id: "queue.block" }, scope: "global" },
+        { key: "r", command: { id: "queue.reset" }, scope: "global" },
+        { key: "R", command: { id: "queue.reset" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "queue.next") {
+          store.commit("SELECT_NEXT");
+          return true;
+        }
+        if (command.id === "queue.previous") {
+          store.commit("SELECT_PREVIOUS");
+          return true;
+        }
+        if (command.id === "queue.start") {
+          store.commit("SET_STATUS", "running");
+          return true;
+        }
+        if (command.id === "queue.done") {
+          store.commit("SET_STATUS", "done");
+          return true;
+        }
+        if (command.id === "queue.block") {
+          store.commit("SET_STATUS", "blocked");
+          return true;
+        }
+        if (command.id === "queue.reset") {
+          store.commit("RESET");
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  return {
+    session,
+    dispatchKey(key: string) {
+      return session.dispatchKey(key);
+    },
+    output() {
+      return session.output();
+    },
+    ansiOutput() {
+      return session.ansiOutput();
+    },
+    isRunning() {
+      return running;
+    },
+    destroy() {
+      running = false;
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleFluxStoreDemo({ runtime: "headless", cols: 92, rows: 18 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleFluxStoreDemo();
+  }
+}
+```
+
+See the Valyrian.js documentation for the full `valyrian.js/flux-store` API.
+
+### `valyrian.js/request`
+
+Connect terminal screens to request helpers, parsing, and endpoint access. Demo app: **Service Status Client**.
+
+Complete demo: **Service Status Client** ([`examples/docs/module-request.tsx`](../examples/docs/module-request.tsx)). Run it with `bun examples/docs/module-request.tsx`, refresh status with `R`, force the next controlled error with `E`, and quit with `Ctrl+C`.
+
+Complete runnable example:
+
+```tsx
+import { request } from "valyrian.js/request";
+import { Pane, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface ModuleDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+interface RequestState {
+  status: "idle" | "loading" | "success" | "error";
+  message: string;
+  fetchedPath: string;
+  lastError: string;
+  failNext: boolean;
+  history: Array<"success" | "error">;
+  running: boolean;
+}
+
+const PANEL_STYLE = { color: "#f8fafc", background: "#111827", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#dbeafe", background: "#1e293b" };
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function createState(): RequestState {
+  return {
+    status: "idle",
+    message: "Ready to check the service status",
+    fetchedPath: "none",
+    lastError: "none",
+    failNext: false,
+    history: [],
+    running: true
+  };
+}
+
+function historySummary(history: RequestState["history"]) {
+  return history.length === 0 ? "none" : history.join(" -> ");
+}
+
+const api = request.new("http://terminal.local", { allowedMethods: ["get"] });
+
+async function withFakeFetch<T>(shouldFail: boolean, run: () => Promise<T>) {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = ((input: RequestInfo | URL) => {
+    const url = new URL(String(input));
+    if (shouldFail) {
+      return Promise.resolve(
+        new Response(JSON.stringify({ message: "controlled local failure" }), { status: 503 })
+      );
+    }
+    return Promise.resolve(
+      new Response(JSON.stringify({ status: "ok", path: `${url.pathname}${url.search}` }), { status: 200 })
+    );
+  }) as typeof fetch;
+
+  try {
+    return await run();
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+}
+
+export function App({ state }: { state: RequestState }) {
+  return (
+    <Screen title="Service Status Client">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Service Status Client</Text>
+      <Pane style={PANEL_STYLE}>
+        <Text>Status Client: checks a local service endpoint without using the network.</Text>
+        <Text>{`Request status: ${state.status}`}</Text>
+        <Text>{state.message}</Text>
+        <Text>{`Fetched: ${state.fetchedPath}`}</Text>
+        <Text>{`Last error: ${state.lastError}`}</Text>
+        <Text>{`Next request: ${state.failNext ? "controlled error" : "success"}`}</Text>
+        <Text>{`History: ${historySummary(state.history)}`}</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>R: refresh status   E: force next error   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModuleRequestDemo(options: TerminalMountOptions = {}): ModuleDemo {
+  const state = createState();
+  let session: TerminalSession;
+
+  async function loadStatus() {
+    if (state.status === "loading") {
+      state.message = "Refresh already in progress";
+      session.update();
+      return;
+    }
+
+    state.status = "loading";
+    state.message = "Loading local service status";
+    session.update();
+    try {
+      const shouldFail = state.failNext;
+      state.failNext = false;
+      const body = (await withFakeFetch(shouldFail, () => api.get("/status", { page: 1 }))) as { status: string; path: string };
+      state.status = "success";
+      state.history.push("success");
+      state.message = state.lastError === "none" ? `HTTP status: ${body.status}` : `Retry result: ${body.status}`;
+      state.fetchedPath = body.path;
+    } catch (error) {
+      state.status = "error";
+      state.history.push("error");
+      state.message = error instanceof Error ? error.message : "Request failed";
+      state.lastError = state.message;
+      state.fetchedPath = "/status?page=1";
+    }
+    session.update();
+  }
+
+  function quit() {
+    state.running = false;
+    session.destroy();
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    cols: options.cols ?? 92,
+    rows: options.rows ?? 16,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "r", command: { id: "request.load" }, scope: "global" },
+        { key: "R", command: { id: "request.load" }, scope: "global" },
+        { key: "e", command: { id: "request.failNext" }, scope: "global" },
+        { key: "E", command: { id: "request.failNext" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "request.load") {
+          void loadStatus();
+          return true;
+        }
+        if (command.id === "request.failNext") {
+          state.failNext = true;
+          state.message = "Next refresh will use the controlled error path";
+          session.update();
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  return {
+    session,
+    dispatchKey(key: string) {
+      return session.dispatchKey(key);
+    },
+    output() {
+      return session.output();
+    },
+    ansiOutput() {
+      return session.ansiOutput();
+    },
+    isRunning() {
+      return state.running;
+    },
+    destroy() {
+      state.running = false;
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleRequestDemo({ runtime: "headless", cols: 92, rows: 16 });
+    demo.dispatchKey("E");
+    demo.dispatchKey("R");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    demo.dispatchKey("R");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleRequestDemo();
+  }
+}
+```
+
+See the Valyrian.js documentation for the full `valyrian.js/request` API.
+
+### `valyrian.js/query`
+
+Show cached read state with fetch, invalidate, status, and data lifecycle. Demo app: **Cached Inventory Browser**.
+
+Complete demo: **Cached Inventory Browser** ([`examples/docs/module-query.tsx`](../examples/docs/module-query.tsx)). Run it with `bun examples/docs/module-query.tsx`, fetch inventory with `F`, invalidate cache with `I`, select items with `J/K`, and quit with `Ctrl+C`.
+
+Complete runnable example:
+
+```tsx
+import { QueryClient } from "valyrian.js/query";
+import { Pane, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface ModuleDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+interface InventoryItem {
+  sku: string;
+  name: string;
+  category: string;
+  stock: number;
+}
+
+interface InventoryResult {
+  readLabel: string;
+  items: InventoryItem[];
+}
+
+interface QueryState {
+  value: string;
+  status: string;
+  invalidated: boolean;
+  fetchCount: number;
+  selectedIndex: number;
+  items: InventoryItem[];
+  running: boolean;
+}
+
+const PANEL_STYLE = { color: "#f8fafc", background: "#111827", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#dbeafe", background: "#1e293b" };
+
+const INVENTORY: InventoryItem[] = [
+  { sku: "OPS-100", name: "Battery pack", category: "Operations", stock: 12 },
+  { sku: "NET-210", name: "Switch kit", category: "Network", stock: 4 },
+  { sku: "SEC-404", name: "Seal tags", category: "Security", stock: 30 }
+];
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function selectedItem(state: QueryState) {
+  return state.items[state.selectedIndex] || null;
+}
+
+export function App({ state }: { state: QueryState }) {
+  const item = selectedItem(state);
+  return (
+    <Screen title="Cached Inventory Browser">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Cached Inventory Browser</Text>
+      <Pane style={PANEL_STYLE}>
+        <Text>Inventory Browser: fetches local stock data through a Valyrian query cache.</Text>
+        <Text>{`Query status: ${state.status}`}</Text>
+        <Text>{`Cached value: ${state.value}`}</Text>
+        <Text>{`Invalidated: ${state.invalidated ? "yes" : "no"}`}</Text>
+        <Text>{`Fetcher calls: ${state.fetchCount}`}</Text>
+        <Text>{`Selected item: ${item ? `${item.name} (${item.sku})` : "none"}`}</Text>
+        <Text>{`Category: ${item ? item.category : "none"}`}</Text>
+        <Text>{`Stock on hand: ${item ? item.stock : 0}`}</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>F: fetch inventory   I: invalidate cache   J/K: select item   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModuleQueryDemo(options: TerminalMountOptions = {}): ModuleDemo {
+  const state: QueryState = {
+    value: "none",
+    status: "idle",
+    invalidated: false,
+    fetchCount: 0,
+    selectedIndex: 0,
+    items: [],
+    running: true
+  };
+  const client = new QueryClient({ staleTime: 30000, cacheTime: 1000 });
+  const query = client.query({
+    key: ["docs", "inventory"],
+    fetcher: (): InventoryResult => {
+      state.fetchCount += 1;
+      return {
+        readLabel: `terminal read #${state.fetchCount}`,
+        items: INVENTORY.map((item) => ({ ...item }))
+      };
+    }
+  });
+  let session: TerminalSession;
+
+  async function fetchInventory() {
+    state.status = "loading";
+    session.update();
+    const data = await query.fetch();
+    state.value = data?.readLabel || "none";
+    state.items = data?.items || [];
+    state.selectedIndex = Math.min(state.selectedIndex, Math.max(state.items.length - 1, 0));
+    state.status = query.state.status;
+    session.update();
+  }
+
+  function invalidateInventory() {
+    query.invalidate();
+    state.status = query.state.status;
+    state.invalidated = true;
+    session.update();
+  }
+
+  function moveSelection(delta: number) {
+    if (state.items.length === 0) {
+      return;
+    }
+    state.selectedIndex = (state.selectedIndex + delta + state.items.length) % state.items.length;
+    session.update();
+  }
+
+  function quit() {
+    state.running = false;
+    client.clear();
+    session.destroy();
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    cols: options.cols ?? 92,
+    rows: options.rows ?? 16,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "f", command: { id: "query.fetch" }, scope: "global" },
+        { key: "F", command: { id: "query.fetch" }, scope: "global" },
+        { key: "i", command: { id: "query.invalidate" }, scope: "global" },
+        { key: "I", command: { id: "query.invalidate" }, scope: "global" },
+        { key: "j", command: { id: "inventory.next" }, scope: "global" },
+        { key: "J", command: { id: "inventory.next" }, scope: "global" },
+        { key: "k", command: { id: "inventory.previous" }, scope: "global" },
+        { key: "K", command: { id: "inventory.previous" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "query.fetch") {
+          void fetchInventory();
+          return true;
+        }
+        if (command.id === "query.invalidate") {
+          invalidateInventory();
+          return true;
+        }
+        if (command.id === "inventory.next") {
+          moveSelection(1);
+          return true;
+        }
+        if (command.id === "inventory.previous") {
+          moveSelection(-1);
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  return {
+    session,
+    dispatchKey(key: string) {
+      return session.dispatchKey(key);
+    },
+    output() {
+      return session.output();
+    },
+    ansiOutput() {
+      return session.ansiOutput();
+    },
+    isRunning() {
+      return state.running;
+    },
+    destroy() {
+      state.running = false;
+      client.clear();
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleQueryDemo({ runtime: "headless", cols: 92, rows: 16 });
+    demo.dispatchKey("F");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    demo.dispatchKey("J");
+    demo.dispatchKey("I");
+    demo.dispatchKey("F");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleQueryDemo();
+  }
+}
+```
+
+See the Valyrian.js documentation for the full `valyrian.js/query` API.
+
+### `valyrian.js/tasks`
+
+Expose async work with run, cancel, reset, success, and error states. Demo app: **Background Maintenance Runner**.
+
+Complete demo: **Background Maintenance Runner** ([`examples/docs/module-tasks.tsx`](../examples/docs/module-tasks.tsx)). Run it with `bun examples/docs/module-tasks.tsx`, run cleanup with `R`, cancel the scan with `C`, trigger a controlled failure with `X`, reset with `Z`, and quit with `Ctrl+C`.
+
+Complete runnable example:
+
+```tsx
+import { Task } from "valyrian.js/tasks";
+import { Pane, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface ModuleDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+interface TaskDemoState {
+  status: string;
+  result: string;
+  error: string;
+  currentJob: string;
+  seenStates: string[];
+  running: boolean;
+}
+
+const PANEL_STYLE = { color: "#f8fafc", background: "#111827", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#dbeafe", background: "#1e293b" };
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function waitForControlledAsync(signal: AbortSignal) {
+  return new Promise<void>((resolve) => {
+    const timer = setTimeout(resolve, 20);
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true }
+    );
+  });
+}
+
+function syncTaskState(state: TaskDemoState, task: Task<string, string>) {
+  const snapshot = task.state;
+  state.status = snapshot.status;
+  state.result = snapshot.result ? `Result: ${snapshot.result}` : "Result: none";
+  state.error = snapshot.error instanceof Error ? `Error: ${snapshot.error.message}` : "Error: none";
+}
+
+function visibleTaskStates(states: string[]) {
+  const compact: string[] = [];
+  for (const status of states) {
+    if ((status === "cancelled" || status === "error") && compact[compact.length - 1] === "running") {
+      compact.pop();
+    }
+    if (compact[compact.length - 1] !== status) {
+      compact.push(status);
+    }
+  }
+  return compact.join(" -> ");
+}
+
+export function App({ state }: { state: TaskDemoState }) {
+  return (
+    <Screen title="Background Maintenance Runner">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Background Maintenance Runner</Text>
+      <Pane style={PANEL_STYLE}>
+        <Text>Maintenance Runner: runs local cleanup work through a Valyrian Task.</Text>
+        <Text>{`Task status: ${state.status}`}</Text>
+        <Text>{`Maintenance job: ${state.currentJob}`}</Text>
+        <Text>{state.result}</Text>
+        <Text>{state.error}</Text>
+        <Text>{`Seen states: ${visibleTaskStates(state.seenStates)}`}</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>R: run cleanup   C: cancel scan   X: controlled fail   Z: reset   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModuleTasksDemo(options: TerminalMountOptions = {}): ModuleDemo {
+  const state: TaskDemoState = {
+    status: "idle",
+    result: "Result: none",
+    error: "Error: none",
+    currentJob: "none",
+    seenStates: ["idle"],
+    running: true
+  };
+  const task = new Task<string, string>(async (label, { signal }) => {
+    if (label === "fail") {
+      throw new Error("controlled task failure");
+    }
+    if (label === "scan") {
+      await waitForControlledAsync(signal);
+      if (signal.aborted) return "Cancelled stale scan";
+    }
+    return `Completed ${label}`;
+  }, { strategy: "restartable" });
+  const rememberState = () => {
+    const status = task.state.status;
+    if (state.seenStates[state.seenStates.length - 1] !== status) {
+      state.seenStates.push(status);
+    }
+    syncTaskState(state, task);
+  };
+  const offTaskState = task.on("state", () => {
+    rememberState();
+    session?.update();
+  });
+  let session: TerminalSession;
+
+  function quit() {
+    state.running = false;
+    offTaskState();
+    task.reset();
+    session.destroy();
+  }
+
+  async function runTask(label: string, job: string) {
+    state.currentJob = job;
+    try {
+      rememberState();
+      await task.run(label);
+    } catch {
+      // The task state snapshot carries the controlled error message.
+    }
+    syncTaskState(state, task);
+    session.update();
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    cols: options.cols ?? 92,
+    rows: options.rows ?? 16,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "r", command: { id: "task.run" }, scope: "global" },
+        { key: "R", command: { id: "task.run" }, scope: "global" },
+        { key: "c", command: { id: "task.cancel" }, scope: "global" },
+        { key: "C", command: { id: "task.cancel" }, scope: "global" },
+        { key: "x", command: { id: "task.error" }, scope: "global" },
+        { key: "X", command: { id: "task.error" }, scope: "global" },
+        { key: "z", command: { id: "task.reset" }, scope: "global" },
+        { key: "Z", command: { id: "task.reset" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "task.run") {
+          void runTask("cleanup", "nightly cleanup");
+          return true;
+        }
+        if (command.id === "task.cancel") {
+          state.currentJob = "stale scan";
+          void task.run("scan");
+          rememberState();
+          task.cancel();
+          rememberState();
+          session.update();
+          return true;
+        }
+        if (command.id === "task.error") {
+          void runTask("fail", "permission audit");
+          return true;
+        }
+        if (command.id === "task.reset") {
+          state.currentJob = "none";
+          task.reset();
+          rememberState();
+          session.update();
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  return {
+    session,
+    dispatchKey(key: string) {
+      return session.dispatchKey(key);
+    },
+    output() {
+      return session.output();
+    },
+    ansiOutput() {
+      return session.ansiOutput();
+    },
+    isRunning() {
+      return state.running;
+    },
+    destroy() {
+      state.running = false;
+      offTaskState();
+      task.reset();
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleTasksDemo({ runtime: "headless", cols: 92, rows: 16 });
+    demo.dispatchKey("R");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    demo.dispatchKey("C");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    demo.dispatchKey("X");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    demo.dispatchKey("Z");
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleTasksDemo();
+  }
+}
+```
+
+See the Valyrian.js documentation for the full `valyrian.js/tasks` API.
+
+### `valyrian.js/forms`
+
+Build validation flows with `setField`, `validate()`, `submit()`, visible errors, and reset. Demo app: **Profile Editor**.
+
+Complete demo: **Profile Editor** ([`examples/docs/module-forms.tsx`](../examples/docs/module-forms.tsx)). Run it with `bun examples/docs/module-forms.tsx`, type profile fields, save with `Enter`, reset with `R`, and quit with `Ctrl+C`.
+
+Complete runnable example:
+
+```tsx
+import { FormStore } from "valyrian.js/forms";
+import { Input, Pane, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface ModuleDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+type ProfileForm = { name: string; email: string };
+
+interface SavedProfile {
+  name: string;
+  email: string;
+}
+
+interface FormDemoState {
+  form: FormStore<ProfileForm>;
+  valid: boolean;
+  savedProfile: SavedProfile | null;
+  submitMessage: string;
+  resetMessage: string;
+  running: boolean;
+}
+
+const PANEL_STYLE = { color: "#f8fafc", background: "#111827", padding: { left: 1, right: 1 } };
+const FIELD_STYLE = { color: "#ffffff", background: "#0f3b3e", padding: { left: 1, right: 1 } };
+const ERROR_STYLE = { color: "#fecaca" };
+const FOOTER_STYLE = { color: "#dbeafe", background: "#1e293b" };
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function createProfileForm(onSaved: (profile: SavedProfile) => void) {
+  return new FormStore<ProfileForm>({
+    state: { name: "", email: "" },
+    schema: {
+      type: "object",
+      properties: {
+        name: { type: "string", minLength: 1 },
+        email: { type: "string", format: "email" }
+      },
+      required: ["name", "email"]
+    },
+    clean: {
+      name: (value) => String(value).trim(),
+      email: (value) => String(value).trim().toLowerCase()
+    },
+    onSubmit(values) {
+      onSaved({ name: values.name, email: values.email });
+    }
+  });
+}
+
+function fieldError(form: FormStore<ProfileForm>, field: keyof ProfileForm) {
+  return String(form.validationErrors[field] || "not checked");
+}
+
+function savedSummary(profile: SavedProfile | null) {
+  return profile ? `${profile.name} / ${profile.email}` : "none";
+}
+
+export function App({ state, onSubmit }: { state: FormDemoState; onSubmit: () => void }) {
+  return (
+    <Screen title="Profile Editor">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Profile Editor</Text>
+      <Pane style={FIELD_STYLE}>
+        <Text>Name</Text>
+        <Input
+          id="profile-name"
+          value={state.form.state.name}
+          placeholder="Full name"
+          onchange={(event) => {
+            state.form.setField("name", event.value);
+            state.valid = false;
+          }}
+          onsubmit={onSubmit}
+        />
+        <Text>{`Name: ${state.form.state.name || "blank"}`}</Text>
+        <Text style={ERROR_STYLE}>{`Name error: ${fieldError(state.form, "name")}`}</Text>
+        <Text>Email</Text>
+        <Input
+          id="profile-email"
+          value={state.form.state.email}
+          placeholder="name@example.com"
+          onchange={(event) => {
+            state.form.setField("email", event.value);
+            state.valid = false;
+          }}
+          onsubmit={onSubmit}
+        />
+        <Text>{`Email: ${state.form.state.email || "blank"}`}</Text>
+        <Text style={ERROR_STYLE}>{`Email error: ${fieldError(state.form, "email")}`}</Text>
+      </Pane>
+      <Pane style={PANEL_STYLE}>
+        <Text>{`Form valid: ${state.valid}`}</Text>
+        <Text>{`Submit: ${state.submitMessage}`}</Text>
+        <Text>{`Reset: ${state.resetMessage}`}</Text>
+        <Text>{`Saved profile: ${savedSummary(state.savedProfile)}`}</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>Type profile fields | Tab: next field | Shift+Tab: previous field | Enter: save profile | R: reset form | Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModuleFormsDemo(options: TerminalMountOptions = {}): ModuleDemo {
+  const state: FormDemoState = {
+    form: null as unknown as FormStore<ProfileForm>,
+    valid: false,
+    savedProfile: null,
+    submitMessage: "not submitted",
+    resetMessage: "not reset",
+    running: true
+  };
+  state.form = createProfileForm((profile) => {
+    state.savedProfile = profile;
+    state.submitMessage = `saved ${profile.name} <${profile.email}>`;
+  });
+  let session: TerminalSession;
+
+  function resetForm() {
+    state.form.reset();
+    state.valid = false;
+    state.savedProfile = null;
+    state.submitMessage = "not submitted";
+    state.resetMessage = "form reset";
+  }
+
+  function submitForm() {
+    state.valid = state.form.validate();
+    if (!state.valid) {
+      state.submitMessage = "blocked by validation";
+      session.update();
+      return;
+    }
+
+    void state.form.submit().then((ok) => {
+      state.valid = ok;
+      if (!ok) state.submitMessage = "blocked by validation";
+      session.update();
+    });
+  }
+
+  function quit() {
+    state.running = false;
+    session.destroy();
+  }
+
+  session = mountTerminal(<App state={state} onSubmit={submitForm} />, {
+    ...options,
+    cols: options.cols ?? 92,
+    rows: options.rows ?? 20,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "R", command: { id: "forms.reset" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "forms.reset") {
+          resetForm();
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  session.focus("profile-name");
+
+  return {
+    session,
+    dispatchKey(key: string) {
+      return session.dispatchKey(key);
+    },
+    output() {
+      return session.output();
+    },
+    ansiOutput() {
+      return session.ansiOutput();
+    },
+    isRunning() {
+      return state.running;
+    },
+    destroy() {
+      state.running = false;
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleFormsDemo({ runtime: "headless", cols: 92, rows: 20 });
+    demo.dispatchKey("ENTER");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    for (const key of "AdaLovelace") demo.dispatchKey(key);
+    demo.dispatchKey("TAB");
+    for (const key of "ada@example.com") demo.dispatchKey(key);
+    demo.dispatchKey("ENTER");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleFormsDemo();
+  }
+}
+```
+
+See the Valyrian.js documentation for the full `valyrian.js/forms` API.
+
+### `valyrian.js/native-store`
+
+Persist local settings with `createNativeStore`, `set(key, value)`, and `get(key)` for values shared across renders. Demo app: **Persistent Workspace Settings**.
+
+Complete demo: **Persistent Workspace Settings** ([`examples/docs/module-native-store.tsx`](../examples/docs/module-native-store.tsx)). Run it with `bun examples/docs/module-native-store.tsx`, type the workspace, save with `Enter`, reset with `R`, and quit with `Ctrl+C`.
+
+Complete runnable example:
+
+```tsx
+import { createNativeStore, StorageType } from "valyrian.js/native-store";
+import { Input, Pane, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface ModuleDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+type NativeStoreDemoOptions = TerminalMountOptions & {
+  storeKey?: string;
+  resetOnStart?: boolean;
+};
+
+interface WorkspaceSettingsState {
+  draftWorkspace: string;
+  restoredWorkspace: string;
+  savedWorkspace: string;
+  status: string;
+}
+
+const DEFAULT_WORKSPACE = "Northwind CLI";
+const DEFAULT_STORE_KEY = "valyrian-terminal-docs.workspace-settings";
+const PANEL_STYLE = { color: "#f8fafc", background: "#111827", padding: { left: 1, right: 1 } };
+const FIELD_STYLE = { color: "#ffffff", background: "#0f3b3e", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#dbeafe", background: "#1e293b" };
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+
+function normalizeWorkspace(value: unknown) {
+  const workspace = String(value ?? "").trim();
+  return workspace.length > 0 ? workspace : DEFAULT_WORKSPACE;
+}
+
+export function App({ state, onSave }: { state: WorkspaceSettingsState; onSave: () => void }) {
+  return (
+    <Screen title="Persistent Workspace Settings">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Persistent Workspace Settings</Text>
+      <Pane style={FIELD_STYLE}>
+        <Text>Workspace name</Text>
+        <Input
+          id="workspace-name"
+          value={state.draftWorkspace}
+          placeholder="Workspace name"
+          onchange={(event) => {
+            state.draftWorkspace = event.value;
+            state.status = "editing workspace setting";
+          }}
+          onsubmit={onSave}
+        />
+        <Text>{`Draft workspace: ${state.draftWorkspace || "blank"}`}</Text>
+      </Pane>
+      <Pane style={PANEL_STYLE}>
+        <Text>{`Restored workspace: ${state.restoredWorkspace}`}</Text>
+        <Text>{`Saved workspace: ${state.savedWorkspace}`}</Text>
+        <Text>{`Settings status: ${state.status}`}</Text>
+        <Text>Local native-store keeps workspace settings outside the renderer.</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>Type workspace | Enter: save setting | R: reset setting | Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModuleNativeStoreDemo(options: NativeStoreDemoOptions = {}): ModuleDemo {
+  const settings = createNativeStore<{ workspace: string }>(options.storeKey ?? DEFAULT_STORE_KEY, {}, StorageType.Session, true);
+  if (options.resetOnStart) {
+    settings.clear();
+  }
+
+  function loadWorkspace() {
+    const restored = normalizeWorkspace(settings.get("workspace"));
+    if (settings.get("workspace") !== restored) settings.set("workspace", restored);
+    return restored;
+  }
+
+  const restoredWorkspace = loadWorkspace();
+  const state: WorkspaceSettingsState = {
+    draftWorkspace: restoredWorkspace,
+    restoredWorkspace,
+    savedWorkspace: restoredWorkspace,
+    status: "loaded saved setting"
+  };
+  let running = true;
+  let session: TerminalSession;
+
+  function saveWorkspace() {
+    const workspace = normalizeWorkspace(state.draftWorkspace);
+    settings.set("workspace", workspace);
+    state.draftWorkspace = workspace;
+    state.savedWorkspace = workspace;
+    state.restoredWorkspace = workspace;
+    state.status = "saved setting";
+  }
+
+  function reloadWorkspace() {
+    settings.load();
+    const workspace = loadWorkspace();
+    state.draftWorkspace = workspace;
+    state.savedWorkspace = workspace;
+    state.restoredWorkspace = workspace;
+    state.status = "loaded saved setting";
+  }
+
+  function resetWorkspace() {
+    settings.clear();
+    settings.set("workspace", DEFAULT_WORKSPACE);
+    state.draftWorkspace = "";
+    state.savedWorkspace = DEFAULT_WORKSPACE;
+    state.restoredWorkspace = DEFAULT_WORKSPACE;
+    state.status = "reset to default";
+  }
+
+  function quit() {
+    running = false;
+    settings.cleanup();
+    session.destroy();
+  }
+
+  session = mountTerminal(<App state={state} onSave={saveWorkspace} />, {
+    ...options,
+    cols: options.cols ?? 92,
+    rows: options.rows ?? 18,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "R", command: { id: "store.reset" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "store.reset") {
+          resetWorkspace();
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  session.focus("workspace-name");
+
+  return {
+    session,
+    dispatchKey(key: string) {
+      return session.dispatchKey(key);
+    },
+    output() {
+      return session.output();
+    },
+    ansiOutput() {
+      return session.ansiOutput();
+    },
+    isRunning() {
+      return running;
+    },
+    destroy() {
+      running = false;
+      settings.cleanup();
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleNativeStoreDemo({ runtime: "headless", cols: 92, rows: 18, resetOnStart: true });
+    demo.dispatchKey("R");
+    demo.session.focus("workspace-name");
+    for (const key of "Support CLI") demo.dispatchKey(key);
+    demo.dispatchKey("ENTER");
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleNativeStoreDemo();
+  }
+}
+```
+
+See the Valyrian.js documentation for the full `valyrian.js/native-store` API.
+
+### `valyrian.js/translate`
+
+Localize user-facing labels in terminal screens. Demo app: **Bilingual Support Console**.
+
+Complete demo: **Bilingual Support Console** ([`examples/docs/module-translate.tsx`](../examples/docs/module-translate.tsx)). Run it with `bun examples/docs/module-translate.tsx`, switch language with `L`, select tickets with `J/K`, filter status with `F`, and quit with `Ctrl+C`.
+
+Complete runnable example:
+
+```tsx
+import { getLang, setLang, setLog, setStoreStrategy, setTranslations, t } from "valyrian.js/translate";
+import { Pane, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface ModuleDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+type Ticket = { id: string; customer: string; status: "open" | "waiting" | "closed" };
+type SupportState = { selected: number; language: "en" | "es"; filter: "all" | "open" };
+
+const TICKETS: Ticket[] = [
+  { id: "T-104", customer: "Northwind", status: "open" },
+  { id: "T-118", customer: "Contoso", status: "waiting" },
+  { id: "T-130", customer: "Tailspin", status: "closed" }
+];
+const PANEL_STYLE = { color: "#f8fafc", background: "#111827", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#dbeafe", background: "#1e293b" };
+let storedLanguage = "en";
+
+function configureTranslations() {
+  setLog(false);
+  setStoreStrategy({
+    get: () => storedLanguage,
+    set: (language) => {
+      storedLanguage = language;
+    }
+  });
+  setTranslations(
+    {
+      title: "Bilingual Support Console",
+      purpose: "Support Console",
+      language: "Language",
+      filter: "Filter",
+      selected: "Selected ticket",
+      all: "all tickets",
+      openOnly: "open only",
+      status: { open: "open", waiting: "waiting", closed: "closed" },
+      help: "L language   J/K select ticket   F filter status   Ctrl+C: quit"
+    },
+    {
+      es: {
+        title: "Bilingual Support Console",
+        purpose: "Consola de soporte",
+        language: "Idioma",
+        filter: "Filtro",
+        selected: "Ticket elegido",
+        all: "todos los tickets",
+        openOnly: "solo abiertos",
+        status: { open: "abierto", waiting: "en espera", closed: "cerrado" },
+        help: "L idioma   J/K elegir ticket   F filtrar estado   Ctrl+C: quit"
+      }
+    }
+  );
+}
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function visibleTickets(filter: SupportState["filter"]) {
+  return filter === "open" ? TICKETS.filter((ticket) => ticket.status === "open") : TICKETS;
+}
+
+export function App({ state }: { state: SupportState }) {
+  setLang(state.language);
+  const tickets = visibleTickets(state.filter);
+  const selected = tickets[state.selected] || tickets[0];
+
+  return (
+    <Screen title="Bilingual Support Console">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>{t("title")}</Text>
+      <Pane style={PANEL_STYLE}>
+        <Text>{t("purpose")}</Text>
+        <Text>{`${t("language")}: ${state.language === "en" ? "English" : "Español"}`}</Text>
+        <Text>{`${t("filter")}: ${state.filter === "open" ? t("openOnly") : t("all")}`}</Text>
+        {tickets.map((ticket, index) => (
+          <Text>{`${index === state.selected ? ">" : " "} ${ticket.id} ${ticket.customer} — ${t(`status.${ticket.status}`)}`}</Text>
+        ))}
+        <Text>{`${t("selected")}: ${selected.id} ${selected.customer}`}</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>{t("help")}</Text>
+    </Screen>
+  );
+}
+
+export function createModuleTranslateDemo(options: TerminalMountOptions = {}): ModuleDemo {
+  const previousLanguage = getLang();
+  configureTranslations();
+  const state: SupportState = { selected: 0, language: "en", filter: "all" };
+  setLang(state.language);
+  let running = true;
+  let session: TerminalSession;
+
+  function quit() {
+    running = false;
+    setLang(previousLanguage);
+    session.destroy();
+  }
+
+  function clampSelection() {
+    const count = visibleTickets(state.filter).length;
+    state.selected = Math.min(state.selected, Math.max(0, count - 1));
+  }
+
+  function move(delta: number) {
+    const count = visibleTickets(state.filter).length;
+    state.selected = (state.selected + delta + count) % count;
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    cols: options.cols ?? 92,
+    rows: options.rows ?? 18,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "l", command: { id: "support.language" }, scope: "global" },
+        { key: "L", command: { id: "support.language" }, scope: "global" },
+        { key: "j", command: { id: "support.next" }, scope: "global" },
+        { key: "J", command: { id: "support.next" }, scope: "global" },
+        { key: "k", command: { id: "support.previous" }, scope: "global" },
+        { key: "K", command: { id: "support.previous" }, scope: "global" },
+        { key: "f", command: { id: "support.filter" }, scope: "global" },
+        { key: "F", command: { id: "support.filter" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "support.language") {
+          state.language = state.language === "en" ? "es" : "en";
+          setLang(state.language);
+          session.update();
+          return true;
+        }
+        if (command.id === "support.next") {
+          move(1);
+          return true;
+        }
+        if (command.id === "support.previous") {
+          move(-1);
+          return true;
+        }
+        if (command.id === "support.filter") {
+          state.filter = state.filter === "all" ? "open" : "all";
+          clampSelection();
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  return {
+    session,
+    dispatchKey(key: string) {
+      return session.dispatchKey(key);
+    },
+    output() {
+      return session.output();
+    },
+    ansiOutput() {
+      return session.ansiOutput();
+    },
+    isRunning() {
+      return running;
+    },
+    destroy() {
+      running = false;
+      setLang(previousLanguage);
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleTranslateDemo({ runtime: "headless", cols: 92, rows: 18 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleTranslateDemo();
+  }
+}
+```
+
+See the Valyrian.js documentation for the full `valyrian.js/translate` API.
+
+### `valyrian.js/money`
+
+Format currency totals with precise cents and locale-aware display. Demo app: **Invoice Calculator**.
+
+Complete demo: **Invoice Calculator** ([`examples/docs/module-money.tsx`](../examples/docs/module-money.tsx)). Run it with `bun examples/docs/module-money.tsx`, select lines with `J/K`, change quantity with `+/-`, toggle discount with `D`, switch locale with `L`, and quit with `Ctrl+C`.
+
+Complete runnable example:
+
+```tsx
+import { Money, formatMoney, parseMoneyInput } from "valyrian.js/money";
+import { Pane, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface ModuleDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+type InvoiceLine = { name: string; unit: Money; quantity: number };
+type InvoiceState = { selected: number; discount: boolean; localeIndex: number; lines: InvoiceLine[] };
+
+const LOCALES = [
+  { label: "US / USD", locale: "en-US", currency: "USD" },
+  { label: "MX / USD", locale: "es-MX", currency: "USD" }
+] as const;
+const INITIAL_LINES: InvoiceLine[] = [
+  { name: "Support seats", unit: parseMoneyInput("49.00", { locale: "en-US" }), quantity: 3 },
+  { name: "Priority add-on", unit: Money.fromDecimal(120), quantity: 1 },
+  { name: "Storage pack", unit: Money.fromCents(2500), quantity: 2 }
+];
+const TAX_RATE = 0.16;
+const DISCOUNT_RATE = 0.1;
+const PANEL_STYLE = { color: "#f8fafc", background: "#111827", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#dbeafe", background: "#1e293b" };
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function cloneLines() {
+  return INITIAL_LINES.map((line) => ({ ...line }));
+}
+
+function moneyView(value: Money, state: InvoiceState) {
+  const locale = LOCALES[state.localeIndex];
+  return formatMoney(value, { currency: locale.currency, locale: locale.locale, digits: 2 });
+}
+
+function invoiceTotals(state: InvoiceState) {
+  const subtotal = state.lines.reduce((total, line) => total.add(line.unit.multiply(line.quantity)), Money.fromCents(0));
+  const discount = state.discount ? subtotal.multiply(DISCOUNT_RATE) : Money.fromCents(0);
+  const taxable = subtotal.subtract(discount);
+  const tax = taxable.multiply(TAX_RATE);
+  const total = taxable.add(tax);
+  return { subtotal, discount, tax, total };
+}
+
+export function App({ state }: { state: InvoiceState }) {
+  const totals = invoiceTotals(state);
+  const locale = LOCALES[state.localeIndex];
+
+  return (
+    <Screen title="Invoice Calculator">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Invoice Calculator</Text>
+      <Pane style={PANEL_STYLE}>
+        <Text>Invoice Calculator</Text>
+        <Text>{`Locale: ${locale.label}`}</Text>
+        {state.lines.map((line, index) => (
+          <Text>{`${index === state.selected ? ">" : " "} ${line.name} x${line.quantity} — ${moneyView(line.unit.multiply(line.quantity), state)}`}</Text>
+        ))}
+        <Text>{`Subtotal: ${moneyView(totals.subtotal, state)}`}</Text>
+        <Text>{`Discount: ${state.discount ? moneyView(totals.discount, state) : "none"}`}</Text>
+        <Text>{`Tax: ${moneyView(totals.tax, state)}`}</Text>
+        <Text>{`Total: ${moneyView(totals.total, state)}`}</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>J/K line   +/- quantity   D discount   L locale   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModuleMoneyDemo(options: TerminalMountOptions = {}): ModuleDemo {
+  const state: InvoiceState = { selected: 0, discount: false, localeIndex: 0, lines: cloneLines() };
+  let running = true;
+  let session: TerminalSession;
+
+  function quit() {
+    running = false;
+    session.destroy();
+  }
+
+  function changeQuantity(delta: number) {
+    const line = state.lines[state.selected];
+    line.quantity = Math.max(0, line.quantity + delta);
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    cols: options.cols ?? 92,
+    rows: options.rows ?? 20,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "j", command: { id: "invoice.next" }, scope: "global" },
+        { key: "J", command: { id: "invoice.next" }, scope: "global" },
+        { key: "k", command: { id: "invoice.previous" }, scope: "global" },
+        { key: "K", command: { id: "invoice.previous" }, scope: "global" },
+        { key: "+", command: { id: "invoice.increase" }, scope: "global" },
+        { key: "-", command: { id: "invoice.decrease" }, scope: "global" },
+        { key: "d", command: { id: "invoice.discount" }, scope: "global" },
+        { key: "D", command: { id: "invoice.discount" }, scope: "global" },
+        { key: "l", command: { id: "invoice.locale" }, scope: "global" },
+        { key: "L", command: { id: "invoice.locale" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "invoice.next") {
+          state.selected = (state.selected + 1) % state.lines.length;
+          return true;
+        }
+        if (command.id === "invoice.previous") {
+          state.selected = (state.selected - 1 + state.lines.length) % state.lines.length;
+          return true;
+        }
+        if (command.id === "invoice.increase") {
+          changeQuantity(1);
+          return true;
+        }
+        if (command.id === "invoice.decrease") {
+          changeQuantity(-1);
+          return true;
+        }
+        if (command.id === "invoice.discount") {
+          state.discount = !state.discount;
+          return true;
+        }
+        if (command.id === "invoice.locale") {
+          state.localeIndex = (state.localeIndex + 1) % LOCALES.length;
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  return {
+    session,
+    dispatchKey(key: string) {
+      return session.dispatchKey(key);
+    },
+    output() {
+      return session.output();
+    },
+    ansiOutput() {
+      return session.ansiOutput();
+    },
+    isRunning() {
+      return running;
+    },
+    destroy() {
+      running = false;
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleMoneyDemo({ runtime: "headless", cols: 92, rows: 20 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleMoneyDemo();
+  }
+}
+```
+
+See the Valyrian.js documentation for the full `valyrian.js/money` API.
+
+### `valyrian.js/utils`
+
+Use shaping helpers for object paths and small view models before render. Demo app: **Account Data Inspector**.
+
+Complete demo: **Account Data Inspector** ([`examples/docs/module-utils.tsx`](../examples/docs/module-utils.tsx)). Run it with `bun examples/docs/module-utils.tsx`, select fields with `J/K`, filter the group with `F`, reset with `R`, and quit with `Ctrl+C`.
+
+Complete runnable example:
+
+```tsx
+import { get, pick, set } from "valyrian.js/utils";
+import { Pane, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface ModuleDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+type AccountPayload = {
+  account: { name: string; plan: string; region?: string; owner: { name: string; email: string } };
+  usage: { seats: number; projects: number; lastLogin: string };
+  billing: { status: string; renewal: string };
+};
+type InspectorState = { selected: number; filter: "all" | "account"; record: AccountPayload };
+type FieldRow = { group: string; label: string; value: string };
+type AccountSummaryKey = "name" | "plan" | "region";
+
+const PANEL_STYLE = { color: "#f8fafc", background: "#111827", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#dbeafe", background: "#1e293b" };
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function createRecord(): AccountPayload {
+  const record: AccountPayload = {
+    account: { name: "Northwind", plan: "Team", owner: { name: "Ada Lovelace", email: "ada@example.test" } },
+    usage: { seats: 12, projects: 4, lastLogin: "2026-05-29" },
+    billing: { status: "current", renewal: "2026-06-15" }
+  };
+  set(record, "account.region", "MX");
+  return record;
+}
+
+function buildRows(record: AccountPayload, filter: InspectorState["filter"]): FieldRow[] {
+  const safeAccount = pick<AccountPayload["account"], AccountSummaryKey>(record.account, ["name", "plan", "region"]);
+  const rows = [
+    { group: "account", label: "Account", value: String(get(safeAccount, "name", "unknown")) },
+    { group: "account", label: "Plan", value: String(get(safeAccount, "plan", "none")) },
+    { group: "account", label: "Region", value: String(get(safeAccount, "region", "unknown")) },
+    { group: "owner", label: "Owner", value: String(get(record, "account.owner.name", "unknown")) },
+    { group: "usage", label: "Seats", value: String(get(record, "usage.seats", 0)) },
+    { group: "usage", label: "Projects", value: String(get(record, "usage.projects", 0)) },
+    { group: "billing", label: "Billing", value: String(get(record, "billing.status", "unknown")) }
+  ];
+  return filter === "account" ? rows.filter((row) => row.group === "account") : rows;
+}
+
+export function App({ state }: { state: InspectorState }) {
+  const rows = buildRows(state.record, state.filter);
+  const selected = rows[state.selected] || rows[0];
+
+  return (
+    <Screen title="Account Data Inspector">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Account Data Inspector</Text>
+      <Pane style={PANEL_STYLE}>
+        <Text>Account Data Inspector</Text>
+        <Text>{`Filter: ${state.filter === "account" ? "account fields" : "all groups"}`}</Text>
+        {rows.map((row, index) => (
+          <Text>{`${index === state.selected ? ">" : " "} [${row.group}] ${row.label}: ${row.value}`}</Text>
+        ))}
+        <Text>{`Selected field: ${selected.label}`}</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>J/K select field   F filter group   R reset   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModuleUtilsDemo(options: TerminalMountOptions = {}): ModuleDemo {
+  const state: InspectorState = { selected: 0, filter: "all", record: createRecord() };
+  let running = true;
+  let session: TerminalSession;
+
+  function quit() {
+    running = false;
+    session.destroy();
+  }
+
+  function clampSelection() {
+    const count = buildRows(state.record, state.filter).length;
+    state.selected = Math.min(state.selected, Math.max(0, count - 1));
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    cols: options.cols ?? 92,
+    rows: options.rows ?? 20,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "j", command: { id: "inspector.next" }, scope: "global" },
+        { key: "J", command: { id: "inspector.next" }, scope: "global" },
+        { key: "k", command: { id: "inspector.previous" }, scope: "global" },
+        { key: "K", command: { id: "inspector.previous" }, scope: "global" },
+        { key: "f", command: { id: "inspector.filter" }, scope: "global" },
+        { key: "F", command: { id: "inspector.filter" }, scope: "global" },
+        { key: "r", command: { id: "inspector.reset" }, scope: "global" },
+        { key: "R", command: { id: "inspector.reset" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "inspector.next") {
+          const count = buildRows(state.record, state.filter).length;
+          state.selected = (state.selected + 1) % count;
+          return true;
+        }
+        if (command.id === "inspector.previous") {
+          const count = buildRows(state.record, state.filter).length;
+          state.selected = (state.selected - 1 + count) % count;
+          return true;
+        }
+        if (command.id === "inspector.filter") {
+          state.filter = state.filter === "all" ? "account" : "all";
+          clampSelection();
+          return true;
+        }
+        if (command.id === "inspector.reset") {
+          state.selected = 0;
+          state.filter = "all";
+          state.record = createRecord();
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  return {
+    session,
+    dispatchKey(key: string) {
+      return session.dispatchKey(key);
+    },
+    output() {
+      return session.output();
+    },
+    ansiOutput() {
+      return session.ansiOutput();
+    },
+    isRunning() {
+      return running;
+    },
+    destroy() {
+      running = false;
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleUtilsDemo({ runtime: "headless", cols: 92, rows: 20 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleUtilsDemo();
+  }
+}
+```
+
+See the Valyrian.js documentation for the full `valyrian.js/utils` API.
+
+## Composed workflows / integrations
+
+The workflows below combine modules after the single-module examples. Use them when a terminal app needs more than one app-layer concern on the same screen.
+
+### Operations Workbench
+
+Use `valyrian.js`, `valyrian.js/pulses`, and `valyrian.js/flux-store` when a terminal app needs more than local objects glued to key handlers.
+
+Keyboard events should flow into state transitions. A practical path is: key event -> command or handler -> pulse mutation or flux operation -> render update. Terminal-handled events render after the handler. Timers, promises, file watchers, or external callbacks that change Valyrian reactive state also refresh the terminal when components read that state. Use `session.update()` when the changed data is not reactive or when you need an explicit manual refresh.
+
+
+Complete demo: **Operations Workbench** ([`examples/docs/module-state-workbench.tsx`](../examples/docs/module-state-workbench.tsx)). Run it with `bun examples/docs/module-state-workbench.tsx`, select jobs with `J/K`, dispatch with `Enter`, mark work with `D` or `B`, reset with `R`, and quit with `Ctrl+C`.
+
+Complete runnable example:
+
+```tsx
+import { v } from "valyrian.js";
+import { createPulse, createPulseStore } from "valyrian.js/pulses";
+import { FluxStore } from "valyrian.js/flux-store";
+import { Pane, Screen, Split, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+type JobStatus = "queued" | "running" | "done" | "blocked";
+type OperationAction = "dispatch" | "done" | "block" | "reset";
+
+interface Job {
+  id: string;
+  label: string;
+  owner: string;
+  status: JobStatus;
+}
+
+interface OperationEvent {
+  action: OperationAction;
+  job: string;
+  note: string;
+}
+
+interface ModuleStateWorkbenchDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+const INITIAL_JOBS: Job[] = [
+  { id: "docs", label: "Docs refresh", owner: "Mina", status: "running" },
+  { id: "release", label: "Package release", owner: "Omar", status: "queued" },
+  { id: "support", label: "Support sweep", owner: "Iris", status: "blocked" }
+];
+
+function createWorkbenchStores() {
+  const jobsStore = createPulseStore(
+    {
+      selectedIndex: 0,
+      jobs: INITIAL_JOBS.map((job) => ({ ...job }))
+    },
+    {
+      selectNext(state) {
+        state.selectedIndex = (state.selectedIndex + 1) % state.jobs.length;
+      },
+      selectPrevious(state) {
+        state.selectedIndex = (state.selectedIndex - 1 + state.jobs.length) % state.jobs.length;
+      },
+      updateSelectedStatus(state, status: JobStatus) {
+        state.jobs[state.selectedIndex].status = status;
+      },
+      reset(state) {
+        state.selectedIndex = 0;
+        state.jobs = INITIAL_JOBS.map((job) => ({ ...job }));
+      }
+    }
+  );
+
+  const [pulseRevision, setPulseRevision] = createPulse(1);
+
+  const operations = new FluxStore({
+    state: {
+      done: 0,
+      blocked: 1,
+      dispatched: 0,
+      timeline: ["Bootstrapped queue", "Loaded terminal session"] as string[],
+      lastAction: "dispatch" as OperationAction
+    },
+    mutations: {
+      SET_METRICS(state, jobs: Job[]) {
+        state.done = jobs.filter((job) => job.status === "done").length;
+        state.blocked = jobs.filter((job) => job.status === "blocked").length;
+      },
+      RECORD_EVENT(state, event: OperationEvent) {
+        state.lastAction = event.action;
+        state.dispatched += event.action === "dispatch" ? 1 : 0;
+        state.timeline.push(`${event.action}: ${event.job} — ${event.note}`);
+        state.timeline = state.timeline.slice(-5);
+      },
+      RESET(state) {
+        state.done = 0;
+        state.blocked = 1;
+        state.dispatched = 0;
+        state.lastAction = "reset";
+        state.timeline = ["reset: queue — restored baseline"];
+      }
+    },
+    actions: {
+      async dispatchSelected(store, job: Job) {
+        jobsStore.updateSelectedStatus("running");
+        store.commit("SET_METRICS", jobsStore.state.jobs);
+        store.commit("RECORD_EVENT", { action: "dispatch", job: job.label, note: "operator started work" });
+      },
+      async markDone(store, job: Job) {
+        jobsStore.updateSelectedStatus("done");
+        store.commit("SET_METRICS", jobsStore.state.jobs);
+        store.commit("RECORD_EVENT", { action: "done", job: job.label, note: "closed cleanly" });
+      },
+      async blockSelected(store, job: Job) {
+        jobsStore.updateSelectedStatus("blocked");
+        store.commit("SET_METRICS", jobsStore.state.jobs);
+        store.commit("RECORD_EVENT", { action: "block", job: job.label, note: "needs review" });
+      }
+    }
+  });
+
+  return { jobsStore, operations, pulseRevision, setPulseRevision };
+}
+
+type WorkbenchStores = ReturnType<typeof createWorkbenchStores>;
+
+const SURFACE_STYLE = { color: "#f5f5f5", background: "#111827", padding: { left: 1, right: 1 } };
+const DETAIL_STYLE = { color: "#f8fafc", background: "#172554", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#d1d5db", background: "#1f2937" };
+const CURRENT_STYLE = { color: "#ffffff", background: "#14532d" };
+const MUTED_STYLE = { color: "#9ca3af" };
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function selectedJob(stores: WorkbenchStores) {
+  return stores.jobsStore.state.jobs[stores.jobsStore.state.selectedIndex];
+}
+
+function resetStores(stores: WorkbenchStores) {
+  stores.jobsStore.reset();
+  stores.operations.commit("RESET");
+  stores.setPulseRevision(1);
+}
+
+function bumpRevision(stores: WorkbenchStores) {
+  stores.setPulseRevision((value) => value + 1);
+}
+
+export function App({ stores }: { stores: WorkbenchStores }) {
+  const selected = selectedJob(stores);
+  const manualVNode = v(Text, { style: MUTED_STYLE }, `Tracked jobs: ${stores.jobsStore.state.jobs.length}`);
+
+  return (
+    <Screen title="Operations Workbench">
+      <Text style={{ color: "#ffffff", background: "#0f172a" }}>Valyrian.js modules in terminal apps: state workbench</Text>
+      <Split direction="row" gap={1} sizes={["2fr", "1fr"]}>
+        <Pane style={SURFACE_STYLE}>
+          <Text>Operations Workbench</Text>
+          <Text>{`Pulse revision: ${stores.pulseRevision()}  Done jobs: ${stores.operations.state.done}  Blocked jobs: ${stores.operations.state.blocked}`}</Text>
+          <Text>{`Dispatches: ${stores.operations.state.dispatched}  Last action: ${stores.operations.state.lastAction}`}</Text>
+          {stores.jobsStore.state.jobs.map((job, index) => (
+            <Text state={index === stores.jobsStore.state.selectedIndex ? "current" : undefined} style={index === stores.jobsStore.state.selectedIndex ? undefined : MUTED_STYLE} styles={{ current: CURRENT_STYLE }}>{`${index === stores.jobsStore.state.selectedIndex ? ">" : " "} ${job.label} — ${job.owner} — ${job.status}`}</Text>
+          ))}
+        </Pane>
+        <Pane style={DETAIL_STYLE}>
+          <Text>{`Selected: ${selected.label}`}</Text>
+          <Text>{`Owner: ${selected.owner}`}</Text>
+          <Text>{`Status: ${selected.status}`}</Text>
+          {manualVNode}
+          <Text>FluxStore dispatch coordinates operation actions.</Text>
+          <Text>{`Timeline: ${stores.operations.state.timeline.slice(-3).join(" | ")}`}</Text>
+        </Pane>
+      </Split>
+      <Text style={FOOTER_STYLE}>J/K: select   Enter: dispatch   D: done   B: block   R: reset   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModuleStateWorkbenchDemo(options: TerminalMountOptions = {}): ModuleStateWorkbenchDemo {
+  const stores = createWorkbenchStores();
+  resetStores(stores);
+  let running = true;
+  let session: TerminalSession;
+
+  function quit() {
+    running = false;
+    session.destroy();
+  }
+
+  function updateAfterOperation() {
+    bumpRevision(stores);
+    session.update();
+  }
+
+  function runSelected(action: "dispatchSelected" | "markDone" | "blockSelected") {
+    const job = selectedJob(stores);
+    void stores.operations.dispatch(action, job).then(updateAfterOperation);
+    updateAfterOperation();
+  }
+
+  session = mountTerminal(<App stores={stores} />, {
+    ...options,
+    cols: options.cols ?? 100,
+    rows: options.rows ?? 24,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "j", command: { id: "jobs.next" }, scope: "global" },
+        { key: "J", command: { id: "jobs.next" }, scope: "global" },
+        { key: "k", command: { id: "jobs.previous" }, scope: "global" },
+        { key: "K", command: { id: "jobs.previous" }, scope: "global" },
+        { key: "ENTER", command: { id: "jobs.dispatch" }, scope: "global" },
+        { key: "d", command: { id: "jobs.done" }, scope: "global" },
+        { key: "D", command: { id: "jobs.done" }, scope: "global" },
+        { key: "b", command: { id: "jobs.block" }, scope: "global" },
+        { key: "B", command: { id: "jobs.block" }, scope: "global" },
+        { key: "r", command: { id: "jobs.reset" }, scope: "global" },
+        { key: "R", command: { id: "jobs.reset" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "jobs.next") {
+          stores.jobsStore.selectNext();
+          session.update();
+          return true;
+        }
+        if (command.id === "jobs.previous") {
+          stores.jobsStore.selectPrevious();
+          session.update();
+          return true;
+        }
+        if (command.id === "jobs.dispatch") {
+          runSelected("dispatchSelected");
+          return true;
+        }
+        if (command.id === "jobs.done") {
+          runSelected("markDone");
+          return true;
+        }
+        if (command.id === "jobs.block") {
+          runSelected("blockSelected");
+          return true;
+        }
+        if (command.id === "jobs.reset") {
+          resetStores(stores);
+          session.update();
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  return {
+    session,
+    dispatchKey(key: string) {
+      return session.dispatchKey(key);
+    },
+    output() {
+      return session.output();
+    },
+    ansiOutput() {
+      return session.ansiOutput();
+    },
+    isRunning() {
+      return running;
+    },
+    destroy() {
+      running = false;
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleStateWorkbenchDemo({ runtime: "headless", cols: 100, rows: 24 });
+    demo.dispatchKey("J");
+    demo.dispatchKey("ENTER");
+    demo.dispatchKey("D");
+    demo.dispatchKey("K");
+    demo.dispatchKey("B");
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleStateWorkbenchDemo();
+  }
+}
+```
+
+### API Operations Dashboard
+
+Principal module: `valyrian.js/request`.
+
+CLIs and TUIs benefit from a clear API client layer. `valyrian.js/request` gives terminal apps one place to define helper methods, response parsing, scoped clients, plugin hooks, and endpoint access. Use a fake/local request in runnable examples, then use real validated endpoints in apps. Let the terminal tree render prepared results while network control flow stays in the app layer.
+
+Pair `valyrian.js/request` with `valyrian.js/query` when a screen has cached read state. Pair it with `valyrian.js/tasks` when the user starts work that may run longer than a single keypress. The app should expose states users can understand: idle, loading, success, error, cancel, retry. When components read Valyrian reactive state, the terminal frame updates when that state changes. Use `session.update()` for non-reactive state or for an explicit manual refresh.
+
+Complete demo: **API Operations Dashboard** ([`examples/docs/module-api-dashboard.tsx`](../examples/docs/module-api-dashboard.tsx)). Run it with `bun examples/docs/module-api-dashboard.tsx`, refresh with `R`, force a controlled error with `E`, invalidate cached data with `I`, start or cancel background work with `T` or `C`, and quit with `Ctrl+C`.
+
+Complete runnable example:
+
+```tsx
+import { QueryClient } from "valyrian.js/query";
+import { request } from "valyrian.js/request";
+import { Task } from "valyrian.js/tasks";
+import { Pane, Screen, Split, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface ServiceStatus {
+  service: string;
+  queue: number;
+  version: string;
+}
+
+interface ApiDashboardState {
+  errorMode: boolean;
+  service: string;
+  queryStatus: string;
+  apiMessage: string;
+  invalidated: boolean;
+  taskStatus: string;
+  taskResult: string;
+  taskError: string;
+  taskJob: string;
+  running: boolean;
+}
+
+interface ModuleApiDashboardDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+const PANEL_STYLE = { color: "#f8fafc", background: "#0f172a", padding: { left: 1, right: 1 } };
+const API_STYLE = { color: "#ffffff", background: "#164e63", padding: { left: 1, right: 1 } };
+const TASK_STYLE = { color: "#ffffff", background: "#312e81", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#dbeafe", background: "#1e293b" };
+const ERROR_STYLE = { color: "#ffffff", background: "#7f1d1d" };
+const SUCCESS_STYLE = { color: "#ffffff", background: "#14532d" };
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function createState(): ApiDashboardState {
+  return {
+    errorMode: false,
+    service: "idle",
+    queryStatus: "idle",
+    apiMessage: "No request yet",
+    invalidated: false,
+    taskStatus: "idle",
+    taskResult: "Result: none",
+    taskError: "Error: none",
+    taskJob: "none",
+    running: true
+  };
+}
+
+async function withFakeFetch<T>(state: ApiDashboardState, run: () => Promise<T>) {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = ((input: RequestInfo | URL) => {
+    const url = String(input);
+    if (state.errorMode || url.endsWith("/failure")) {
+      return Promise.resolve(new Response(JSON.stringify({ message: "controlled request failure" }), { status: 503 }));
+    }
+    return Promise.resolve(new Response(JSON.stringify({ service: "healthy", queue: 3, version: "local-1" }), { status: 200 }));
+  }) as typeof fetch;
+
+  try {
+    return await run();
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+}
+
+function waitForTask(signal: AbortSignal) {
+  return new Promise<void>((resolve) => {
+    const timer = setTimeout(resolve, 20);
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true }
+    );
+  });
+}
+
+function syncTaskState(state: ApiDashboardState, task: Task<string, string>) {
+  const snapshot = task.state;
+  state.taskStatus = snapshot.status;
+  state.taskResult = snapshot.result ? `Result: ${snapshot.result}` : "Result: none";
+  state.taskError = snapshot.error instanceof Error ? `Error: ${snapshot.error.message}` : "Error: none";
+}
+
+export function App({ state }: { state: ApiDashboardState }) {
+  return (
+    <Screen title="API Operations Dashboard">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Valyrian.js modules in terminal apps: API dashboard</Text>
+      <Split direction="row" gap={1} sizes={["1fr", "1fr"]}>
+        <Pane style={API_STYLE}>
+          <Text>API Operations Dashboard</Text>
+          <Text>{`Mode: ${state.errorMode ? "forced error" : "success"}`}</Text>
+          <Text state={state.queryStatus === "error" ? "error" : "success"} styles={{ error: ERROR_STYLE, success: SUCCESS_STYLE }}>{state.apiMessage}</Text>
+          <Text>{`Query: ${state.queryStatus}`}</Text>
+          <Text>{`Invalidated: ${state.invalidated ? "yes" : "no"}`}</Text>
+          <Text>{`Service: ${state.service}`}</Text>
+        </Pane>
+        <Pane style={TASK_STYLE}>
+          <Text>Maintenance task</Text>
+          <Text>{`Task: ${state.taskStatus}`}</Text>
+          <Text>{`Job: ${state.taskJob}`}</Text>
+          <Text>{state.taskResult}</Text>
+          <Text>{state.taskError}</Text>
+          <Text>Request and query use a local fake fetch, so this example never calls the network.</Text>
+        </Pane>
+      </Split>
+      <Pane style={PANEL_STYLE}>
+        <Text>R: refresh   E: force error   I: invalidate   T: start task   C: cancel   Ctrl+C: quit</Text>
+        <Text style={FOOTER_STYLE}>See the Valyrian.js documentation for request, query, and tasks.</Text>
+      </Pane>
+    </Screen>
+  );
+}
+
+export function createModuleApiDashboardDemo(options: TerminalMountOptions = {}): ModuleApiDashboardDemo {
+  const state = createState();
+  const client = new QueryClient({ staleTime: 0, cacheTime: 1000 });
+  const api = request.new("http://terminal.local", { allowedMethods: ["get"] });
+  const serviceQuery = client.query({
+    key: ["terminal", "service-status"],
+    fetcher: () => api.get("/health")
+  });
+  const maintenanceTask = new Task<string, string>(async (label, { signal }) => {
+    if (label === "scan") {
+      await waitForTask(signal);
+      if (signal.aborted) return "Cancelled stale scan";
+    }
+    if (label === "fail") throw new Error("controlled task failure");
+    return `Completed ${label}`;
+  }, { strategy: "restartable" });
+  let session: TerminalSession;
+  const offTaskState = maintenanceTask.on("state", () => {
+    syncTaskState(state, maintenanceTask);
+    session?.update();
+  });
+
+  function quit() {
+    state.running = false;
+    offTaskState();
+    client.clear();
+    maintenanceTask.reset();
+    session.destroy();
+  }
+
+  async function refresh() {
+    if (state.queryStatus === "loading") {
+      state.apiMessage = "Refresh already in progress";
+      session.update();
+      return;
+    }
+
+    state.queryStatus = "loading";
+    state.apiMessage = state.errorMode ? "Loading forced error" : "Loading service status";
+    session.update();
+    try {
+      const data = (await withFakeFetch(state, () => serviceQuery.fetch())) as ServiceStatus;
+      state.service = data.service;
+      state.queryStatus = serviceQuery.state.status;
+      state.apiMessage = `Service: ${data.service}  Queue: ${data.queue}  Version: ${data.version}`;
+      state.invalidated = false;
+    } catch {
+      state.service = "unavailable";
+      state.queryStatus = serviceQuery.state.status;
+      state.apiMessage = "API error: controlled request failure";
+    }
+    session.update();
+  }
+
+  function invalidate() {
+    serviceQuery.invalidate();
+    state.queryStatus = serviceQuery.state.status;
+    state.invalidated = true;
+    state.apiMessage = "Cache invalidated; refresh will fetch again";
+    session.update();
+  }
+
+  async function runMaintenance(label: string, job: string) {
+    state.taskJob = job;
+    syncTaskState(state, maintenanceTask);
+    session.update();
+    try {
+      await maintenanceTask.run(label);
+    } catch {
+      // Task state stores the controlled error for the UI.
+    }
+    syncTaskState(state, maintenanceTask);
+    session.update();
+  }
+
+  function cancelMaintenance() {
+    state.taskJob = "stale scan";
+    void maintenanceTask.run("scan");
+    syncTaskState(state, maintenanceTask);
+    maintenanceTask.cancel();
+    syncTaskState(state, maintenanceTask);
+    session.update();
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    cols: options.cols ?? 96,
+    rows: options.rows ?? 22,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "r", command: { id: "api.refresh" }, scope: "global" },
+        { key: "R", command: { id: "api.refresh" }, scope: "global" },
+        { key: "e", command: { id: "api.error" }, scope: "global" },
+        { key: "E", command: { id: "api.error" }, scope: "global" },
+        { key: "i", command: { id: "api.invalidate" }, scope: "global" },
+        { key: "I", command: { id: "api.invalidate" }, scope: "global" },
+        { key: "t", command: { id: "task.run" }, scope: "global" },
+        { key: "T", command: { id: "task.run" }, scope: "global" },
+        { key: "c", command: { id: "task.cancel" }, scope: "global" },
+        { key: "C", command: { id: "task.cancel" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "api.refresh") {
+          void refresh();
+          return true;
+        }
+        if (command.id === "api.error") {
+          state.errorMode = true;
+          state.apiMessage = "Next refresh will use controlled error";
+          session.update();
+          return true;
+        }
+        if (command.id === "api.invalidate") {
+          invalidate();
+          return true;
+        }
+        if (command.id === "task.run") {
+          void runMaintenance("maintenance", "maintenance");
+          return true;
+        }
+        if (command.id === "task.cancel") {
+          cancelMaintenance();
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  return {
+    session,
+    dispatchKey(key: string) {
+      return session.dispatchKey(key);
+    },
+    output() {
+      return session.output();
+    },
+    ansiOutput() {
+      return session.ansiOutput();
+    },
+    isRunning() {
+      return state.running;
+    },
+    destroy() {
+      state.running = false;
+      offTaskState();
+      client.clear();
+      maintenanceTask.reset();
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleApiDashboardDemo({ runtime: "headless", cols: 96, rows: 22 });
+    demo.dispatchKey("R");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    demo.dispatchKey("I");
+    demo.dispatchKey("E");
+    demo.dispatchKey("R");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    demo.dispatchKey("T");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    demo.dispatchKey("C");
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleApiDashboardDemo();
+  }
+}
+```
+
+### Billing/Settings Wizard
+
+Use `valyrian.js/forms` and `valyrian.js/native-store` when terminal input becomes app data instead of throwaway text.
+
+Terminal input should move through cleanup, validation, visible errors, save, and reset. Do not bury validation in output text after the save already ran. Users need the error at the point where the value can be corrected.
+
+
+Complete demo: **Billing/Settings Wizard** ([`examples/docs/module-form-workflow.tsx`](../examples/docs/module-form-workflow.tsx)). Run it with `bun examples/docs/module-form-workflow.tsx`, fill the name with `N`, switch language with `L`, save with `S` or `Enter`, reset with `R`, clear saved data with `X`, and quit with `Ctrl+C`.
+
+Complete runnable example:
+
+```tsx
+import { FormStore } from "valyrian.js/forms";
+import { Money, formatMoney, parseMoneyInput } from "valyrian.js/money";
+import { createNativeStore, StorageType } from "valyrian.js/native-store";
+import { setLang, setLog, setStoreStrategy, setTranslations, t } from "valyrian.js/translate";
+import { get, set } from "valyrian.js/utils";
+import { Input, Pane, Screen, Split, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+type Language = "en" | "es";
+
+type BillingForm = {
+  name: string;
+  seats: number;
+  budgetCents: number;
+};
+
+interface SavedBilling {
+  name: string;
+  seats: number;
+  budgetCents: number;
+  workspace: string;
+}
+
+interface FormWorkflowState {
+  language: Language;
+  savedWorkspace: string;
+  savedBilling: SavedBilling | null;
+  saveMessage: string;
+  resetMessage: string;
+  running: boolean;
+}
+
+interface ModuleFormWorkflowDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+type FormWorkflowOptions = TerminalMountOptions & {
+  storeKey?: string;
+};
+
+const DEFAULT_STORE_KEY = "valyrian-terminal-docs.billing-settings-wizard";
+const DEFAULT_WORKSPACE = "Northwind CLI";
+
+const SHELL_STYLE = { color: "#f8fafc", background: "#111827", padding: { left: 1, right: 1 } };
+const FORM_STYLE = { color: "#ffffff", background: "#0f3b3e", padding: { left: 1, right: 1 } };
+const SUMMARY_STYLE = { color: "#ffffff", background: "#3b1f4f", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#e5e7eb", background: "#1f2937" };
+const MUTED_STYLE = { color: "#cbd5e1" };
+const ERROR_STYLE = { color: "#fecaca" };
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+
+function configureTranslations() {
+  setLog(false);
+  let storedLanguage = "en";
+  setStoreStrategy({
+    get: () => storedLanguage,
+    set: (language) => {
+      storedLanguage = language;
+    }
+  });
+  setTranslations(
+    {
+      heading: "Billing/Settings Wizard",
+      language: "Language: English",
+      workspace: "Workspace",
+      customer: "Customer",
+      seats: "Seats",
+      budget: "Budget"
+    },
+    {
+      es: {
+        heading: "Asistente de cobro/configuración",
+        language: "Idioma: español",
+        workspace: "Espacio",
+        customer: "Cliente",
+        seats: "Asientos",
+        budget: "Presupuesto"
+      }
+    }
+  );
+}
+
+function parseSeats(value: unknown) {
+  const seats = Number(String(value).trim());
+  return Number.isFinite(seats) ? seats : 0;
+}
+
+function parseBudgetCents(value: unknown) {
+  try {
+    return parseMoneyInput(String(value), { decimalPlaces: 2 }).toCents();
+  } catch {
+    return -1;
+  }
+}
+
+function createBillingForm(onSaved: (billing: SavedBilling) => void) {
+  return new FormStore<BillingForm>({
+    state: { name: "Ada", seats: 12, budgetCents: 129950 },
+    schema: {
+      type: "object",
+      properties: {
+        name: { type: "string", minLength: 1 },
+        seats: { type: "number", minimum: 1 },
+        budgetCents: { type: "number", minimum: 100 }
+      },
+      required: ["name", "seats", "budgetCents"]
+    },
+    clean: {
+      name: (value) => String(value).trim(),
+      seats: parseSeats,
+      budgetCents: parseBudgetCents
+    },
+    format: {
+      seats: (value) => String(value),
+      budgetCents: (value) => (Number(value) / 100).toFixed(2)
+    },
+    onSubmit(values) {
+      onSaved({
+        name: values.name,
+        seats: values.seats,
+        budgetCents: values.budgetCents,
+        workspace: DEFAULT_WORKSPACE
+      });
+    }
+  });
+}
+
+function formatBudget(cents: number, language: Language) {
+  const money = Money.fromCents(Number.isFinite(cents) ? cents : 0);
+  return formatMoney(money, { currency: "USD", locale: language === "es" ? "es-MX" : "en-US" });
+}
+
+function fieldError(form: FormStore<BillingForm>, field: keyof BillingForm) {
+  return String(form.validationErrors[field] || "not checked");
+}
+
+function savedSummary(saved: SavedBilling | null, language: Language) {
+  if (!saved) return "none";
+  return `${saved.name} / ${saved.seats} seats / ${formatBudget(saved.budgetCents, language)}`;
+}
+
+export function App({ form, state, onSubmit }: { form: FormStore<BillingForm>; state: FormWorkflowState; onSubmit: () => void }) {
+  setLang(state.language);
+  const data = { billing: { name: form.state.name, seats: form.state.seats } };
+  set(data, "billing.workspace", DEFAULT_WORKSPACE);
+  set(data, "billing.total", formatBudget(form.state.budgetCents, state.language));
+  const workspace = String(get(data, "billing.workspace", DEFAULT_WORKSPACE));
+  const displayBudget = String(get(data, "billing.total", formatBudget(0, state.language)));
+
+  return (
+    <Screen title="Billing/Settings Wizard">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Valyrian.js modules in terminal apps: form workflow</Text>
+      <Split direction="row" gap={1} sizes={["1fr", "1fr"]}>
+        <Pane style={FORM_STYLE}>
+          <Text>{t("heading")}</Text>
+          <Text>{t("language")}</Text>
+          <Text>{`${t("workspace")}: ${workspace}`}</Text>
+          <Text>{t("customer")}</Text>
+          <Input id="billing-name" value={String(form.state.name)} placeholder="Customer name" onchange={(event) => form.setField("name", event.value)} onsubmit={onSubmit} />
+          <Text>{`Name: ${form.state.name || "missing"}`}</Text>
+          <Text style={ERROR_STYLE}>{`Name error: ${fieldError(form, "name")}`}</Text>
+          <Text>{t("seats")}</Text>
+          <Input id="billing-seats" value={String(form.formatValue("seats", form.state.seats))} placeholder="Seat count" onchange={(event) => form.setField("seats", event.value)} onsubmit={onSubmit} />
+          <Text>{`Seats: ${form.state.seats}`}</Text>
+          <Text style={ERROR_STYLE}>{`Seats error: ${fieldError(form, "seats")}`}</Text>
+          <Text>{t("budget")}</Text>
+          <Input id="billing-budget" value={String(form.formatValue("budgetCents", form.state.budgetCents))} placeholder="Monthly budget" onchange={(event) => form.setField("budgetCents", event.value)} onsubmit={onSubmit} />
+          <Text>{`Budget: ${displayBudget}`}</Text>
+          <Text style={ERROR_STYLE}>{`Budget error: ${fieldError(form, "budgetCents")}`}</Text>
+        </Pane>
+        <Pane style={SUMMARY_STYLE}>
+          <Text>Cleaned billing summary</Text>
+          <Text>{`Workspace: ${workspace}`}</Text>
+          <Text>{`Saved workspace: ${state.savedWorkspace || "none"}`}</Text>
+          <Text>{`Saved billing: ${savedSummary(state.savedBilling, state.language)}`}</Text>
+          <Text>{`Form dirty: ${form.isDirty}`}</Text>
+          <Text>{`Form success: ${form.success}`}</Text>
+          <Text>{`Save: ${state.saveMessage}`}</Text>
+          <Text>{`Reset: ${state.resetMessage}`}</Text>
+          <Text style={MUTED_STYLE}>Forms clean input, native-store persists workspace, translate changes labels, money formats totals, and utils shape summary data.</Text>
+        </Pane>
+      </Split>
+      <Pane style={SHELL_STYLE}>
+        <Text>N: fill name   Tab: next field   Shift+Tab: previous field   L: language   S/Enter: save   R: reset form   X: clear saved   Ctrl+C: quit</Text>
+        <Text style={FOOTER_STYLE}>See the Valyrian.js documentation for forms, native-store, translate, money, and utils.</Text>
+      </Pane>
+    </Screen>
+  );
+}
+
+export function createModuleFormWorkflowDemo(options: FormWorkflowOptions = {}): ModuleFormWorkflowDemo {
+  configureTranslations();
+  const settings = createNativeStore<{ workspace: string }>(options.storeKey ?? DEFAULT_STORE_KEY, {}, StorageType.Session, true);
+  const state: FormWorkflowState = {
+    language: "en",
+    savedWorkspace: String(settings.get("workspace") || ""),
+    savedBilling: null,
+    saveMessage: "not saved",
+    resetMessage: "not reset",
+    running: true
+  };
+  const form = createBillingForm((billing) => {
+    state.savedBilling = billing;
+    state.savedWorkspace = billing.workspace;
+    settings.set("workspace", billing.workspace);
+    state.saveMessage = `saved ${billing.name} for ${billing.seats} seats`;
+  });
+  let session: TerminalSession;
+
+  function quit() {
+    state.running = false;
+    settings.cleanup();
+    session.destroy();
+  }
+
+  function resetForm() {
+    form.reset();
+    state.savedBilling = null;
+    state.savedWorkspace = "";
+    state.saveMessage = "not saved";
+    state.resetMessage = "form reset";
+    settings.clear();
+    session.update();
+  }
+
+  async function submitForm() {
+    const ok = await form.submit();
+    if (!ok) {
+      state.saveMessage = "blocked by validation";
+    }
+    session.update();
+  }
+
+  session = mountTerminal(<App form={form} state={state} onSubmit={submitForm} />, {
+    ...options,
+    cols: options.cols ?? 100,
+    rows: options.rows ?? 24,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "n", command: { id: "form.name" }, scope: "global" },
+        { key: "N", command: { id: "form.name" }, scope: "global" },
+        { key: "l", command: { id: "form.language" }, scope: "global" },
+        { key: "L", command: { id: "form.language" }, scope: "global" },
+        { key: "s", command: { id: "form.save" }, scope: "global" },
+        { key: "S", command: { id: "form.save" }, scope: "global" },
+        { key: "r", command: { id: "form.reset" }, scope: "global" },
+        { key: "R", command: { id: "form.reset" }, scope: "global" },
+        { key: "x", command: { id: "form.clear" }, scope: "global" },
+        { key: "X", command: { id: "form.clear" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "form.name") {
+          form.setField("name", "Ada Lovelace");
+          session.update();
+          return true;
+        }
+        if (command.id === "form.language") {
+          state.language = state.language === "en" ? "es" : "en";
+          setLang(state.language);
+          session.update();
+          return true;
+        }
+        if (command.id === "form.save") {
+          void submitForm();
+          return true;
+        }
+        if (command.id === "form.reset") {
+          resetForm();
+          return true;
+        }
+        if (command.id === "form.clear") {
+          state.savedWorkspace = "";
+          state.savedBilling = null;
+          state.saveMessage = "not saved";
+          settings.clear();
+          session.update();
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  session.focus("billing-name");
+
+  return {
+    session,
+    dispatchKey(key: string) {
+      return session.dispatchKey(key);
+    },
+    output() {
+      return session.output();
+    },
+    ansiOutput() {
+      return session.ansiOutput();
+    },
+    isRunning() {
+      return state.running;
+    },
+    destroy() {
+      state.running = false;
+      settings.cleanup();
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleFormWorkflowDemo({ runtime: "headless", cols: 100, rows: 24 });
+    demo.dispatchKey("S");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    demo.dispatchKey("N");
+    demo.dispatchKey("L");
+    demo.dispatchKey("S");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleFormWorkflowDemo();
+  }
+}
+```
+
+## Where to learn the full APIs
+
+This guide explains how Valyrian.js modules fit terminal-specific app patterns. For complete signatures, options, edge cases, and deeper examples, refer to the Valyrian.js docs for each module.