@venturewild/workspace 0.3.7 → 0.3.8

package/server/src/canvas/core.mjs

@@ -1,421 +1,446 @@
-// Canvas core — the store + validator for AGENT-MADE custom blocks.
-//
-// The block canvas (UX §3.3) lets the agent build the user a widget on request
-// ("make me a block that shows today's signups"). The differentiator: the canvas
-// stops being a fixed menu of widgets and becomes "anything the agent can build".
-//
-// SECURITY POSTURE — declarative, not code. The agent does NOT ship a React
-// component or any code to eval. It computes the data itself (Read/Bash in its own
-// turn) and emits a *spec* drawn from a small, fixed vocabulary of presentation
-// primitives (metric · list · table · markdown). The browser renders that spec with
-// trusted primitives (React-escaped text; markdown via react-markdown with NO raw
-// HTML). So an agent-made block adds NO new execution surface and cannot escalate a
-// read-only share-link viewer's privileges. "Live" = the agent re-pushes via
-// update_block (principle #4: no idle polling), not a server-run refresh command.
-// A shell-bound live refresh is a deliberate, owner-gated follow-up (see NOTES).
-//
-// State lives ENTIRELY under ~/.wild-workspace/canvas/ (absolute, OUTSIDE the
-// user's repo — CLAUDE.md rule #1). One module, imported by BOTH the main server
-// (to serve /api/canvas/blocks) and the spawned MCP server (to make/update blocks),
-// so there is a single file-backed source of truth and no port handshake:
-//   - blocks.json   the array of custom block specs. MCP writes, main reads.
-
-import fs from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
-import crypto from 'node:crypto';
-
-// The presentation primitives the agent may choose from. Anything else is rejected
-// at the boundary — the renderer only knows these.
-export const KINDS = ['metric', 'list', 'table', 'markdown'];
-
-// The named theme tokens an agent (or a Bazaar theme) may override — the EXTENSION
-// surface for "make my terminal look how I want". Each is ONLY ever a hex color
-// (validated below), so a theme is DATA, never CSS: it cannot inject url()/
-// expression()/selector-escapes. Keep in lockstep with TOKEN_VARS in web/src/theme.js.
-export const TOKEN_KEYS = [
-  'bg', 'bgElev', 'surface', 'border', 'text', 'textMuted', 'canvas1', 'canvas2', 'canvas3',
-];
-
-const HEX = /^#[0-9a-f]{6}$/i;
-export function isHex(v) {
-  return typeof v === 'string' && HEX.test(v.trim());
-}
-function hexOr(v, fallback = null) {
-  return isHex(v) ? v.trim().toLowerCase() : fallback;
-}
-
-const DEFAULT_ICON = { metric: '📈', list: '📋', table: '🗂️', markdown: '📝' };
-const TRENDS = ['up', 'down', 'flat'];
-
-// Caps — bound every field so a runaway tool call can't bloat the store or the UI.
-const CAP = {
-  blocks: 60, //          keep the most-recent N specs
-  title: 80,
-  icon: 8,
-  note: 240,
-  value: 48,
-  label: 48,
-  delta: 24,
-  spark: 60, //           sparkline points
-  listItems: 50,
-  itemLabel: 80,
-  itemValue: 40,
-  columns: 12,
-  colName: 40,
-  rows: 50,
-  cell: 80,
-  markdown: 6000,
-};
-
-// ~/.wild-workspace/canvas — mirrors logpaths.globalDir() but kept dependency-free
-// here so the MCP child can import this module standalone (same trick as bazaar).
-export function defaultCanvasDir(env = process.env) {
-  const base = env.WILD_WORKSPACE_GLOBAL_DIR || path.join(os.homedir(), '.wild-workspace');
-  return path.join(base, 'canvas');
-}
-
-function rid() {
-  return crypto.randomUUID().slice(0, 12);
-}
-
-function readJsonSafe(file, fallback) {
-  try {
-    return JSON.parse(fs.readFileSync(file, 'utf8'));
-  } catch {
-    return fallback;
-  }
-}
-
-function writeJsonAtomic(file, value) {
-  const tmp = `${file}.${process.pid}.tmp`;
-  fs.writeFileSync(tmp, JSON.stringify(value, null, 2));
-  fs.renameSync(tmp, file); // Node rename replaces the destination on all platforms
-}
-
-// --- spec normalization (the security boundary) ---------------------------
-
-function str(v, max) {
-  if (v === null || v === undefined) return '';
-  const s = String(typeof v === 'object' ? JSON.stringify(v) : v);
-  return s.slice(0, max);
-}
-
-function nonEmptyStr(v, max, fallback = '') {
-  const s = str(v, max).trim();
-  return s || fallback;
-}
-
-function numArray(v, max) {
-  if (!Array.isArray(v)) return [];
-  return v
-    .map((n) => Number(n))
-    .filter((n) => Number.isFinite(n))
-    .slice(0, max);
-}
-
-function normalizeData(kind, raw = {}) {
-  switch (kind) {
-    case 'metric': {
-      const data = { value: nonEmptyStr(raw.value, CAP.value, '—') };
-      const label = nonEmptyStr(raw.label, CAP.label);
-      if (label) data.label = label;
-      const delta = nonEmptyStr(raw.delta, CAP.delta);
-      if (delta) data.delta = delta;
-      if (TRENDS.includes(raw.trend)) data.trend = raw.trend;
-      const spark = numArray(raw.spark, CAP.spark);
-      if (spark.length) data.spark = spark;
-      return data;
-    }
-    case 'list': {
-      const src = Array.isArray(raw.items) ? raw.items : [];
-      const items = src.slice(0, CAP.listItems).map((it) => {
-        // Accept {label,value} objects OR bare strings (the agent's convenience).
-        if (it && typeof it === 'object') {
-          const item = { label: nonEmptyStr(it.label ?? it.name ?? it.key, CAP.itemLabel, '—') };
-          const value = nonEmptyStr(it.value ?? it.amount ?? it.count, CAP.itemValue);
-          if (value) item.value = value;
-          return item;
-        }
-        return { label: nonEmptyStr(it, CAP.itemLabel, '—') };
-      });
-      return { items };
-    }
-    case 'table': {
-      const columns = (Array.isArray(raw.columns) ? raw.columns : [])
-        .slice(0, CAP.columns)
-        .map((c) => nonEmptyStr(c, CAP.colName, ''));
-      const width = columns.length || CAP.columns;
-      const rows = (Array.isArray(raw.rows) ? raw.rows : [])
-        .slice(0, CAP.rows)
-        .map((r) => (Array.isArray(r) ? r : [r]).slice(0, width).map((cell) => str(cell, CAP.cell)));
-      return { columns, rows };
-    }
-    case 'markdown':
-    default:
-      return { text: nonEmptyStr(raw.markdown ?? raw.text ?? raw.body, CAP.markdown) };
-  }
-}
-
-/**
- * Validate + normalize a raw spec (from the agent's flat tool input) into the
- * stored shape. Throws on an unsupported `kind` so the MCP tool returns an error.
- * Everything else degrades gracefully (capped strings, dropped junk) — the agent
- * gets a usable block even if it over- or mis-specifies.
- */
-export function normalizeSpec(raw = {}) {
-  const kind = String(raw.kind || '').toLowerCase();
-  if (!KINDS.includes(kind)) {
-    throw new Error(`unsupported kind "${raw.kind}". Use one of: ${KINDS.join(', ')}`);
-  }
-  const spec = {
-    title: nonEmptyStr(raw.title, CAP.title, 'Untitled'),
-    icon: nonEmptyStr(raw.icon, CAP.icon, DEFAULT_ICON[kind]),
-    kind,
-    data: normalizeData(kind, raw),
-  };
-  const note = nonEmptyStr(raw.note, CAP.note);
-  if (note) spec.note = note;
-  return spec;
-}
-
-// --- theme normalization (the same security boundary, for the look) --------
-
-/**
- * Validate + normalize a raw theme (from the agent's flat set_theme input) into the
- * stored shape: { mode, accent, hot?, name?, tokens: {…hex} }. Hex-only, allowlisted
- * tokens — anything else is dropped. Never throws; a junk theme degrades to the
- * mode default (the picker/stylesheet still produces a usable look).
- */
-export function normalizeTheme(raw = {}) {
-  const theme = {
-    mode: raw.mode === 'dark' ? 'dark' : 'light',
-    accent: hexOr(raw.accent, '#0891b2'),
-  };
-  const hot = hexOr(raw.hot);
-  if (hot) theme.hot = hot;
-  const name = nonEmptyStr(raw.name, 60);
-  if (name) theme.name = name;
-  const tokens = {};
-  for (const key of TOKEN_KEYS) {
-    const hex = hexOr(raw[key] ?? raw.tokens?.[key]);
-    if (hex) tokens[key] = hex;
-  }
-  theme.tokens = tokens;
-  return theme;
-}
-
-// --- store ----------------------------------------------------------------
-
-export function createCanvas({ baseDir } = {}) {
-  const dir = baseDir || defaultCanvasDir();
-  const blocksFile = path.join(dir, 'blocks.json');
-  const themeFile = path.join(dir, 'theme.json');
-  // Server-side persistence for canvas state (layout, templates, user-theme).
-  // Fixes the localStorage-per-origin divergence bug (req-1 gave the user two
-  // origins → two divergent canvas states for the same workspace).
-  const layoutFile = path.join(dir, 'layout.json');
-  const templatesFile = path.join(dir, 'templates.json');
-  const userThemeFile = path.join(dir, 'user-theme.json');
-
-  function ensureDir() {
-    try {
-      fs.mkdirSync(dir, { recursive: true });
-    } catch {
-      /* read-only fs — degrades to no persistence */
-    }
-  }
-
-  function listBlocks() {
-    const v = readJsonSafe(blocksFile, []);
-    return Array.isArray(v) ? v : [];
-  }
-
-  function getBlock(id) {
-    return listBlocks().find((b) => b.id === id) || null;
-  }
-
-  function save(blocks) {
-    ensureDir();
-    // Bound the store: keep the most-recent N (a user can always remove more).
-    const trimmed = blocks.slice(-CAP.blocks);
-    try {
-      writeJsonAtomic(blocksFile, trimmed);
-    } catch {
-      /* persistence best-effort */
-    }
-    return trimmed;
-  }
-
-  function addBlock(raw) {
-    const spec = normalizeSpec(raw); // throws on bad kind
-    const block = { id: `cb-${rid()}`, ...spec, createdBy: 'agent', ts: Date.now() };
-    save([...listBlocks(), block]);
-    return block;
-  }
-
-  // Update an existing block's content by id. Only the fields the agent supplies
-  // change; the rest (incl. kind unless re-specified) are preserved. Returns the
-  // updated block, or null if the id is unknown.
-  function updateBlock(id, raw = {}) {
-    const blocks = listBlocks();
-    const idx = blocks.findIndex((b) => b.id === id);
-    if (idx < 0) return null;
-    const prev = blocks[idx];
-    const merged = normalizeSpec({
-      kind: raw.kind || prev.kind,
-      title: raw.title ?? prev.title,
-      icon: raw.icon ?? prev.icon,
-      note: raw.note ?? prev.note,
-      // Data fields: if the agent re-specifies the data for this kind, use the new
-      // ones; otherwise re-feed the previous data so nothing is lost.
-      ...flattenData(prev),
-      ...raw,
-    });
-    const next = { ...prev, ...merged, updatedAt: Date.now() };
-    blocks[idx] = next;
-    save(blocks);
-    return next;
-  }
-
-  function removeBlock(id) {
-    const blocks = listBlocks();
-    const next = blocks.filter((b) => b.id !== id);
-    if (next.length === blocks.length) return false;
-    save(next);
-    return true;
-  }
-
-  // --- theme (the agent-set look) — one file, last-write-wins ---------------
-
-  function getTheme() {
-    const v = readJsonSafe(themeFile, null);
-    return v && typeof v === 'object' ? v : null;
-  }
-
-  function setTheme(raw) {
-    const theme = { ...normalizeTheme(raw), ts: Date.now() };
-    ensureDir();
-    try {
-      writeJsonAtomic(themeFile, theme);
-    } catch {
-      /* persistence best-effort */
-    }
-    return theme;
-  }
-
-  // --- canvas layout (which blocks exist and where) — one file per workspace ----
-
-  function getLayout() {
-    const v = readJsonSafe(layoutFile, null);
-    return v && typeof v === 'object' ? v : null;
-  }
-
-  function saveLayout(layout) {
-    // Validate: blocks is an array, layouts has an lg array.
-    const blocks = Array.isArray(layout?.blocks) ? layout.blocks : [];
-    const lg = Array.isArray(layout?.layouts?.lg) ? layout.layouts.lg : [];
-    const data = { blocks, layouts: { lg }, ts: Date.now() };
-    ensureDir();
-    try { writeJsonAtomic(layoutFile, data); } catch { /* best-effort */ }
-    return data;
-  }
-
-  // --- user templates (saved layouts) — global per install ----
-
-  function getTemplates() {
-    const v = readJsonSafe(templatesFile, null);
-    return Array.isArray(v) ? v : [];
-  }
-
-  function saveTemplates(templates) {
-    const data = Array.isArray(templates) ? templates : [];
-    ensureDir();
-    try { writeJsonAtomic(templatesFile, data); } catch { /* best-effort */ }
-    return data;
-  }
-
-  // --- user theme (mode + accent from the picker) — separate from the agent theme ---
-  // The agent theme (theme.json) holds tokens/wallpaper set by set_theme; the user
-  // theme holds the user's own mode+accent choice from the ThemePicker. They merge
-  // at render time (mergeAgentTheme in theme.js).
-
-  function getUserTheme() {
-    const v = readJsonSafe(userThemeFile, null);
-    return v && typeof v === 'object' ? v : null;
-  }
-
-  function saveUserTheme(raw) {
-    // Only persist allowlisted fields — mode, accent, hot, accentManual, tokens.
-    const accent = hexOr(raw?.accent);
-    const theme = {
-      mode: raw?.mode === 'dark' ? 'dark' : 'light',
-      accent: accent || '#0891b2',
-      hot: hexOr(raw?.hot) || (accent ? darkenHex(accent) : '#0e7490'),
-      accentManual: !!raw?.accentManual,
-      tokens: {},
-    };
-    if (raw?.tokens && typeof raw.tokens === 'object') {
-      for (const key of TOKEN_KEYS) {
-        const hex = hexOr(raw.tokens[key]);
-        if (hex) theme.tokens[key] = hex;
-      }
-    }
-    ensureDir();
-    try { writeJsonAtomic(userThemeFile, theme); } catch { /* best-effort */ }
-    return theme;
-  }
-
-  // Darken helper (standalone — can't import from theme.js which is client-only)
-  function darkenHex(hex, f = 0.16) {
-    const h = hex.replace('#', '');
-    const k = 1 - f;
-    const c = (i) => Math.max(0, Math.min(255, Math.round(parseInt(h.slice(i, i + 2), 16) * k)));
-    return `#${[0, 2, 4].map((i) => c(i).toString(16).padStart(2, '0')).join('')}`;
-  }
-
-  // --- batch get/save (used by /api/canvas/state) ---
-
-  function getState() {
-    return {
-      layout: getLayout(),
-      templates: getTemplates(),
-      userTheme: getUserTheme(),
-    };
-  }
-
-  function saveState(updates) {
-    const result = {};
-    if (updates.layout) result.layout = saveLayout(updates.layout);
-    if (updates.templates) result.templates = saveTemplates(updates.templates);
-    if (updates.userTheme) result.userTheme = saveUserTheme(updates.userTheme);
-    return result;
-  }
-
-  return {
-    dir, blocksFile, themeFile, layoutFile, templatesFile, userThemeFile,
-    listBlocks, getBlock, addBlock, updateBlock, removeBlock,
-    getTheme, setTheme,
-    getLayout, saveLayout, getTemplates, saveTemplates,
-    getUserTheme, saveUserTheme,
-    getState, saveState,
-  };
-}
-
-// Re-expand a stored spec's `data` back into the flat fields normalizeSpec reads,
-// so updateBlock can merge partial changes over the previous content.
-function flattenData(block) {
-  const d = block?.data || {};
-  switch (block?.kind) {
-    case 'metric':
-      return { value: d.value, label: d.label, delta: d.delta, trend: d.trend, spark: d.spark };
-    case 'list':
-      return { items: d.items };
-    case 'table':
-      return { columns: d.columns, rows: d.rows };
-    case 'markdown':
-      return { markdown: d.text };
-    default:
-      return {};
-  }
-}
+// Canvas core — the store + validator for AGENT-MADE custom blocks.
+//
+// The block canvas (UX §3.3) lets the agent build the user a widget on request
+// ("make me a block that shows today's signups"). The differentiator: the canvas
+// stops being a fixed menu of widgets and becomes "anything the agent can build".
+//
+// SECURITY POSTURE — declarative, not code. The agent does NOT ship a React
+// component or any code to eval. It computes the data itself (Read/Bash in its own
+// turn) and emits a *spec* drawn from a small, fixed vocabulary of presentation
+// primitives (metric · list · table · markdown). The browser renders that spec with
+// trusted primitives (React-escaped text; markdown via react-markdown with NO raw
+// HTML). So an agent-made block adds NO new execution surface and cannot escalate a
+// read-only share-link viewer's privileges. "Live" = the agent re-pushes via
+// update_block (principle #4: no idle polling), not a server-run refresh command.
+// A shell-bound live refresh is a deliberate, owner-gated follow-up (see NOTES).
+//
+// State lives ENTIRELY under ~/.wild-workspace/canvas/ (absolute, OUTSIDE the
+// user's repo — CLAUDE.md rule #1). One module, imported by BOTH the main server
+// (to serve /api/canvas/blocks) and the spawned MCP server (to make/update blocks),
+// so there is a single file-backed source of truth and no port handshake:
+//   - blocks.json   the array of custom block specs. MCP writes, main reads.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+
+// The presentation primitives the agent may choose from. Anything else is rejected
+// at the boundary — the renderer only knows these.
+export const KINDS = ['metric', 'list', 'table', 'markdown'];
+
+// The named theme tokens an agent (or a Bazaar theme) may override — the EXTENSION
+// surface for "make my terminal look how I want". Each is ONLY ever a hex color
+// (validated below), so a theme is DATA, never CSS: it cannot inject url()/
+// expression()/selector-escapes. Keep in lockstep with TOKEN_VARS in web/src/theme.js.
+export const TOKEN_KEYS = [
+  'bg', 'bgElev', 'surface', 'border', 'text', 'textMuted', 'canvas1', 'canvas2', 'canvas3',
+];
+
+const HEX = /^#[0-9a-f]{6}$/i;
+export function isHex(v) {
+  return typeof v === 'string' && HEX.test(v.trim());
+}
+function hexOr(v, fallback = null) {
+  return isHex(v) ? v.trim().toLowerCase() : fallback;
+}
+
+const DEFAULT_ICON = { metric: '📈', list: '📋', table: '🗂️', markdown: '📝' };
+const TRENDS = ['up', 'down', 'flat'];
+
+// Caps — bound every field so a runaway tool call can't bloat the store or the UI.
+const CAP = {
+  blocks: 60, //          keep the most-recent N specs
+  title: 80,
+  icon: 8,
+  note: 240,
+  value: 48,
+  label: 48,
+  delta: 24,
+  spark: 60, //           sparkline points
+  listItems: 50,
+  itemLabel: 80,
+  itemValue: 40,
+  columns: 12,
+  colName: 40,
+  rows: 50,
+  cell: 80,
+  markdown: 6000,
+};
+
+// ~/.wild-workspace/canvas — mirrors logpaths.globalDir() but kept dependency-free
+// here so the MCP child can import this module standalone (same trick as bazaar).
+export function defaultCanvasDir(env = process.env) {
+  const base = env.WILD_WORKSPACE_GLOBAL_DIR || path.join(os.homedir(), '.wild-workspace');
+  return path.join(base, 'canvas');
+}
+
+function rid() {
+  return crypto.randomUUID().slice(0, 12);
+}
+
+function readJsonSafe(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJsonAtomic(file, value) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(value, null, 2));
+  fs.renameSync(tmp, file); // Node rename replaces the destination on all platforms
+}
+
+// --- spec normalization (the security boundary) ---------------------------
+
+function str(v, max) {
+  if (v === null || v === undefined) return '';
+  const s = String(typeof v === 'object' ? JSON.stringify(v) : v);
+  return s.slice(0, max);
+}
+
+function nonEmptyStr(v, max, fallback = '') {
+  const s = str(v, max).trim();
+  return s || fallback;
+}
+
+function numArray(v, max) {
+  if (!Array.isArray(v)) return [];
+  return v
+    .map((n) => Number(n))
+    .filter((n) => Number.isFinite(n))
+    .slice(0, max);
+}
+
+function normalizeData(kind, raw = {}) {
+  switch (kind) {
+    case 'metric': {
+      const data = { value: nonEmptyStr(raw.value, CAP.value, '—') };
+      const label = nonEmptyStr(raw.label, CAP.label);
+      if (label) data.label = label;
+      const delta = nonEmptyStr(raw.delta, CAP.delta);
+      if (delta) data.delta = delta;
+      if (TRENDS.includes(raw.trend)) data.trend = raw.trend;
+      const spark = numArray(raw.spark, CAP.spark);
+      if (spark.length) data.spark = spark;
+      return data;
+    }
+    case 'list': {
+      const src = Array.isArray(raw.items) ? raw.items : [];
+      const items = src.slice(0, CAP.listItems).map((it) => {
+        // Accept {label,value} objects OR bare strings (the agent's convenience).
+        if (it && typeof it === 'object') {
+          const item = { label: nonEmptyStr(it.label ?? it.name ?? it.key, CAP.itemLabel, '—') };
+          const value = nonEmptyStr(it.value ?? it.amount ?? it.count, CAP.itemValue);
+          if (value) item.value = value;
+          return item;
+        }
+        return { label: nonEmptyStr(it, CAP.itemLabel, '—') };
+      });
+      return { items };
+    }
+    case 'table': {
+      const columns = (Array.isArray(raw.columns) ? raw.columns : [])
+        .slice(0, CAP.columns)
+        .map((c) => nonEmptyStr(c, CAP.colName, ''));
+      const width = columns.length || CAP.columns;
+      const rows = (Array.isArray(raw.rows) ? raw.rows : [])
+        .slice(0, CAP.rows)
+        .map((r) => (Array.isArray(r) ? r : [r]).slice(0, width).map((cell) => str(cell, CAP.cell)));
+      return { columns, rows };
+    }
+    case 'markdown':
+    default:
+      return { text: nonEmptyStr(raw.markdown ?? raw.text ?? raw.body, CAP.markdown) };
+  }
+}
+
+/**
+ * Validate + normalize a raw spec (from the agent's flat tool input) into the
+ * stored shape. Throws on an unsupported `kind` so the MCP tool returns an error.
+ * Everything else degrades gracefully (capped strings, dropped junk) — the agent
+ * gets a usable block even if it over- or mis-specifies.
+ */
+export function normalizeSpec(raw = {}) {
+  const kind = String(raw.kind || '').toLowerCase();
+  if (!KINDS.includes(kind)) {
+    throw new Error(`unsupported kind "${raw.kind}". Use one of: ${KINDS.join(', ')}`);
+  }
+  const spec = {
+    title: nonEmptyStr(raw.title, CAP.title, 'Untitled'),
+    icon: nonEmptyStr(raw.icon, CAP.icon, DEFAULT_ICON[kind]),
+    kind,
+    data: normalizeData(kind, raw),
+  };
+  const note = nonEmptyStr(raw.note, CAP.note);
+  if (note) spec.note = note;
+  return spec;
+}
+
+// --- theme normalization (the same security boundary, for the look) --------
+
+/**
+ * Validate + normalize a raw theme (from the agent's flat set_theme input) into the
+ * stored shape: { mode, accent, hot?, name?, tokens: {…hex} }. Hex-only, allowlisted
+ * tokens — anything else is dropped. Never throws; a junk theme degrades to the
+ * mode default (the picker/stylesheet still produces a usable look).
+ */
+export function normalizeTheme(raw = {}) {
+  const theme = {
+    mode: raw.mode === 'dark' ? 'dark' : 'light',
+    accent: hexOr(raw.accent, '#0891b2'),
+  };
+  const hot = hexOr(raw.hot);
+  if (hot) theme.hot = hot;
+  const name = nonEmptyStr(raw.name, 60);
+  if (name) theme.name = name;
+  const tokens = {};
+  for (const key of TOKEN_KEYS) {
+    const hex = hexOr(raw[key] ?? raw.tokens?.[key]);
+    if (hex) tokens[key] = hex;
+  }
+  theme.tokens = tokens;
+  return theme;
+}
+
+// --- store ----------------------------------------------------------------
+
+// A personKey scopes the user's canvas STATE files (layout/templates/user-theme)
+// to one identity. It becomes a path segment, so harden it against traversal —
+// accountId is a uuid and the role sentinels are safe, but defend in depth.
+function sanitizePersonKey(key) {
+  const s = String(key || '')
+    .replace(/[^a-zA-Z0-9._-]/g, '_')
+    .slice(0, 80);
+  return s && s !== '.' && s !== '..' ? s : 'local';
+}
+
+export function createCanvas({ baseDir, personKey } = {}) {
+  const dir = baseDir || defaultCanvasDir();
+  // Agent-made content is workspace-SHARED (the agent builds blocks / sets the
+  // theme for the workspace, not for one person), so it stays at the canvas root.
+  const blocksFile = path.join(dir, 'blocks.json');
+  const themeFile = path.join(dir, 'theme.json');
+  // The user's canvas STATE (layout, saved templates, user-theme) is PER-IDENTITY
+  // when a personKey is given: it lives under <dir>/people/<personKey>/ so two
+  // people sharing one host don't collide, and (via the rails) one person's layout
+  // follows them across hosts. Without a personKey it stays flat at <dir>/ — the
+  // legacy / no-account-install path, which also preserves the existing on-disk
+  // layout for migration. (Originally added to fix the localStorage-per-origin
+  // divergence bug — req-1 gave the user two origins → two divergent states.)
+  const stateDir = personKey ? path.join(dir, 'people', sanitizePersonKey(personKey)) : dir;
+  const layoutFile = path.join(stateDir, 'layout.json');
+  const templatesFile = path.join(stateDir, 'templates.json');
+  const userThemeFile = path.join(stateDir, 'user-theme.json');
+
+  function ensureDir() {
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+    } catch {
+      /* read-only fs — degrades to no persistence */
+    }
+  }
+  // The per-identity state dir (same as `dir` when no personKey is set).
+  function ensureStateDir() {
+    try {
+      fs.mkdirSync(stateDir, { recursive: true });
+    } catch {
+      /* read-only fs — degrades to no persistence */
+    }
+  }
+
+  function listBlocks() {
+    const v = readJsonSafe(blocksFile, []);
+    return Array.isArray(v) ? v : [];
+  }
+
+  function getBlock(id) {
+    return listBlocks().find((b) => b.id === id) || null;
+  }
+
+  function save(blocks) {
+    ensureDir();
+    // Bound the store: keep the most-recent N (a user can always remove more).
+    const trimmed = blocks.slice(-CAP.blocks);
+    try {
+      writeJsonAtomic(blocksFile, trimmed);
+    } catch {
+      /* persistence best-effort */
+    }
+    return trimmed;
+  }
+
+  function addBlock(raw) {
+    const spec = normalizeSpec(raw); // throws on bad kind
+    const block = { id: `cb-${rid()}`, ...spec, createdBy: 'agent', ts: Date.now() };
+    save([...listBlocks(), block]);
+    return block;
+  }
+
+  // Update an existing block's content by id. Only the fields the agent supplies
+  // change; the rest (incl. kind unless re-specified) are preserved. Returns the
+  // updated block, or null if the id is unknown.
+  function updateBlock(id, raw = {}) {
+    const blocks = listBlocks();
+    const idx = blocks.findIndex((b) => b.id === id);
+    if (idx < 0) return null;
+    const prev = blocks[idx];
+    const merged = normalizeSpec({
+      kind: raw.kind || prev.kind,
+      title: raw.title ?? prev.title,
+      icon: raw.icon ?? prev.icon,
+      note: raw.note ?? prev.note,
+      // Data fields: if the agent re-specifies the data for this kind, use the new
+      // ones; otherwise re-feed the previous data so nothing is lost.
+      ...flattenData(prev),
+      ...raw,
+    });
+    const next = { ...prev, ...merged, updatedAt: Date.now() };
+    blocks[idx] = next;
+    save(blocks);
+    return next;
+  }
+
+  function removeBlock(id) {
+    const blocks = listBlocks();
+    const next = blocks.filter((b) => b.id !== id);
+    if (next.length === blocks.length) return false;
+    save(next);
+    return true;
+  }
+
+  // --- theme (the agent-set look) — one file, last-write-wins ---------------
+
+  function getTheme() {
+    const v = readJsonSafe(themeFile, null);
+    return v && typeof v === 'object' ? v : null;
+  }
+
+  function setTheme(raw) {
+    const theme = { ...normalizeTheme(raw), ts: Date.now() };
+    ensureDir();
+    try {
+      writeJsonAtomic(themeFile, theme);
+    } catch {
+      /* persistence best-effort */
+    }
+    return theme;
+  }
+
+  // --- canvas layout (which blocks exist and where) — one file per workspace ----
+
+  function getLayout() {
+    const v = readJsonSafe(layoutFile, null);
+    return v && typeof v === 'object' ? v : null;
+  }
+
+  function saveLayout(layout) {
+    // Validate: blocks is an array, layouts has an lg array.
+    const blocks = Array.isArray(layout?.blocks) ? layout.blocks : [];
+    const lg = Array.isArray(layout?.layouts?.lg) ? layout.layouts.lg : [];
+    const data = { blocks, layouts: { lg }, ts: Date.now() };
+    ensureStateDir();
+    try { writeJsonAtomic(layoutFile, data); } catch { /* best-effort */ }
+    return data;
+  }
+
+  // --- user templates (saved layouts) — global per install ----
+
+  function getTemplates() {
+    const v = readJsonSafe(templatesFile, null);
+    return Array.isArray(v) ? v : [];
+  }
+
+  function saveTemplates(templates) {
+    const data = Array.isArray(templates) ? templates : [];
+    ensureStateDir();
+    try { writeJsonAtomic(templatesFile, data); } catch { /* best-effort */ }
+    return data;
+  }
+
+  // --- user theme (mode + accent from the picker) — separate from the agent theme ---
+  // The agent theme (theme.json) holds tokens/wallpaper set by set_theme; the user
+  // theme holds the user's own mode+accent choice from the ThemePicker. They merge
+  // at render time (mergeAgentTheme in theme.js).
+
+  function getUserTheme() {
+    const v = readJsonSafe(userThemeFile, null);
+    return v && typeof v === 'object' ? v : null;
+  }
+
+  function saveUserTheme(raw) {
+    // Only persist allowlisted fields — mode, accent, hot, accentManual, tokens.
+    const accent = hexOr(raw?.accent);
+    const theme = {
+      mode: raw?.mode === 'dark' ? 'dark' : 'light',
+      accent: accent || '#0891b2',
+      hot: hexOr(raw?.hot) || (accent ? darkenHex(accent) : '#0e7490'),
+      accentManual: !!raw?.accentManual,
+      tokens: {},
+    };
+    if (raw?.tokens && typeof raw.tokens === 'object') {
+      for (const key of TOKEN_KEYS) {
+        const hex = hexOr(raw.tokens[key]);
+        if (hex) theme.tokens[key] = hex;
+      }
+    }
+    ensureStateDir();
+    try { writeJsonAtomic(userThemeFile, theme); } catch { /* best-effort */ }
+    return theme;
+  }
+
+  // Darken helper (standalone — can't import from theme.js which is client-only)
+  function darkenHex(hex, f = 0.16) {
+    const h = hex.replace('#', '');
+    const k = 1 - f;
+    const c = (i) => Math.max(0, Math.min(255, Math.round(parseInt(h.slice(i, i + 2), 16) * k)));
+    return `#${[0, 2, 4].map((i) => c(i).toString(16).padStart(2, '0')).join('')}`;
+  }
+
+  // --- batch get/save (used by /api/canvas/state) ---
+
+  function getState() {
+    return {
+      layout: getLayout(),
+      templates: getTemplates(),
+      userTheme: getUserTheme(),
+    };
+  }
+
+  function saveState(updates) {
+    const result = {};
+    if (updates.layout) result.layout = saveLayout(updates.layout);
+    if (updates.templates) result.templates = saveTemplates(updates.templates);
+    if (updates.userTheme) result.userTheme = saveUserTheme(updates.userTheme);
+    return result;
+  }
+
+  return {
+    dir, stateDir, blocksFile, themeFile, layoutFile, templatesFile, userThemeFile,
+    listBlocks, getBlock, addBlock, updateBlock, removeBlock,
+    getTheme, setTheme,
+    getLayout, saveLayout, getTemplates, saveTemplates,
+    getUserTheme, saveUserTheme,
+    getState, saveState,
+  };
+}
+
+// Re-expand a stored spec's `data` back into the flat fields normalizeSpec reads,
+// so updateBlock can merge partial changes over the previous content.
+function flattenData(block) {
+  const d = block?.data || {};
+  switch (block?.kind) {
+    case 'metric':
+      return { value: d.value, label: d.label, delta: d.delta, trend: d.trend, spark: d.spark };
+    case 'list':
+      return { items: d.items };
+    case 'table':
+      return { columns: d.columns, rows: d.rows };
+    case 'markdown':
+      return { markdown: d.text };
+    default:
+      return {};
+  }
+}