@vgai/editor 0.2.0

package/vite-plugin-ui-oid.ts

@@ -0,0 +1,561 @@
+/**
+ * Vite plugin: live OID instrumentation + source-write endpoints (C1/C2/C7/C8).
+ *
+ * The visual-edit "trick" made live for hand-authored React UI components: at dev
+ * time it stamps `data-oid` on every JSX element in files matched by `include` (a
+ * predicate, so the rest of the editor build is untouched), builds an OID→source
+ * index, and serves:
+ *   GET  /__ui-source/index            → the whole OID index
+ *   POST /__ui-source/write {oid,prop,value} → surgical inline-style edit to source
+ *   POST /__ui-source/struct {oid,op}  → structural source edit (delete)
+ * Edits run the SAME `writer.ts` used in unit tests, server-side, then Vite HMR
+ * reloads. `data-oid` exists only in transform output, never on disk.
+ *
+ * `include` widening (T6.2 slice 2, `docs/REACT-WORLD-DESIGN.md` §1.D): the original
+ * scope was ONLY `ui-editor/editable-components/*.tsx` (the visual-edit fixture dir,
+ * for `UIAuthoringAdapter`/`SourceEditPanel`). A react WORLD's entry graph is a real
+ * project's `.tsx` source — the mounted template project (`packages/editor/template/
+ * src/**`) or an externally-scaffolded project directory reached via the SAME
+ * dev-server `fs.allow` pipeline `server/dev.ts` already builds for project scripts
+ * (T3.3) — so `ReactWorldAuthoringAdapter` needs those files instrumented too.
+ * `defaultProjectScopeInclude` widens to PROJECT scope, not repo-global: any `.tsx`
+ * file outside `node_modules`, EXCEPT the vgai tooling/engine source trees this repo
+ * itself is built from (`packages/engine/src`, `packages/create-vgai-project`,
+ * `packages/vgai-cli`, `packages/editor-sdk`, and `packages/editor/src` generally —
+ * carving OUT `ui-editor/editable-components` so the existing UI-edit-mode surface
+ * keeps working unchanged). This does NOT depend on which project happens to be
+ * open — `fs.allow` already bounds what Vite can even reach, and this predicate
+ * additionally keeps the vgai app's OWN react source un-instrumented.
+ *
+ * Vendored-tree exclusion (Track N, D-N4 item 2 — docs/REACT-INGEST-LANDING-
+ * DESIGN.md): any path under a `/vendor/` segment (`vendor/pixi-games/…`,
+ * and — once N2 lands — `vendor/react-games/…`) is REJECTED regardless of
+ * extension. Vendored trees hold unmodified, foreign game source (Track P's
+ * pixi games today; Track N's react games starting N2) — the whole point of
+ * vendoring is a byte-for-byte, never-modified tree (`verify-unaltered.mjs`'s
+ * zero-diff CI gate). `data-oid` stamping is what makes a `.tsx` file
+ * WRITABLE through `/__ui-source/write` (`ReactWorldAuthoringAdapter`'s
+ * source-write path, D-N4 item 1's companion) — stamping a vendored file
+ * would silently reopen the never-modify-game-source rule for it. Today this
+ * is a no-op in practice (the existing `.tsx`-only filter already misses
+ * `vendor/pixi-games/`'s `.jsx` sources, and react-rpg — the first vendored
+ * react game, D-N5 — is ALSO `.jsx`), but it is closing a real future hole,
+ * not changing current behavior: the day a vendored `.tsx` game lands (or an
+ * existing one is ever renamed), this is the only thing standing between it
+ * and becoming editable.
+ *
+ * D-Y4 (wave 2, docs/EXTERNAL-REACT-AND-MODULE-DESIGN.md §1/§4 slice S3) —
+ * the write-back ban becomes IDENTITY-scoped, not just location-scoped: the
+ * `/vendor/` regex above only protects the repo's OWN vendored trees, but
+ * wave 2 lets an `ingest-react` world live in ANY external, user-owned
+ * folder (`vgai edit <folder>`) — an ingested-as-is foreign game there would
+ * otherwise be silently stamped/writable, reopening the never-modify-game-
+ * source rule by location rather than by identity. `nearestManifestExcludesIngestReact`
+ * walks up from a candidate `.tsx`'s own directory to the NEAREST
+ * `vgai.game.json`; if that manifest declares an `{ ingest }` react world,
+ * the whole manifest folder's subtree is excluded — exact, not coarse:
+ * `ingest-react` is single-world by construction (`adapter-resolver.ts`'s
+ * `MULTI_WORLD_ALLOWED_IDENTITIES` exclusion), so "the manifest folder" IS
+ * the foreign game's whole tree, and D-N8 ships no authoring for it anyway —
+ * excluding it from stamping loses nothing. Cached per directory (hit AND
+ * miss, R-Y3) so a project with no manifest anywhere up the tree pays the
+ * walk cost once, ever. Malformed JSON at the manifest path is treated as
+ * "no exclusion" (never crash the transform hook over a broken file); a
+ * genuine fs error OTHER than "not found" (e.g. a permission error) is not
+ * swallowed — it propagates, same honesty bar the rest of this file holds.
+ */
+
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { Plugin } from 'vite';
+import { lineColToOffset, OidStore, transformSource } from './src/ui-source/oid-transform';
+import {
+  deleteElement,
+  deleteElements,
+  duplicateElement,
+  editTextContent,
+  getEditableText,
+  insertChildElement,
+  removeInlineStyle,
+  reorderChild,
+  reparentElement,
+  type StructEditResult,
+  type StyleEditResult,
+  surgicalCssEdit,
+  unwrapElement,
+  wrapElement,
+  writePropChange,
+  writeStyleAuto,
+} from './src/ui-source/writer';
+
+const NODE_MODULES_RE = /\/node_modules\//;
+const TOOLING_SRC_RE = /\/packages\/(engine\/src|create-vgai-project|vgai-cli|editor-sdk)\//;
+const EDITOR_SRC_RE = /\/packages\/editor\/src\//;
+const EDITABLE_COMPONENTS_RE = /\/ui-editor\/editable-components\/.*\.tsx$/;
+/** Track N, D-N4 item 2 — see the module doc comment's "Vendored-tree exclusion". */
+const VENDOR_RE = /\/vendor\//;
+
+/** True if a parsed `vgai.game.json` body declares at least one
+ *  `kind: 'react'` world with an `{ ingest }` adapter (kind-agnostic on
+ *  `strategy` — every ingest-react strategy is D-N8 no-authoring today, and
+ *  a future strategy should not silently reopen the hole). Defensive against
+ *  any shape (never trusts the manifest is even an object) — this is a
+ *  best-effort identity probe for a WRITE-BACK BAN, not manifest validation
+ *  (the real Zod schema/loader is `@engine/manifest/load`, not reachable
+ *  from this vite-config-time, dependency-light file by design). */
+function manifestDeclaresIngestReactWorld(parsed: unknown): boolean {
+  if (!parsed || typeof parsed !== 'object') return false;
+  const worlds = (parsed as { worlds?: unknown }).worlds;
+  if (!Array.isArray(worlds)) return false;
+  return worlds.some((entry) => {
+    if (!entry || typeof entry !== 'object') return false;
+    const world = entry as { kind?: unknown; adapter?: unknown };
+    if (world.kind !== 'react') return false;
+    const { adapter } = world;
+    return !!adapter && typeof adapter === 'object' && 'ingest' in adapter;
+  });
+}
+
+/** Cache: absolute directory -> whether ITS OWN ancestor walk (starting AT
+ *  this directory) hit an ingest-react-declaring manifest. Cached both ways
+ *  (hit and miss, R-Y3) — see the module doc comment's D-Y4 section. */
+const manifestAncestorExclusionCache = new Map<string, boolean>();
+
+function nearestManifestExcludesIngestReact(dir: string): boolean {
+  const cached = manifestAncestorExclusionCache.get(dir);
+  if (cached !== undefined) return cached;
+
+  const manifestPath = join(dir, 'vgai.game.json');
+  let raw: string | undefined;
+  try {
+    raw = readFileSync(manifestPath, 'utf8');
+  } catch (err) {
+    // ENOENT (no manifest at this level) -> keep walking up. Any OTHER fs
+    // error (e.g. EACCES) is a real environment problem, not "no manifest
+    // here" — never silently swallowed.
+    if ((err as NodeJS.ErrnoException)?.code !== 'ENOENT') throw err;
+  }
+
+  let result: boolean;
+  if (raw === undefined) {
+    const parent = dirname(dir);
+    result = parent === dir ? false : nearestManifestExcludesIngestReact(parent);
+  } else {
+    try {
+      result = manifestDeclaresIngestReactWorld(JSON.parse(raw));
+    } catch {
+      // Malformed JSON: honest "no exclusion" (stamping stays on) — never
+      // crash the transform hook over a broken manifest file.
+      result = false;
+    }
+  }
+  manifestAncestorExclusionCache.set(dir, result);
+  return result;
+}
+
+/**
+ * Cap 2 (React visual-edit parity): the scope guard for the `/__ui-source/css` endpoint.
+ * A CSS file path (from a stylesheet's `data-vite-dev-id`) is editable iff it is a
+ * first-party PROJECT `.css` file — same carve-outs as `defaultProjectScopeInclude`
+ * (never node_modules, vendored trees, the vgai tooling/engine source, or the editor's
+ * own source). Paths are normalized to forward slashes so a Windows dev-id matches. This
+ * is the CSS analogue of the `.tsx` stamping scope: an out-of-scope path must not become
+ * writable through a client-supplied `file`.
+ */
+export function isEditableCssFile(id: string): boolean {
+  const clean = (id.split('?')[0] ?? id).replace(/\\/g, '/');
+  if (!clean.endsWith('.css')) return false;
+  if (NODE_MODULES_RE.test(clean)) return false;
+  if (VENDOR_RE.test(clean)) return false;
+  if (TOOLING_SRC_RE.test(clean)) return false;
+  if (EDITOR_SRC_RE.test(clean)) return false;
+  return true;
+}
+
+/** D-1 (Phase D, spec27 §2): sha256 hex digest — the checksum guard the
+ *  `/__ui-source/restore` endpoint (below) uses to refuse a stale write. Only
+ *  ever computed SERVER-SIDE: the client (`ReactWorldAuthoringAdapter`) never
+ *  hashes anything itself, it only echoes back a digest this server already
+ *  handed it in a prior `writeStruct`/`restoreSource` response. */
+function sha256(text: string): string {
+  return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+/** Default `include` predicate (see the module doc comment above for the reasoning). */
+export function defaultProjectScopeInclude(id: string): boolean {
+  if (!id.endsWith('.tsx')) return false;
+  if (NODE_MODULES_RE.test(id)) return false;
+  if (VENDOR_RE.test(id)) return false;
+  if (TOOLING_SRC_RE.test(id)) return false;
+  if (EDITOR_SRC_RE.test(id) && !EDITABLE_COMPONENTS_RE.test(id)) return false;
+  if (nearestManifestExcludesIngestReact(dirname(id))) return false;
+  return true;
+}
+
+/**
+ * D-A3 (wave 13, `docs/WAVE13-JSX-SPREAD-UNDO-DESIGN.md`): route a
+ * `/__ui-source/write` body to the write-or-remove writer call — a `value: null`
+ * body is the REMOVAL sentinel (paired with `SourceWriteBackend.removeStyle`),
+ * routing to `removeInlineStyle`; any other value routes to the normal
+ * write-or-append path (`writeStyleAuto`, unchanged). Exported as a pure function
+ * so this routing decision is unit-testable without spinning up a dev server —
+ * the OID→offset resolution and the actual fs read/write around it stay inline in
+ * the middleware below (real I/O, not worth mocking).
+ */
+export function applyStyleWriteRequest(
+  code: string,
+  elementStart: number,
+  prop: string,
+  value: string | number | null,
+): StyleEditResult & { route?: 'class' | 'inline' } {
+  if (value === null) return removeInlineStyle(code, elementStart, prop);
+  return writeStyleAuto(code, elementStart, prop, value);
+}
+
+/** The JSON response a source-endpoint handler produces (status defaults to 200). */
+export interface HandlerResult {
+  status?: number;
+  body: unknown;
+}
+
+/** POST `/__ui-source/write` — surgical inline-style/className edit (F5 routing).
+ *  D-A3 (wave 13): a `value: null` body is the REMOVAL sentinel — routed via
+ *  `applyStyleWriteRequest` to `removeInlineStyle` (append-aware undo); `appended`
+ *  is forwarded so the client's undo can remove vs. restore. */
+function handleWrite(store: OidStore, body: Record<string, unknown>): HandlerResult {
+  const { oid, prop, value } = body as { oid: string; prop: string; value: string | null };
+  const entry = store.index.get(oid);
+  if (!entry) return { body: { changed: false, error: 'unknown oid' } };
+  const src = readFileSync(entry.file, 'utf8');
+  const off = lineColToOffset(src, entry.line, entry.col);
+  const result = applyStyleWriteRequest(src, off, prop, value);
+  if (result.changed) writeFileSync(entry.file, result.code);
+  return {
+    body: {
+      changed: result.changed,
+      dynamic: result.dynamic,
+      route: result.route,
+      appended: result.appended,
+      file: entry.file,
+    },
+  };
+}
+
+/**
+ * POST `/__ui-source/css` — Cap 2 surgical CSS-FILE edit. The client (adapter) resolves
+ * the target rule from live matched-rule data (`inspect.ts` getMatchedCssRules) and sends
+ * the rule's source file + selector; this edits that file in place. The file path is
+ * client-supplied, so it MUST pass the first-party CSS scope guard before any read/write
+ * — an out-of-scope path is rejected, not touched. A selector not present in source is
+ * generated CSS (`generated: true`); the client re-routes to class/inline.
+ *
+ * Exported (unlike its sibling handlers above, which close over the live
+ * `OidStore`) so it's directly unit-testable without a dev server — it's pure
+ * body-in/HandlerResult-out plus real fs I/O on a client-supplied, scope-
+ * guarded path, no store/session state involved.
+ */
+export function handleCss(body: Record<string, unknown>): HandlerResult {
+  const { file, selector, prop, value } = body as {
+    file: string;
+    selector: string;
+    prop: string;
+    value: string;
+  };
+  if (!file || !isEditableCssFile(file)) {
+    return { body: { changed: false, error: 'css file out of editable scope' } };
+  }
+  const cleanFile = file.split('?')[0] ?? file;
+  const src = readFileSync(cleanFile, 'utf8');
+  const edited = surgicalCssEdit(src, selector, prop, value);
+  if (edited === null) return { body: { changed: false, generated: true, file: cleanFile } };
+  if (edited !== src) writeFileSync(cleanFile, edited);
+  return { body: { changed: edited !== src, file: cleanFile } };
+}
+
+/**
+ * POST `/__ui-source/text` — Cap 3 text-content edit. Replaces a leaf element's pure-text
+ * body in place (guarded: refuses a body with `{expression}` or child elements). Returns
+ * `prevText` (the editable text before the edit) for the client's undo inverse.
+ */
+function handleText(store: OidStore, body: Record<string, unknown>): HandlerResult {
+  const { oid, text } = body as { oid: string; text: string };
+  const entry = store.index.get(oid);
+  if (!entry) return { body: { changed: false, error: 'unknown oid' } };
+  const src = readFileSync(entry.file, 'utf8');
+  const off = lineColToOffset(src, entry.line, entry.col);
+  const prevText = getEditableText(src, off);
+  const result = editTextContent(src, off, text);
+  if (result.changed) writeFileSync(entry.file, result.code);
+  return {
+    body: { changed: result.changed, dynamic: result.dynamic, prevText, file: entry.file },
+  };
+}
+
+/**
+ * POST `/__ui-source/prop` — Cap 4 component prop / attribute edit at the call site. The
+ * client sends the CALL-SITE oid (resolved from the fiber, `inspect.ts` getCallSiteOid)
+ * whose index entry points at the `<Component …>` tag. Guards a dynamic (non-literal) prop
+ * and the event-handler / structural props.
+ */
+function handleProp(store: OidStore, body: Record<string, unknown>): HandlerResult {
+  const { oid, prop, value } = body as { oid: string; prop: string; value: string };
+  const entry = store.index.get(oid);
+  if (!entry) return { body: { changed: false, error: 'unknown oid' } };
+  const src = readFileSync(entry.file, 'utf8');
+  const off = lineColToOffset(src, entry.line, entry.col);
+  const result = writePropChange(src, off, prop, value);
+  if (result.changed) writeFileSync(entry.file, result.code);
+  return { body: { changed: result.changed, dynamic: result.dynamic, file: entry.file } };
+}
+
+/**
+ * POST `/__ui-source/struct` — Cap 5 structural source edits. Ops: `delete`, `duplicate`,
+ * `wrap` (+wrapperTag), `unwrap`, `create` (insert a `<tag/>` child of `oid`), `reorder`
+ * (move `oid` before `targetOid`, or to the end of `parentOid`), and `reparent` (move `oid`
+ * into `parentOid`). Multi-oid ops resolve every oid to an offset in the SAME file (a
+ * cross-file move is refused) — OID-resolved, immune to index races.
+ *
+ * D-1 (Phase D, spec27 §2 "known limitation to schedule, not hide"): when the op actually
+ * changes the file, the response also carries the WHOLE file's `prevSource`/`newSource`
+ * (before/after this write) and their `prevSha`/`newSha` (sha256 digests, computed here —
+ * the client never hashes anything itself). `ReactWorldAuthoringAdapter.structOp` uses
+ * these to push a checksum-guarded whole-file-snapshot undo/redo entry — the sound inverse
+ * for a structural op (a per-OID inverse is unsound: OIDs are content-signature keyed,
+ * reorder/delete reassign occurrence indices, and delete has no inverse payload). Exported
+ * (like `handleCss`) so it's directly unit-testable without a running dev server.
+ */
+export function handleStruct(store: OidStore, body: Record<string, unknown>): HandlerResult {
+  const { oid, op, targetOid, parentOid, wrapperTag } = body as {
+    oid: string;
+    op: string;
+    targetOid?: string;
+    parentOid?: string;
+    wrapperTag?: string;
+  };
+  const entry = store.index.get(oid);
+  if (!entry) return { body: { changed: false, error: 'unknown oid' } };
+  const src = readFileSync(entry.file, 'utf8');
+  const off = lineColToOffset(src, entry.line, entry.col);
+  // Resolve a companion oid to an offset in the SAME file, or null (cross-file ⇒ error).
+  const resolve = (id: string | undefined): number | null | 'cross-file' => {
+    if (!id) return null;
+    const e = store.index.get(id);
+    if (!e) return null;
+    if (e.file !== entry.file) return 'cross-file';
+    return lineColToOffset(src, e.line, e.col);
+  };
+  const target = resolve(targetOid);
+  const parent = resolve(parentOid);
+  if (target === 'cross-file' || parent === 'cross-file') {
+    return { body: { changed: false, error: 'cannot move across files' } };
+  }
+
+  let result: StructEditResult;
+  switch (op) {
+    case 'delete':
+      result = deleteElement(src, off);
+      break;
+    case 'duplicate':
+      result = duplicateElement(src, off);
+      break;
+    case 'wrap':
+      result = wrapElement(src, off, wrapperTag ?? 'div');
+      break;
+    case 'unwrap':
+      result = unwrapElement(src, off);
+      break;
+    case 'create':
+      result = insertChildElement(src, off, wrapperTag ?? 'div');
+      break;
+    case 'reorder':
+      result = reorderChild(src, off, target, parent);
+      break;
+    case 'reparent':
+      result = parent == null ? { code: src, changed: false } : reparentElement(src, off, parent);
+      break;
+    default:
+      return { body: { changed: false, error: `unknown struct op: ${op}` } };
+  }
+  if (!result.changed) return { body: { changed: false, file: entry.file } };
+  const prevSource = src;
+  const newSource = result.code;
+  writeFileSync(entry.file, newSource);
+  return {
+    body: {
+      changed: true,
+      file: entry.file,
+      prevSource,
+      newSource,
+      prevSha: sha256(prevSource),
+      newSha: sha256(newSource),
+    },
+  };
+}
+
+/**
+ * POST `/__ui-source/struct-many` — delete-order-residual fix (bug-panel follow-up
+ * to the multi-delete corruption fix, 50f90a6d). Delete-only (today's one caller,
+ * `ReactWorldAuthoringAdapter.structure.removeMany`): resolves EVERY `oid` in `oids`
+ * to an offset against ONE `readFileSync` snapshot of their (shared) file, then
+ * applies all of them via `deleteElements` (`writer.ts`) — highest offset first, so
+ * no still-queued target's offset is ever shifted out from under it, REGARDLESS of
+ * what order the caller listed `oids` in. This is what makes the batch immune to the
+ * delete-order-residual: `deleteSelection` (`editor-hotkeys.ts`)'s per-id fallback
+ * loop derives its delete order from the CALLER's own hierarchy walk (DOM order for
+ * `ReactWorldAuthoringAdapter` — see `walkOidTree`), which can diverge from true
+ * SOURCE order when a component's live DOM child order is a runtime permutation of
+ * its JSX (e.g. `{[...els].reverse()}`); this endpoint never consults that walk order
+ * at all, only each oid's own registered `{line, col}` and ONE shared file read, so
+ * caller order is irrelevant to correctness. Explicitly NOT a re-scan/re-transform of
+ * the file per oid (see `deleteElements`'s doc comment for why that would be UNSOUND
+ * here — a live re-transform mid-batch reassigns occurrence-index-based oid identity
+ * out from under the very oids this batch is still trying to resolve). One write, one
+ * `prevSource`/`newSource` pair — one undo entry for the whole batch (a bonus over
+ * the N-entry per-id fallback, not the point of this fix, but free from reusing
+ * `pushStructUndo`'s existing whole-file-snapshot inverse unchanged).
+ */
+export function handleStructMany(store: OidStore, body: Record<string, unknown>): HandlerResult {
+  const { oids, op } = body as { oids?: unknown; op?: string };
+  if (op !== 'delete') return { body: { changed: false, error: `unsupported batch op: ${op}` } };
+  if (!Array.isArray(oids) || oids.length === 0) {
+    return { body: { changed: false, error: 'oids must be a non-empty array' } };
+  }
+  const uniqueOids = [...new Set(oids as string[])];
+  const entries = uniqueOids.map((oid) => ({ oid, entry: store.index.get(oid) }));
+  const missing = entries.find((e) => !e.entry);
+  if (missing) return { body: { changed: false, error: `unknown oid: ${missing.oid}` } };
+  const file = entries[0]!.entry!.file;
+  const crossFile = entries.find((e) => e.entry!.file !== file);
+  if (crossFile) return { body: { changed: false, error: 'cannot batch-delete across files' } };
+
+  const src = readFileSync(file, 'utf8'); // ONE snapshot every offset below resolves against
+  const offsets = entries.map((e) => lineColToOffset(src, e.entry!.line, e.entry!.col));
+  const result = deleteElements(src, offsets);
+  if (!result.changed) return { body: { changed: false, file } };
+  const prevSource = src;
+  const newSource = result.code;
+  writeFileSync(file, newSource);
+  return {
+    body: {
+      changed: true,
+      file,
+      prevSource,
+      newSource,
+      prevSha: sha256(prevSource),
+      newSha: sha256(newSource),
+    },
+  };
+}
+
+/**
+ * POST `/__ui-source/restore` — D-1 (Phase D, spec27 §2): the checksum-guarded whole-file
+ * restore that makes Cap-5 structural edits (delete/duplicate/wrap/unwrap/reorder/reparent/
+ * create) undoable. `ReactWorldAuthoringAdapter.structOp` captures `{prevSource, newSource,
+ * prevSha, newSha}` from a struct write's response (`handleStruct`, above) and, on undo/
+ * redo, posts the INVERSE `{file, source, ifMatchSha}` here: undo sends `source: prevSource,
+ * ifMatchSha: newSha` (the hash of what SHOULD be on disk right now); redo sends the mirror
+ * image. Refuses — WITHOUT writing — when the file's CURRENT sha256 doesn't match
+ * `ifMatchSha` (an out-of-band change since: a hand-edit, a since-diverged reload, …);
+ * `restored: false` is the caller's cue to surface a loud refusal instead of silently
+ * corrupting the file. Scope-guarded the same way `handleCss`'s client-supplied `file` is
+ * (`defaultProjectScopeInclude` — restore targets the SAME `.tsx` project files struct ops
+ * do). Exported (like `handleCss`) so it's directly unit-testable without a dev server.
+ */
+export function handleRestore(body: Record<string, unknown>): HandlerResult {
+  const { file, source, ifMatchSha } = body as {
+    file: string;
+    source: string;
+    ifMatchSha: string;
+  };
+  if (!file || !defaultProjectScopeInclude(file)) {
+    return { status: 403, body: { restored: false, error: 'file out of editable scope' } };
+  }
+  let current: string;
+  try {
+    current = readFileSync(file, 'utf8');
+  } catch (e) {
+    return { status: 404, body: { restored: false, error: String(e) } };
+  }
+  const currentSha = sha256(current);
+  if (currentSha !== ifMatchSha) {
+    return {
+      status: 409,
+      body: {
+        restored: false,
+        error: 'stale: the file changed since this undo/redo entry was recorded',
+        sha: currentSha,
+      },
+    };
+  }
+  writeFileSync(file, source);
+  return { body: { restored: true, sha: sha256(source) } };
+}
+
+export function uiOidPlugin(
+  include: RegExp | ((id: string) => boolean) = defaultProjectScopeInclude,
+): Plugin {
+  const test = typeof include === 'function' ? include : (id: string) => include.test(id);
+  const store = new OidStore();
+  return {
+    name: 'vgai-ui-oid',
+    enforce: 'pre',
+    transform(code, id) {
+      const clean = id.split('?')[0] ?? id;
+      if (!test(clean)) return null;
+      const { code: out } = transformSource(code, clean, store);
+      return { code: out, map: null };
+    },
+    configureServer(server) {
+      // The Express host may apply express.json() app-wide, consuming the body and
+      // leaving the parsed object on req.body. Prefer that; else read the raw stream.
+      const readJson = async (
+        req: import('node:http').IncomingMessage,
+      ): Promise<Record<string, unknown>> => {
+        const pre = (req as unknown as { body?: unknown }).body;
+        if (pre && typeof pre === 'object') return pre as Record<string, unknown>;
+        const chunks: Buffer[] = [];
+        for await (const chunk of req) chunks.push(chunk as Buffer);
+        const raw = Buffer.concat(chunks).toString('utf8');
+        return raw ? JSON.parse(raw) : {};
+      };
+      const json = (res: import('node:http').ServerResponse, obj: unknown, code = 200): void => {
+        res.statusCode = code;
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify(obj));
+      };
+      // Single middleware switching on the URL — avoids connect prefix-matching subtleties.
+      // Each POST endpoint delegates to a small module-level handler (below) so this
+      // dispatcher stays flat; the try/catch + JSON plumbing lives here once.
+      const post = async (
+        req: import('node:http').IncomingMessage,
+        res: import('node:http').ServerResponse,
+        handler: (body: Record<string, unknown>) => HandlerResult,
+      ): Promise<void> => {
+        try {
+          const result = handler(await readJson(req));
+          json(res, result.body, result.status ?? 200);
+        } catch (e) {
+          json(res, { changed: false, error: String(e) }, 400);
+        }
+      };
+      // POST route table — keeps the dispatcher flat (one lookup, no per-endpoint branch).
+      const postRoutes: Record<string, (body: Record<string, unknown>) => HandlerResult> = {
+        '/__ui-source/write': (b) => handleWrite(store, b),
+        '/__ui-source/css': handleCss,
+        '/__ui-source/text': (b) => handleText(store, b),
+        '/__ui-source/prop': (b) => handleProp(store, b),
+        '/__ui-source/struct': (b) => handleStruct(store, b),
+        '/__ui-source/struct-many': (b) => handleStructMany(store, b),
+        '/__ui-source/restore': handleRestore,
+      };
+      server.middlewares.use(async (req, res, next) => {
+        const url = (req.url ?? '').split('?')[0] ?? '';
+        if (url === '/__ui-source/index') return json(res, Object.fromEntries(store.index));
+        const handler = req.method === 'POST' ? postRoutes[url] : undefined;
+        if (handler) return post(req, res, handler);
+        next();
+      });
+    },
+  };
+}