@vgai/editor 0.2.0

package/src/components/DataPanel.tsx

@@ -0,0 +1,1268 @@
+/**
+ * DATA dock tab (W2, docs/DATA-TOOLS-DESIGN.md §2.4) — lists every
+ * `src/data/*.data.json` of the open project and edits it in place.
+ *
+ * Architecture (spec §2.1): widgets are generated from the EMITTED
+ * `*.schema.json` (JSON Schema, the interchange artifact) via
+ * `jsonSchemaToFieldDescriptors` — the editor never executes the project's
+ * `.schema.ts`. The two blessed shapes render differently:
+ * - **singleton** → a form, one widget row per field (same look as the
+ *   component inspector — same `FieldDescriptor` IR, same widget primitives).
+ * - **table** (`z.record`) → a grid: one row per key in the data file, one
+ *   column per row-schema field, every cell a widget.
+ *
+ * Writes (D1, §2.5): every widget commit POSTs the whole updated file to
+ * `/__editor/data-file` immediately — no local buffering, no save button;
+ * undo is git. The `"$schema"` key is held out of editing everywhere and
+ * re-serialized first so git diffs stay minimal.
+ *
+ * Table rows can be added/removed (W6b) — see `TableEditor` below, which also
+ * carries CSV export/import (W6c, `data-csv.ts`) — a spreadsheet-friendly
+ * bulk-edit path for the same table. The empty state (`EmptyState`, W6d)
+ * teaches the create-a-data-asset recipe with a "Copy starter files" button;
+ * no file-creating scaffold button this wave (deferred — needs a
+ * purpose-scoped write verb, a security-surface decision). Still pending:
+ * adding a whole new FIELD to a schema (a `.schema.ts` code change, not an
+ * editor concern).
+ *
+ * Cross-asset refs (§2.2): a field declared with `dataRef(target)`
+ * (`@engine/data/data-ref`) renders as a `stem#key` PICKER instead of free
+ * text — `RefOptionsContext` reduces this panel's already-loaded `files`
+ * state into `stem -> key[]` once per change and threads it to `Widget`'s
+ * `'ref'` case (deep in `FieldList`/`TableEditor`) without prop-drilling.
+ */
+
+import {
+  createContext,
+  Fragment,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { connectDataFileEvents } from '../asset-events';
+import { csvToTable, tableToCsv } from './data-csv';
+import {
+  type DataAssetShape,
+  type DataFieldDescriptor,
+  defaultValueForDescriptor,
+  describeDataSchema,
+} from './inspectors/json-schema-fields';
+import { ColorInput } from './primitives/ColorInput';
+import { NumberInput } from './primitives/NumberInput';
+import { Tooltip } from './primitives/Tooltip';
+
+/** One file as served by GET /__editor/data-files (raw text, client parses). */
+interface ServerDataFile {
+  path: string;
+  content: string;
+  schema: string | null;
+}
+
+/** One file after client-side parsing + schema classification. */
+interface LoadedDataFile {
+  /** Project-relative path, e.g. `src/data/tuning.data.json`. */
+  path: string;
+  /** Parsed data object (`"$schema"` entry included), or null on parse error. */
+  data: Record<string, unknown> | null;
+  /**
+   * The file's own top-level key order, read from the RAW TEXT (D1
+   * diff-contract, #6): a JS object's own `Object.keys` order is not the
+   * file's textual order — integer-LIKE keys ("1", "2", "10") are always
+   * enumerated numerically-ascending by the engine, regardless of where they
+   * sat in the source JSON, so a table keyed by numeric strings would get a
+   * whole-file reorder on the very first edit if we ever serialized from
+   * `Object.keys(data)`. Captured once at load, then carried forward
+   * (new/removed keys folded in) by `nextKeyOrder` on every commit — see
+   * `writeFile`. `undefined` only when `data` is null (unparseable file).
+   */
+  keyOrder?: string[];
+  /** Widget plan derived from the emitted schema; null = no/unusable schema. */
+  shape: DataAssetShape | null;
+  hasSchema: boolean;
+  error?: string;
+}
+
+/**
+ * Every loaded file's own top-level keys, by asset stem — the `'ref'` widget
+ * kind's picker options. `DataPanel` already fetches and parses every data
+ * file's raw text (`GET /__editor/data-files`); this just reduces that same
+ * state into `stem -> key[]` once per `files` change and threads it to
+ * `Widget` (deep inside `FieldList`/`TableEditor`) via context instead of a
+ * prop through every intermediate component — the SAME shape a `dataRef`
+ * field's `refTarget` addresses (`json-schema-fields.ts`).
+ */
+const RefOptionsContext = createContext<ReadonlyMap<string, string[]>>(new Map());
+
+const inputStyle: React.CSSProperties = {
+  width: '100%',
+  background: '#1e1e1e',
+  color: '#c5c8ce',
+  border: '1px solid #333',
+  borderRadius: 2,
+  padding: '2px 4px',
+  fontSize: 12,
+  boxSizing: 'border-box',
+};
+
+const labelStyle: React.CSSProperties = {
+  fontSize: 11,
+  color: '#8c8c8c',
+  width: 140,
+  flexShrink: 0,
+};
+
+/** Scan a (valid-JSON) string literal starting at the opening quote; returns the index just past the closing quote. */
+function skipJsonString(text: string, i: number): number {
+  let j = i + 1;
+  while (j < text.length) {
+    const ch = text[j];
+    if (ch === '\\') {
+      j += 2;
+      continue;
+    }
+    if (ch === '"') return j + 1;
+    j++;
+  }
+  return j;
+}
+
+/** Scan one JSON value (string/object/array/number/bool/null) starting at `i`; returns the index just past it. Assumes well-formed JSON (only ever called on text `JSON.parse` already accepted). */
+function skipJsonValue(text: string, i: number): number {
+  const ch = text[i];
+  if (ch === '"') return skipJsonString(text, i);
+  if (ch === '{' || ch === '[') {
+    const close = ch === '{' ? '}' : ']';
+    let depth = 1;
+    let j = i + 1;
+    while (j < text.length && depth > 0) {
+      const c = text[j];
+      if (c === '"') {
+        j = skipJsonString(text, j);
+        continue;
+      }
+      if (c === '{' || c === '[') depth++;
+      else if (c === close || c === '}' || c === ']') depth--;
+      j++;
+    }
+    return j;
+  }
+  // number / true / false / null — run until a structural character.
+  let j = i;
+  while (j < text.length && !/[,}\]\s]/.test(text[j]!)) j++;
+  return j;
+}
+
+/**
+ * Read a top-level JSON object's key order straight off the SOURCE TEXT
+ * (D1 diff-contract, #6) — `JSON.parse` builds a JS object whose own
+ * enumeration order already reindexed any integer-like keys, so recovering
+ * "the order the file had on disk" has to happen before that reindexing, on
+ * the raw characters. Only ever called with text that `JSON.parse` already
+ * accepted, so this can assume well-formed JSON throughout.
+ */
+function extractTopLevelKeyOrder(text: string): string[] {
+  const keys: string[] = [];
+  let i = 0;
+  const n = text.length;
+  const skipWs = () => {
+    while (i < n && /\s/.test(text[i]!)) i++;
+  };
+  skipWs();
+  if (text[i] !== '{') return keys;
+  i++;
+  skipWs();
+  while (i < n && text[i] !== '}') {
+    if (text[i] !== '"') break;
+    const keyEnd = skipJsonString(text, i);
+    const key = JSON.parse(text.slice(i, keyEnd)) as string;
+    if (!keys.includes(key)) keys.push(key);
+    i = keyEnd;
+    skipWs();
+    if (text[i] !== ':') break;
+    i++;
+    skipWs();
+    i = skipJsonValue(text, i);
+    skipWs();
+    if (text[i] === ',') {
+      i++;
+      skipWs();
+      continue;
+    }
+    break;
+  }
+  return keys;
+}
+
+function parseServerFile(f: ServerDataFile): LoadedDataFile {
+  let data: Record<string, unknown> | null = null;
+  let error: string | undefined;
+  try {
+    const parsed = JSON.parse(f.content) as unknown;
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      data = parsed as Record<string, unknown>;
+    } else {
+      error = 'Data file is not a JSON object.';
+    }
+  } catch (e) {
+    error = `Data file is not valid JSON: ${e}`;
+  }
+
+  let shape: DataAssetShape | null = null;
+  if (f.schema !== null) {
+    try {
+      shape = describeDataSchema(JSON.parse(f.schema));
+    } catch {
+      /* malformed emitted schema — fall through to the no-schema message */
+    }
+  }
+
+  const out: LoadedDataFile = { path: f.path, data, shape, hasSchema: f.schema !== null };
+  if (data) {
+    try {
+      out.keyOrder = extractTopLevelKeyOrder(f.content);
+    } catch {
+      out.keyOrder = Object.keys(data); // defensive fallback — never block loading over this
+    }
+  }
+  if (error !== undefined) out.error = error;
+  return out;
+}
+
+/**
+ * Fold a commit's resulting keys into a stable order: `prevOrder` (whatever
+ * this file's keys were last serialized in — from disk on first load, from
+ * the previous commit after that) survives for every key still present, and
+ * any BRAND NEW key (add-row, a freshly-set nested field) is appended at the
+ * end in `Object.keys` order. This is what makes #6's fix stick across a
+ * SESSION of edits, not just the first one: each commit's output order
+ * becomes the next commit's `prevOrder`.
+ */
+function nextKeyOrder(prevOrder: string[] | undefined, obj: Record<string, unknown>): string[] {
+  const existing = prevOrder ?? Object.keys(obj);
+  const kept = [...new Set(existing)].filter((k) => k in obj);
+  const added = Object.keys(obj).filter((k) => !existing.includes(k));
+  return [...kept, ...added];
+}
+
+/**
+ * Serialize per D1's diff-minimal contract: `"$schema"` first, then every
+ * other key in `keyOrder` (falling back to `Object.keys(obj)` if the caller
+ * has none — e.g. a brand-new file), 2-space indent, trailing newline.
+ *
+ * Deliberately NOT `JSON.stringify(orderedObject, null, 2)` on a
+ * spread-reordered plain object (#6, D1 diff-contract): building a plain
+ * object and letting the engine enumerate its keys reorders any INTEGER-LIKE
+ * key ("1", "2", "10") to numeric-ascending regardless of insertion order —
+ * so a table keyed by numeric strings would get its whole file reordered on
+ * the very first value edit. Emitting the object manually, key by key, in
+ * the exact order the caller hands us, sidesteps that reindexing entirely.
+ */
+function serializeDataFile(obj: Record<string, unknown>, keyOrder?: string[]): string {
+  const hasSchema = '$schema' in obj;
+  const rest = (keyOrder ?? Object.keys(obj)).filter((k) => k !== '$schema' && k in obj);
+  const order = hasSchema ? ['$schema', ...rest] : rest;
+  if (order.length === 0) return '{}\n';
+  const lines = order.map((k) => {
+    const valueJson = JSON.stringify(obj[k], null, 2);
+    return `  ${JSON.stringify(k)}: ${valueJson.split('\n').join('\n  ')}`;
+  });
+  return `{\n${lines.join(',\n')}\n}\n`;
+}
+
+/**
+ * Immutable set-at-path (W2 hardening, path-aware commits): spreads at every
+ * level the path touches, so untouched sibling keys — AND their original
+ * declaration order — survive unchanged (D1's diff-minimal contract; only
+ * the leaf's value actually changes in the serialized JSON). A path
+ * segment whose current value isn't an object (e.g. the field didn't exist
+ * yet, or a schema/data mismatch) starts that level fresh from `{}` rather
+ * than throwing — the write always succeeds, matching the panel's other
+ * commit paths (`setCell` has the same defensive fallback).
+ */
+function setDeep(
+  obj: Record<string, unknown>,
+  path: string[],
+  value: unknown,
+): Record<string, unknown> {
+  const [head, ...rest] = path;
+  if (head === undefined) return obj;
+  if (rest.length === 0) return { ...obj, [head]: value };
+  const child = obj[head];
+  const childObj =
+    child && typeof child === 'object' && !Array.isArray(child)
+      ? (child as Record<string, unknown>)
+      : {};
+  return { ...obj, [head]: setDeep(childObj, rest, value) };
+}
+
+export function DataPanel({ active }: { active: boolean }) {
+  const [files, setFiles] = useState<LoadedDataFile[]>([]);
+  const [selectedPath, setSelectedPath] = useState<string | null>(null);
+
+  const refresh = useCallback(async () => {
+    try {
+      const res = await fetch('/__editor/data-files');
+      if (!res.ok) return;
+      const { files: raw } = (await res.json()) as { files: ServerDataFile[] };
+      setFiles(raw.map(parseServerFile));
+    } catch {
+      /* server unreachable — keep whatever we last had */
+    }
+  }, []);
+
+  // Re-scan whenever the tab is shown (D3: discovery IS the folder scan —
+  // never a cached manifest, so activating the tab always reflects disk).
+  useEffect(() => {
+    if (active) void refresh();
+  }, [active, refresh]);
+
+  // W6a: a NEW `src/data/*.data.json`/`*.schema.json` (or a deleted one)
+  // appears/disappears in the master list without switching tabs — the
+  // server's `src/`-scoped watcher broadcasts add/unlink only (a `change`
+  // event is deliberately excluded: it would echo this panel's own
+  // `/__editor/data-file` POST writes back into a refetch, clobbering
+  // in-flight drafts). `refresh` is the same rescan the tab-activation
+  // effect above already runs.
+  useEffect(() => connectDataFileEvents(() => void refresh()), [refresh]);
+
+  const selected = files.find((f) => f.path === selectedPath) ?? files[0] ?? null;
+
+  // `'ref'` widget picker options (§2.2's designer payoff): every loaded
+  // file's own top-level keys, keyed by asset stem — recomputed only when
+  // `files` actually changes (a fresh fetch, or a local commit updating one
+  // file's `data` in place).
+  const refOptionsByStem = useMemo(() => {
+    const map = new Map<string, string[]>();
+    for (const f of files) {
+      if (!f.data) continue;
+      const stem = f.path.replace(/^src\/data\//, '').replace(/\.data\.json$/, '');
+      map.set(
+        stem,
+        Object.keys(f.data).filter((k) => k !== '$schema'),
+      );
+    }
+    return map;
+  }, [files]);
+
+  /**
+   * D1 (spec §2.5): commit → write the file IMMEDIATELY, no buffering. The
+   * local copy is updated in the same tick so widgets stay live; disk is the
+   * document. D5 resolution: this deliberately BYPASSES the play-mode overlay
+   * (scene-entity-only) — a running game receives the change through the
+   * shipped `.data.json` HMR path instead (see the `/__editor/data-file`
+   * route's doc comment in editor-server.ts).
+   *
+   * Takes the whole `LoadedDataFile` (not just its path, #6) so it can read
+   * that file's CURRENT `keyOrder` straight from the caller's own prop/state
+   * closure — no stale-closure risk from reaching into the panel's `files`
+   * state inside this `useCallback([])`. `nextKeyOrder` folds the commit's
+   * keys into that order once, and the result becomes this file's `keyOrder`
+   * going forward, so a whole session of edits keeps the file's original
+   * on-disk key order (integer-like keys included) stable throughout.
+   */
+  const writeFile = useCallback((file: LoadedDataFile, nextData: Record<string, unknown>) => {
+    const order = nextKeyOrder(file.keyOrder, nextData);
+    const content = serializeDataFile(nextData, order);
+    setFiles((prev) =>
+      prev.map((f) => (f.path === file.path ? { ...f, data: nextData, keyOrder: order } : f)),
+    );
+    void fetch('/__editor/data-file', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ path: file.path, content }),
+    });
+  }, []);
+
+  if (files.length === 0) {
+    return <EmptyState />;
+  }
+
+  return (
+    <RefOptionsContext.Provider value={refOptionsByStem}>
+      <div style={{ display: 'flex', flex: 1, minHeight: 0 }}>
+        {/* File list (master) */}
+        <div
+          style={{
+            width: 200,
+            flexShrink: 0,
+            borderRight: '1px solid #333',
+            overflowY: 'auto',
+            padding: '4px 0',
+          }}
+        >
+          {files.map((f) => {
+            const isSelected = f.path === selected?.path;
+            const name = f.path.replace(/^src\/data\//, '').replace(/\.data\.json$/, '');
+            return (
+              <button
+                key={f.path}
+                type="button"
+                data-testid={`data-file-${name}`}
+                onClick={() => setSelectedPath(f.path)}
+                title={f.path}
+                style={{
+                  display: 'block',
+                  width: '100%',
+                  textAlign: 'left',
+                  background: isSelected ? '#2c2c2c' : 'transparent',
+                  color: isSelected ? '#c5c8ce' : '#8c8c8c',
+                  border: 'none',
+                  borderLeft: isSelected ? '2px solid #579EFF' : '2px solid transparent',
+                  padding: '4px 10px',
+                  cursor: 'pointer',
+                  fontSize: 12,
+                }}
+              >
+                {name}
+              </button>
+            );
+          })}
+        </div>
+
+        {/* Editor (detail) */}
+        <div style={{ flex: 1, minWidth: 0, overflow: 'auto', padding: 10 }}>
+          {selected && <DataFileEditor file={selected} writeFile={writeFile} />}
+        </div>
+      </div>
+    </RefOptionsContext.Provider>
+  );
+}
+
+/**
+ * A minimal, paste-ready `.schema.ts` + `.data.json` pair (W6d) — mirrors the
+ * shape of the shipped `tuning.*` trio (template/src/data/README.md), just
+ * renamed/generic so it's obviously a starting point to rename, not the real
+ * thing to keep verbatim. No file-creating server verb this wave (deferred —
+ * today's write routes are purpose-scoped, `src/data/**\/*.data.json` only;
+ * a general project-file write API needs its own security ruling), so this
+ * is copy-paste, not a button that writes to disk.
+ */
+const STARTER_FILES = `// src/data/example.schema.ts
+import { z } from 'zod';
+
+export const ExampleSchema = z.object({
+  speed: z.number().min(0).max(10).default(1).describe('Example tunable — rename me'),
+  label: z.string().default('hello').describe('Example string field'),
+});
+
+export type Example = z.infer<typeof ExampleSchema>;
+
+// src/data/example.data.json
+{
+  "$schema": "./example.schema.json",
+  "speed": 1,
+  "label": "hello"
+}
+`;
+
+/**
+ * DATA tab empty state (W6d, docs/DATA-TOOLS-DESIGN.md §3.5): the project has
+ * no `src/data/*.data.json` yet. Teaches the concrete recipe rather than just
+ * naming the shape, plus a one-click "Copy starter files" so the first asset
+ * doesn't require memorizing the trio from scratch. Once the files exist +
+ * `npm run emit-schemas` has run, the new asset appears here automatically —
+ * no reload, W6a's src-watcher SSE channel picks it up.
+ */
+function EmptyState() {
+  const [copied, setCopied] = useState(false);
+
+  const copyStarter = () => {
+    void navigator.clipboard.writeText(STARTER_FILES).then(() => {
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1500);
+    });
+  };
+
+  return (
+    <div style={{ padding: 12, fontSize: 12, color: '#8c8c8c', maxWidth: 480 }}>
+      <p style={{ margin: '0 0 8px' }}>
+        No data assets yet — a data asset is a <code>src/data/*.data.json</code> file governed by a
+        Zod schema (docs/DATA-TOOLS-DESIGN.md §2).
+      </p>
+      <ol style={{ margin: '0 0 10px', paddingLeft: 18 }}>
+        <li>
+          Create <code>src/data/&lt;name&gt;.schema.ts</code> — a Zod object (or{' '}
+          <code>z.record(...)</code> for a table) exporting the schema.
+        </li>
+        <li>
+          Create <code>src/data/&lt;name&gt;.data.json</code> with a <code>"$schema"</code> line
+          pointing at the emitted schema, plus starting values.
+        </li>
+        <li>
+          Run <code>npm run emit-schemas</code> in the project — it writes the emitted{' '}
+          <code>.schema.json</code> and validates the data file against it.
+        </li>
+      </ol>
+      <p style={{ margin: '0 0 8px' }}>
+        See the project's <code>src/data/README.md</code> for the full trio doctrine and the shipped{' '}
+        <code>tuning.*</code> worked example.
+      </p>
+      <button
+        type="button"
+        data-testid="data-empty-copy-starter"
+        onClick={copyStarter}
+        style={{
+          background: '#2c2c2c',
+          color: '#c5c8ce',
+          border: '1px solid #444',
+          borderRadius: 2,
+          padding: '4px 10px',
+          fontSize: 12,
+          cursor: 'pointer',
+        }}
+      >
+        {copied ? 'Copied' : 'Copy starter files'}
+      </button>
+    </div>
+  );
+}
+
+function DataFileEditor({
+  file,
+  writeFile,
+}: {
+  file: LoadedDataFile;
+  writeFile: (file: LoadedDataFile, nextData: Record<string, unknown>) => void;
+}) {
+  if (file.error) {
+    return <Message text={`${file.path}: ${file.error}`} tone="error" />;
+  }
+  if (!file.hasSchema) {
+    // Teaching message, house style: name the fix (D4 — emitted schemas are
+    // the artifact the editor consumes; without one there are no widget types).
+    return (
+      <Message
+        text={`${file.path} has no emitted schema (${file.path.replace(/\.data\.json$/, '.schema.json')}). Run \`npm run emit-schemas\` in the project to generate it.`}
+        tone="warn"
+      />
+    );
+  }
+  if (!file.shape || !file.data) {
+    return (
+      <Message
+        text={`${file.path}: emitted schema is not one of the two blessed shapes (singleton object or z.record table — spec §2.1).`}
+        tone="warn"
+      />
+    );
+  }
+
+  const data = file.data;
+
+  if (file.shape.shape === 'singleton') {
+    // Path-aware write (W2 hardening): a nested `group` field commits through
+    // the SAME immutable `setDeep`, so an edit three levels down (e.g.
+    // `enemyKinds.scout.hp`) only ever replaces the leaf — every other level
+    // is spread, preserving key order (D1's diff-minimal contract). This is
+    // what keeps a nested singleton's serialized shape an OBJECT at every
+    // level instead of ever collapsing a branch to a JSON string.
+    const onCommitAt = (path: string[], value: unknown) => {
+      writeFile(file, setDeep(data, path, value));
+    };
+    return (
+      <div style={{ maxWidth: 480 }}>
+        <FieldList fields={file.shape.fields} value={data} path={[]} onCommitAt={onCommitAt} />
+      </div>
+    );
+  }
+
+  // Table: one grid row per data key ("$schema" is plumbing, never a row),
+  // one column per row-schema field, plus row add/remove (W6b) — a separate
+  // component because add-row needs its own draft-key state (hooks can't
+  // live in this early-return-heavy function; see `TableEditor`'s comment).
+  return (
+    <TableEditor file={file} data={data} rowFields={file.shape.rowFields} writeFile={writeFile} />
+  );
+}
+
+function Message({ text, tone }: { text: string; tone: 'error' | 'warn' }) {
+  return (
+    <div style={{ fontSize: 12, color: tone === 'error' ? '#FF6B6B' : '#FFD866', maxWidth: 560 }}>
+      {text}
+    </div>
+  );
+}
+
+/**
+ * Table-shape data-file editor (W6b, docs/DATA-TOOLS-DESIGN.md §7): the grid
+ * itself (one row per data key, one column per row-schema field — unchanged
+ * from W2) plus row add/remove. Pulled out of `DataFileEditor` because it's
+ * the only shape needing its own hook state (the add-row key draft + inline
+ * error) — `DataFileEditor` stays a plain function with early-return teaching
+ * branches (no conditional hooks).
+ */
+function TableEditor({
+  file,
+  data,
+  rowFields,
+  writeFile,
+}: {
+  file: LoadedDataFile;
+  data: Record<string, unknown>;
+  rowFields: DataFieldDescriptor[];
+  writeFile: (file: LoadedDataFile, nextData: Record<string, unknown>) => void;
+}) {
+  const rowKeys = Object.keys(data).filter((k) => k !== '$schema');
+  // Any successful edit through the grid/add-row clears a stale CSV import
+  // error block (W6c) — it describes the LAST import attempt, not the
+  // current state of the file.
+  const [importErrors, setImportErrors] = useState<string[]>([]);
+
+  const setCell = (rowKey: string, fieldName: string, value: unknown) => {
+    const row = data[rowKey];
+    const rowObj = row && typeof row === 'object' ? (row as Record<string, unknown>) : {};
+    writeFile(file, { ...data, [rowKey]: { ...rowObj, [fieldName]: value } });
+    if (importErrors.length > 0) setImportErrors([]);
+  };
+
+  // Remove: no confirm dialog (D1's "undo is git" stance) — `$schema`
+  // survives in `rest` (re-ordered first by `serializeDataFile`), and the
+  // spread preserves every other row's key order.
+  const removeRow = (rowKey: string) => {
+    const { [rowKey]: _removed, ...rest } = data;
+    writeFile(file, rest);
+    if (importErrors.length > 0) setImportErrors([]);
+  };
+
+  const [newKey, setNewKey] = useState('');
+  const [addError, setAddError] = useState<string | null>(null);
+
+  const addRow = () => {
+    const trimmed = newKey.trim();
+    if (!trimmed) {
+      setAddError('Row key cannot be empty.');
+      return;
+    }
+    if (trimmed === '$schema') {
+      setAddError('"$schema" is reserved and cannot be a row key.');
+      return;
+    }
+    if (trimmed in data) {
+      setAddError(`Row "${trimmed}" already exists.`);
+      return;
+    }
+    const row = Object.fromEntries(rowFields.map((f) => [f.name, defaultValueForDescriptor(f)]));
+    writeFile(file, { ...data, [trimmed]: row }); // appends — key order preserved
+    setNewKey('');
+    setAddError(null);
+    if (importErrors.length > 0) setImportErrors([]);
+  };
+
+  // ---- CSV round-trip (W6c) ----
+  const fileInputRef = useRef<HTMLInputElement>(null);
+
+  const exportCsv = () => {
+    const csv = tableToCsv(data, rowFields);
+    const blob = new Blob([csv], { type: 'text/csv' });
+    const url = URL.createObjectURL(blob);
+    const baseName = file.path.replace(/^src\/data\//, '').replace(/\.data\.json$/, '');
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = `${baseName}.csv`;
+    a.click();
+    URL.revokeObjectURL(url);
+  };
+
+  const importCsv = async (fileList: FileList | null) => {
+    const picked = fileList?.[0];
+    if (fileInputRef.current) fileInputRef.current.value = ''; // allow re-picking the same file
+    if (!picked) return;
+    const text = await picked.text();
+    const { rows, errors } = csvToTable(text, rowFields);
+    if (errors.length > 0) {
+      setImportErrors(errors);
+      return; // atomic — nothing written
+    }
+    setImportErrors([]);
+    // Whole-table replace: a CSV IS the table. `$schema` is plumbing, carried
+    // over from the current file (never itself a CSV column).
+    const next: Record<string, unknown> = '$schema' in data ? { $schema: data['$schema'] } : {};
+    writeFile(file, { ...next, ...rows });
+  };
+
+  return (
+    <div>
+      <div style={{ display: 'flex', gap: 6, marginBottom: 8 }}>
+        <button
+          type="button"
+          data-testid="data-csv-export"
+          onClick={exportCsv}
+          title="Download this table as a CSV file"
+          style={{
+            background: '#2c2c2c',
+            color: '#c5c8ce',
+            border: '1px solid #444',
+            borderRadius: 2,
+            padding: '3px 10px',
+            fontSize: 12,
+            cursor: 'pointer',
+          }}
+        >
+          Export CSV
+        </button>
+        <button
+          type="button"
+          data-testid="data-csv-import"
+          onClick={() => fileInputRef.current?.click()}
+          title="Import replaces every row in this file (undo is git)."
+          style={{
+            background: '#2c2c2c',
+            color: '#c5c8ce',
+            border: '1px solid #444',
+            borderRadius: 2,
+            padding: '3px 10px',
+            fontSize: 12,
+            cursor: 'pointer',
+          }}
+        >
+          Import CSV
+        </button>
+        <input
+          ref={fileInputRef}
+          type="file"
+          accept=".csv,text/csv"
+          style={{ display: 'none' }}
+          onChange={(e) => void importCsv(e.target.files)}
+        />
+      </div>
+      {importErrors.length > 0 && (
+        <div data-testid="data-csv-errors" style={{ marginBottom: 8 }}>
+          {importErrors.map((err) => (
+            <Message key={err} text={err} tone="error" />
+          ))}
+        </div>
+      )}
+      <div
+        style={{
+          display: 'grid',
+          gridTemplateColumns: `110px repeat(${rowFields.length}, minmax(100px, 200px)) 24px`,
+          gap: '3px 6px',
+          alignItems: 'center',
+          width: 'max-content',
+        }}
+      >
+        {/* Header row */}
+        <span style={{ ...labelStyle, width: 'auto' }} />
+        {rowFields.map((f) => {
+          const head = (
+            <span key={f.name} style={{ ...labelStyle, width: 'auto', fontWeight: 600 }}>
+              {f.name}
+            </span>
+          );
+          return f.description ? (
+            <Tooltip key={f.name} text={f.description} position="bottom">
+              {head}
+            </Tooltip>
+          ) : (
+            head
+          );
+        })}
+        <span />
+
+        {rowKeys.map((rowKey) => {
+          const row = data[rowKey];
+          const rowObj = row && typeof row === 'object' ? (row as Record<string, unknown>) : {};
+          return (
+            <Fragment key={rowKey}>
+              <span style={{ ...labelStyle, width: 'auto', color: '#b0b0b0', fontWeight: 600 }}>
+                {rowKey}
+              </span>
+              {rowFields.map((f) => (
+                <Widget
+                  key={f.name}
+                  field={f}
+                  value={f.name in rowObj ? rowObj[f.name] : f.default}
+                  onCommit={(v) => setCell(rowKey, f.name, v)}
+                  testId={`data-cell-${rowKey}-${f.name}`}
+                />
+              ))}
+              <button
+                type="button"
+                data-testid={`data-row-remove-${rowKey}`}
+                title="Remove row (undo is git)"
+                onClick={() => removeRow(rowKey)}
+                style={{
+                  background: 'transparent',
+                  border: 'none',
+                  color: '#8c8c8c',
+                  cursor: 'pointer',
+                  fontSize: 13,
+                  lineHeight: 1,
+                  padding: '2px 4px',
+                }}
+              >
+                ×
+              </button>
+            </Fragment>
+          );
+        })}
+      </div>
+
+      <div style={{ display: 'flex', alignItems: 'center', gap: 6, marginTop: 8 }}>
+        <input
+          data-testid="data-row-add-key"
+          placeholder="new-row-key"
+          value={newKey}
+          onChange={(e) => {
+            setNewKey(e.target.value);
+            if (addError) setAddError(null);
+          }}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter') addRow();
+          }}
+          style={{ ...inputStyle, width: 160 }}
+        />
+        <button
+          type="button"
+          data-testid="data-row-add"
+          onClick={addRow}
+          style={{
+            background: '#2c2c2c',
+            color: '#c5c8ce',
+            border: '1px solid #444',
+            borderRadius: 2,
+            padding: '3px 10px',
+            fontSize: 12,
+            cursor: 'pointer',
+          }}
+        >
+          Add row
+        </button>
+      </div>
+      {addError && (
+        <div style={{ marginTop: 4 }}>
+          <Message text={addError} tone="error" />
+        </div>
+      )}
+    </div>
+  );
+}
+
+function FieldRow({
+  name,
+  description,
+  children,
+}: {
+  name: string;
+  description?: string | undefined;
+  children: React.ReactNode;
+}) {
+  const label = <span style={labelStyle}>{name}</span>;
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 4, marginBottom: 3 }}>
+      {description ? (
+        <Tooltip text={description} position="right">
+          {label}
+        </Tooltip>
+      ) : (
+        label
+      )}
+      <div style={{ flex: 1, minWidth: 0 }}>{children}</div>
+    </div>
+  );
+}
+
+/**
+ * Recursive singleton-form renderer (W2 hardening §3.2): a `'group'`
+ * descriptor renders as an indented, bordered sub-form (a nested `FieldList`
+ * over its `children`) instead of falling back to a raw-JSON cell; every
+ * other kind renders the existing `Widget`. `path` accumulates the field
+ * names from the form root down to this row so `onCommitAt` can write
+ * exactly the touched leaf via `setDeep` — nothing above or beside it in the
+ * nested object is ever re-typed as a string.
+ */
+function FieldList({
+  fields,
+  value,
+  path,
+  onCommitAt,
+}: {
+  fields: DataFieldDescriptor[];
+  value: Record<string, unknown>;
+  path: string[];
+  onCommitAt: (path: string[], value: unknown) => void;
+}) {
+  return (
+    <>
+      {fields.map((f) => {
+        const fieldPath = [...path, f.name];
+        const raw = f.name in value ? value[f.name] : f.default;
+        const testId = `data-field-${fieldPath.join('.')}`;
+
+        if (f.kind === 'group') {
+          const childValue =
+            raw && typeof raw === 'object' && !Array.isArray(raw)
+              ? (raw as Record<string, unknown>)
+              : {};
+          return (
+            <div
+              key={f.name}
+              data-testid={testId}
+              style={{
+                border: '1px solid #333',
+                borderRadius: 3,
+                padding: '6px 8px',
+                marginBottom: 6,
+                marginLeft: Math.min(path.length, 3) * 10,
+              }}
+            >
+              <GroupHeader name={f.name} description={f.description} />
+              <FieldList
+                fields={f.children ?? []}
+                value={childValue}
+                path={fieldPath}
+                onCommitAt={onCommitAt}
+              />
+            </div>
+          );
+        }
+
+        return (
+          <FieldRow key={f.name} name={f.name} description={f.description}>
+            <Widget
+              field={f}
+              value={raw}
+              onCommit={(v) => onCommitAt(fieldPath, v)}
+              testId={testId}
+            />
+          </FieldRow>
+        );
+      })}
+    </>
+  );
+}
+
+function GroupHeader({ name, description }: { name: string; description?: string | undefined }) {
+  const label = (
+    <div style={{ fontSize: 11, color: '#a0a0a0', fontWeight: 600, marginBottom: 4 }}>{name}</div>
+  );
+  return description ? (
+    <Tooltip text={description} position="right">
+      {label}
+    </Tooltip>
+  ) : (
+    label
+  );
+}
+
+/**
+ * One typed cell/field widget — the SAME primitives the component inspector
+ * renders `FieldDescriptor`s with (`ComponentsSection.renderWidget`), so the
+ * Data panel looks native. Number edits clamp to the schema's
+ * `minimum`/`maximum` (the JSON-Schema extra `DataFieldDescriptor` carries).
+ */
+function Widget({
+  field,
+  value,
+  onCommit,
+  testId,
+}: {
+  field: DataFieldDescriptor;
+  value: unknown;
+  onCommit: (value: unknown) => void;
+  testId: string;
+}) {
+  // Read unconditionally (hook rules) even though only the `'ref'` case below
+  // uses it — cheap, and `RefOptionsContext`'s default (empty map) makes a
+  // ref field outside the panel's own provider degrade to the "target not
+  // loaded" fallback rather than crash.
+  const refOptions = useContext(RefOptionsContext);
+
+  switch (field.kind) {
+    case 'number':
+      return <NumberCell field={field} value={value} onCommit={onCommit} testId={testId} />;
+    case 'boolean':
+      return (
+        <input
+          type="checkbox"
+          data-testid={testId}
+          checked={Boolean(value)}
+          onChange={(e) => onCommit(e.target.checked)}
+        />
+      );
+    case 'color':
+      return (
+        <div data-testid={testId}>
+          <ColorInput value={typeof value === 'string' ? value : '#ffffff'} onChange={onCommit} />
+        </div>
+      );
+    case 'enum':
+      return (
+        <select
+          data-testid={testId}
+          value={value == null ? '' : String(value)}
+          onChange={(e) => onCommit(e.target.value)}
+          style={{ ...inputStyle, cursor: 'pointer' }}
+        >
+          {(field.options ?? []).map((opt) => (
+            <option key={opt} value={opt}>
+              {opt}
+            </option>
+          ))}
+        </select>
+      );
+    case 'string':
+      return <StringCell value={value} onCommit={onCommit} testId={testId} />;
+    case 'ref': {
+      // The designer payoff (§2.2): a declared `dataRef(target)` field
+      // renders as a `stem#key` PICKER, sourced from the target file's own
+      // top-level keys (already loaded — every data file's raw text is
+      // fetched by this same panel, see `RefOptionsContext` above), instead
+      // of free text. Falls back to `StringCell` when the target file isn't
+      // loaded (renamed/deleted/never existed — `vgai doctor`'s
+      // `data-ref-missing-file` is the enforcement side of that) or the
+      // current value carries a deeper `key.field` path (v1 scope: deep ref
+      // addresses stay free-text, per the design note this module's history
+      // carries).
+      const targetStem = field.refTarget;
+      const targetKeys = targetStem !== undefined ? refOptions.get(targetStem) : undefined;
+      const current = typeof value === 'string' ? value : '';
+      const hasDeepPath = current.includes('#') && (current.split('#')[1]?.includes('.') ?? false);
+      if (targetStem === undefined || targetKeys === undefined || hasDeepPath) {
+        return <StringCell value={value} onCommit={onCommit} testId={testId} />;
+      }
+      const options = targetKeys.map((k) => `${targetStem}#${k}`);
+      const isDangling = current !== '' && !options.includes(current);
+      return (
+        <select
+          data-testid={testId}
+          value={current}
+          onChange={(e) => onCommit(e.target.value)}
+          style={{ ...inputStyle, cursor: 'pointer' }}
+        >
+          <option value="">—</option>
+          {options.map((opt) => (
+            <option key={opt} value={opt}>
+              {opt}
+            </option>
+          ))}
+          {isDangling && <option value={current}>{current} (dangling)</option>}
+        </select>
+      );
+    }
+    default:
+      // 'group' (only reachable here from a TABLE cell — nested sub-forms
+      // inside a grid cell are deferred, W6) and 'json' (arrays, unions,
+      // anything past the group depth cap) both fall back to the
+      // type-preserving `JsonCell`. This is the correctness floor (W2
+      // hardening): `StringCell` commits raw text, which is only ever safe
+      // for an actual `type: 'string'` field — every other degraded case
+      // MUST go through a parse-or-refuse cell, never a bare string commit.
+      return <JsonCell value={value} onCommit={onCommit} testId={testId} />;
+  }
+}
+
+/**
+ * Number field/cell: buffers a drag scrub into ONE commit at release, instead
+ * of one per pointermove (#3). `NumberInput` still calls `onChange` on every
+ * intermediate move (so the widget's OWN displayed number stays live-scrub
+ * responsive) — but here that per-move callback only updates `live`, local
+ * state that overrides the authoritative `value` prop for display purposes.
+ * The actual `onCommit` (a `writeFile` → POST, non-atomic disk truncate-write
+ * per D1) fires from `onChangeEnd` instead, which `NumberInput` invokes
+ * exactly once per gesture: on pointerup after a real drag, or once for a
+ * typed blur/Enter edit (already single-shot, unaffected either way).
+ */
+function NumberCell({
+  field,
+  value,
+  onCommit,
+  testId,
+}: {
+  field: DataFieldDescriptor;
+  value: unknown;
+  onCommit: (value: unknown) => void;
+  testId: string;
+}) {
+  const clamp = (v: number) => {
+    let out = v;
+    if (field.min !== undefined) out = Math.max(field.min, out);
+    if (field.max !== undefined) out = Math.min(field.max, out);
+    return out;
+  };
+  const authoritative = typeof value === 'number' ? value : Number(value) || 0;
+  const [live, setLive] = useState<number | null>(null);
+
+  // Once the authoritative (committed/file) value changes underneath us —
+  // our own commit landing, another widget, a reload — drop the live
+  // override so we go back to reflecting real state.
+  useEffect(() => {
+    setLive(null);
+  }, [authoritative]);
+
+  return (
+    <NumberInput
+      value={live ?? authoritative}
+      onChange={(v) => setLive(clamp(v))}
+      onChangeEnd={(v) => {
+        setLive(null);
+        onCommit(clamp(v));
+      }}
+      testId={testId}
+    />
+  );
+}
+
+/**
+ * Draft-buffered text cell: commits on blur/Enter, reverts on Escape — unlike
+ * the inspector's keystroke-live `RawInput`, because HERE every commit is a
+ * FILE write (D1) and per-keystroke writes would spam disk + HMR.
+ *
+ * `kind: 'string'` ONLY (W2 hardening) — a real string field can never be
+ * widened by committing raw text, because the field already IS a string.
+ * Non-string fallbacks render `JsonCell` instead (see `Widget`'s `default`).
+ */
+function StringCell({
+  value,
+  onCommit,
+  testId,
+}: {
+  value: unknown;
+  onCommit: (value: unknown) => void;
+  testId: string;
+}) {
+  const display = value === null || value === undefined ? '' : String(value);
+  const [draft, setDraft] = useState(display);
+  // Escape below calls `.blur()` imperatively, which fires the native
+  // blur/focusout event SYNCHRONOUSLY inside the same handler — so the
+  // resulting `onBlur={commit}` closes over the PRE-revert `draft` (React
+  // hasn't re-rendered yet) and would re-commit the just-discarded edit. Same
+  // fix as `primitives/JsonInput.tsx`'s `revertingRef`: Escape sets it before
+  // blurring, `commit()` checks it first and no-ops instead of racing it.
+  const revertingRef = useRef(false);
+
+  // Re-sync when the underlying value changes (file re-list, another widget).
+  useEffect(() => {
+    setDraft(display);
+  }, [display]);
+
+  const commit = () => {
+    if (revertingRef.current) {
+      revertingRef.current = false;
+      return;
+    }
+    if (draft !== display) onCommit(draft);
+  };
+
+  return (
+    <input
+      data-testid={testId}
+      value={draft}
+      onChange={(e) => setDraft(e.target.value)}
+      onBlur={commit}
+      onKeyDown={(e) => {
+        if (e.key === 'Enter') {
+          commit();
+          (e.target as HTMLInputElement).blur();
+        } else if (e.key === 'Escape') {
+          revertingRef.current = true;
+          setDraft(display);
+          (e.target as HTMLInputElement).blur();
+        }
+      }}
+      style={inputStyle}
+    />
+  );
+}
+
+/**
+ * Type-preserving fallback cell (W2 hardening — the correctness floor, spec
+ * §2.1). Used for anything the panel can't render a typed widget for: a
+ * nested `group` past the depth cap, arrays, unions — and (until §2.1's
+ * variant picker ships) discriminated unions.
+ *
+ * The invariant this cell exists to hold: **a commit must never widen a
+ * typed value into a JSON string.** `commit()` runs `JSON.parse(draft)` and
+ * hands `onCommit` the PARSED value, never the raw text. On parse failure it
+ * REFUSES the commit outright — the draft stays exactly as typed, the input
+ * shows an error state, and no write/POST fires — so a mid-edit invalid JSON
+ * string can never reach disk (which is exactly how the live-observed
+ * corruption happened before this cell existed: a raw string committed
+ * straight over a typed object field).
+ */
+function JsonCell({
+  value,
+  onCommit,
+  testId,
+}: {
+  value: unknown;
+  onCommit: (value: unknown) => void;
+  testId: string;
+}) {
+  const display = value === undefined ? '' : JSON.stringify(value);
+  const [draft, setDraft] = useState(display);
+  const [invalid, setInvalid] = useState(false);
+  // Same race as `primitives/JsonInput.tsx`'s `revertingRef`: Escape's
+  // imperative `.blur()` fires `onBlur={commit}` synchronously, before React
+  // re-renders with the reverted draft — so `commit`'s closure still sees the
+  // pre-revert (possibly invalid, always discarded) draft and would commit or
+  // re-flag it right after Escape cleared it. This ref lets Escape tell the
+  // nested commit to no-op instead of racing it.
+  const revertingRef = useRef(false);
+
+  // Re-sync when the underlying value changes (file re-list, another widget).
+  useEffect(() => {
+    setDraft(display);
+    setInvalid(false);
+  }, [display]);
+
+  const commit = () => {
+    if (revertingRef.current) {
+      revertingRef.current = false;
+      return;
+    }
+    if (draft === display) {
+      setInvalid(false);
+      return;
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(draft);
+    } catch {
+      setInvalid(true); // refuse: keep the draft, no onCommit, no write
+      return;
+    }
+    setInvalid(false);
+    onCommit(parsed);
+  };
+
+  return (
+    <div>
+      <input
+        data-testid={testId}
+        value={draft}
+        onChange={(e) => {
+          setDraft(e.target.value);
+          if (invalid) setInvalid(false);
+        }}
+        onBlur={commit}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter') {
+            commit();
+          } else if (e.key === 'Escape') {
+            revertingRef.current = true;
+            setDraft(display);
+            setInvalid(false);
+            (e.target as HTMLInputElement).blur();
+          }
+        }}
+        style={invalid ? { ...inputStyle, borderColor: '#FF6B6B', color: '#FF6B6B' } : inputStyle}
+        title={
+          invalid
+            ? 'Not valid JSON — nothing written. Fix the JSON or press Escape to revert.'
+            : undefined
+        }
+      />
+      {invalid && (
+        <div
+          data-testid={`${testId}-error`}
+          style={{ fontSize: 10, color: '#FF6B6B', marginTop: 2 }}
+        >
+          Not valid JSON — nothing written. Fix the JSON or press Escape to revert.
+        </div>
+      )}
+    </div>
+  );
+}