@volter/editor-react 0.5.210 → 0.5.212

package/serving/ui-oid-plugin.ts

@@ -1,74 +1,4 @@
-/**
- * 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): 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/game-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 `ReactRootAuthoringAdapter` needs those files instrumented too.
- * `defaultProjectScopeInclude` widens to PROJECT scope, not repo-global: any `.tsx`
- * file outside `node_modules`, EXCEPT the Volter tooling/engine source trees this repo
- * itself is built from (`packages/engine/src`, `packages/create-volter-project`,
- * `packages/volter-cli`, `packages/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 Volter app's OWN react source un-instrumented.
- *
- * Vendored trees: a vendored GAME's source is STAMPED; every other `/vendor/`
- * tree is not. `data-oid` stamping is what makes a `.tsx` file addressable —
- * and, through `/__ui-source/write`, writable — so this predicate is where the
- * question "may a vendored game be authored?" is actually decided.
- *
- * It used to answer no, for every path under a `/vendor/` segment, under the
- * never-modify-vendored-source rule. The owner's code-or-data ruling
- * superseded that rule (ARCHITECTURE-CORE §Editor "Every edit edits the game's
- * own CODE or DATA", §Rules "there is no unwritable base"): ownership decides
- * the RECORDER, not whether the edit may happen. A user's folder records in
- * their git; a repo-vendored copy records in its own `UPSTREAM.lock`, written
- * in the SAME gesture as the file by `server/vendored-lock-recorder.ts` and
- * routed through {@link writeEditableSource} below. `verify-unaltered.mjs`'s
- * bar was never zero diff — it is zero UNRECORDED diff — so it stays green
- * with an authored edit present, as a patch that reverse-applies to upstream.
- *
- * What stays excluded is everything under `/vendor/` that is a DEPENDENCY
- * rather than a game: `packages/threejs-runtime/vendor/realism-effects` (a vendored
- * library) and the import analyzers' `vendor/` API dumps. See
- * {@link VENDORED_GAME_SRC_RE} for the measured characterization behind that
- * split.
- *
- * D-Y4 (wave 2, 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 (`volter-game-editor 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
- * `volter.project.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 (`binding-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.
- */
+/** Vite source authoring for project React components. JSX receives data-oid attributes only in transform output; the source index and write routes apply recorded edits to the project files. Tooling and dependency source stay outside this scope. */
 
 import { createHash } from 'node:crypto';
 import { createRequire } from 'node:module';
@@ -82,7 +12,6 @@ import {
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { Worker } from 'node:worker_threads';
 import type { Plugin, ViteDevServer } from 'vite';
-import { resolveManifestPath } from '@volter/project/manifest/locate';
 import {
   type ProjectServingServices,
   SOURCE_WRITE_ROUTES_PLUGIN,
@@ -94,7 +23,6 @@ import {
   type OidEntry,
   OidStore,
   oidAttributeForSurface,
-  type R3fComponentContract,
   transformSource,
 } from '../src/source/oid-transform';
 import { planDeleteStory, planRenameStory, planSaveStory } from '../src/source/plan-csf-story';
@@ -107,15 +35,6 @@ import {
   planSourceEdit,
   sourceEditFiles,
 } from '../src/source/plan-source-edit';
-import {
-  type EntryDiagnosticSelector,
-  fileDiagnosticJoin,
-} from '../src/source/r3f-diagnostic-index';
-import {
-  importedR3fContracts,
-  r3fAuthoringDiagnostics,
-  visibleR3fContracts,
-} from '../src/source/r3f-project-contracts';
 import type { SourceEditRequest } from '../src/source/source-edit-request';
 import {
   detectUtilityClassSupport,
@@ -127,11 +46,8 @@ import {
   addClassNameToken,
   collectLiteralInlineStyles,
   cssCamelToKebab,
-  deleteElements,
   editTextContent,
   findTagEnd,
-  getEditableText,
-  groupSiblingElements,
   removeClassNameToken,
   removeInlineStyle,
   removePropAttribute,
@@ -140,14 +56,8 @@ import {
   writePropChange,
 } from '../src/source/writer';
 
-// `applyStyleWriteRequest` and `oidAttributeForSurface` live in browser-safe
-// modules (`plan-source-edit.ts` / `oid-transform.ts`), because a PAGE reaches
-// the same transform; re-exported here so this file stays the stable import
-// site for both.
-export { applyStyleWriteRequest, oidAttributeForSurface };
-
 const NODE_MODULES_RE = /\/node_modules\//;
-const TOOLING_SRC_RE = /\/packages\/(engine\/src|create-volter-project|volter-cli)\//;
+const TOOLING_SRC_RE = /\/packages\/(blender-engine|cyclotron|live|play|project)\/(src|node)\//;
 /** The SDK's own folder, where a workspace keeps its source: tooling, never a game's UI. Named by
  *  where `@volter/sdk` resolves from here (its entry module is `src/index.ts`), with forward
  *  slashes; `null` when it does not resolve. A project's own `packages/sdk` is not this folder. */
@@ -171,101 +81,22 @@ const foldCase = (file: string): string => (process.platform === 'win32' ? file.
 function isToolingSource(clean: string): boolean {
   return TOOLING_SRC_RE.test(clean) || (SDK_ROOT !== null && foldCase(clean).startsWith(foldCase(SDK_ROOT)));
 }
-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 EDITOR_SRC_RE = /\/packages\/editor-(core|blender|threejs|react|ui)\/(src|contributions)\//;
+/** Dependency source inside vendor trees is excluded from authoring. */
 const VENDOR_RE = /\/vendor\//;
-/**
- * A vendored GAME's own source (`…/vendor/games/<id>/…`) — the ONE tree under
- * a `/vendor/` segment that is a game rather than a dependency.
- *
- * The distinction is what {@link defaultProjectScopeInclude} needs and the
- * blanket `VENDOR_RE` could not express. Characterized before it was carved,
- * because "what else does this regex protect?" is the question a scope change
- * has to answer: under every `/vendor/` root in this repo, the only `.tsx` at
- * all is `vendor/games/racing-game`'s 35 files. The rest is
- * `packages/threejs-runtime/vendor/realism-effects` (a vendored LIBRARY — built `dist`
- * JS and shaders, a dependency we happen to ship in-tree) and the two import
- * analyzers' `vendor/` API dumps (`packages/gd-analyze`,
- * `packages/rbx-analyze` — JSON only). None of those is a game, none is
- * authorable, and all of them stay excluded here.
- *
- * The Godot lane is ARCHIVED off main — `git fetch origin archive/godot-lane`, tag `archive/godot-lane-2026-09-19`.
- */
+/** Project game source may be authored inside a vendor tree; dependency source is excluded. */
 const VENDORED_GAME_SRC_RE = /\/vendor\/games\/[^/]+\//;
 
-/** True if a parsed `volter.project.json` body declares at least one
- *  React root with an `{ ingest }` adapter — the `{ ingest }` shape alone is
- *  the answer, because every ingest-react root is D-N8 no-authoring.
- *  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 `@volter/project/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 roots = (parsed as { roots?: unknown }).roots;
-  if (!Array.isArray(roots)) return false;
-  return roots.some((entry) => {
-    if (!entry || typeof entry !== 'object') return false;
-    const root = entry as { adapter?: unknown };
-    const { adapter } = root;
-    return (
-      !!adapter &&
-      typeof adapter === 'object' &&
-      (adapter as { surface?: unknown }).surface === 'dom' &&
-      '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 = resolveManifestPath(dir);
-  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.
+ * 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 Volter tooling/engine source, or the editor's
- * own source). Paths are normalized to forward slashes so a Windows dev-id matches. This
+ * first-party PROJECT `.css` file outside node_modules, every vendor tree, the Volter
+ * tooling/engine source and the editor's own source. JSX stamping separately permits project
+ * game source in vendor trees. 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 {
+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;
@@ -275,11 +106,7 @@ export function isEditableCssFile(id: string): boolean {
   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 (`ReactRootAuthoringAdapter`) never
- *  hashes anything itself, it only echoes back a digest this server already
- *  handed it in a prior `writeStruct`/`restoreSource` response. */
+/** Server-computed SHA-256 for guarded whole-file source writes. */
 function sha256(text: string): string {
   return createHash('sha256').update(text, 'utf8').digest('hex');
 }
@@ -294,17 +121,9 @@ function sourceResourcePath(file: string, projectRoot: string): string {
   return `.volter/external-source/${identity}/${basename(file)}`;
 }
 
-/**
- * Utility-class support is a property of the PACKAGE that owns the edited file,
- * not of the editor session — an ingested game's HUD lives in the game's own
- * tree, with its own `package.json` and its own build, and it is THAT build
- * that would have to compile a `bg-[#059669]`. So the probe walks up from the
- * file to the nearest enclosing `package.json` (falling back to the served
- * project root) and reads the evidence `utility-class-support.ts` names.
- *
- * Cached per resolved package directory, like `propResolvers` above: the walk
- * and the reads happen once per package per dev-server lifetime.
- */
+/** Cache utility-class evidence by the package owning the edited file. The
+ * nearest package.json, or the served project root, determines which build
+ * must compile its authored classes. */
 const utilityClassSupport = new Map<string, UtilityClassSupport>();
 
 /** The nearest ancestor of `file` holding a `package.json`, else `fallback`. */
@@ -383,109 +202,28 @@ function declaredPropsOf(
   return propsByTag.get(key);
 }
 
-/** Everything one project file contributes to an index read, resolved from its
- *  CURRENT bytes exactly once per read. */
-interface IndexFileAnalysis {
-  /** Component contracts visible in this module — `null` for a file this
-   *  server does not stamp as R3F (or could not read). */
-  readonly contracts: ReadonlyMap<string, R3fComponentContract> | null;
-  /** H5 — which of this file's authorability diagnostics pertain to a given
-   *  entry of this file. Inert for a non-R3F/unreadable file. */
-  readonly selectDiagnostics: EntryDiagnosticSelector;
-}
-
-const INERT_FILE_ANALYSIS: IndexFileAnalysis = {
-  contracts: null,
-  selectDiagnostics: () => undefined,
-};
-
-/** The index grouped by file, each bucket keyed by oid — the shape
- *  `fileDiagnosticJoin` needs so an entry's `parentOid` resolves. */
-function indexEntriesByFile(store: OidStore): Map<string, Map<string, OidEntry>> {
-  const byFile = new Map<string, Map<string, OidEntry>>();
-  for (const [oid, entry] of store.index) {
-    const bucket = byFile.get(entry.file);
-    if (bucket) bucket.set(oid, entry);
-    else byFile.set(entry.file, new Map([[oid, entry]]));
-  }
-  return byFile;
-}
-
-/**
- * Read one file's current bytes and derive everything an index read wants from
- * it. Unreadable (deleted/renamed since it was transformed) or not stamped as
- * R3F ⇒ the inert analysis: its entries ship exactly as recorded, which is a
- * degradation, never a failure of the whole index read.
- *
- * COST, and why it went DOWN rather than up when H5 landed: this runs at most
- * once per file per index read (the caller memoizes), whereas the previous
- * shape re-read and re-surface-resolved a file for EVERY capitalized-tag entry
- * whose surface turned out not to be `userData-oid`. H5 adds one
- * `r3fAuthoringDiagnostics` pass per R3F file — the same order of work as the
- * `visibleR3fContracts` pass beside it, and it early-returns for any file
- * without an R3F reconciler import.
- */
-function analyzeIndexFile(
-  file: string,
-  fileEntries: ReadonlyMap<string, OidEntry>,
-  moduleGraph: unknown,
-): IndexFileAnalysis {
+/** Whether the current source belongs to a stage region. Unreadable files
+ * keep their recorded index entries without declared-prop enrichment. */
+function isStageIndexFile(file: string, moduleGraph: unknown): boolean {
   let source: string;
   try {
     source = readFileSync(file, 'utf8');
   } catch {
-    return INERT_FILE_ANALYSIS;
-  }
-  // The SAME decision the transform hook stamped with (task #45) — not a
-  // second derivation that could disagree with it.
-  if (serving().surfaceOf(file, source, moduleGraph).attribute !== 'userData-oid') {
-    return INERT_FILE_ANALYSIS;
+    return false;
   }
-  return {
-    contracts: visibleR3fContracts(source, file),
-    // The surface check above already established this file renders through
-    // the R3F reconciler, which is a stronger answer than the source-text
-    // sniff the analyzer falls back on — and the one a project that imports
-    // its prop shape from a shared module can actually pass.
-    selectDiagnostics: fileDiagnosticJoin(
-      fileEntries,
-      r3fAuthoringDiagnostics(source, file, { knownThreeSurface: true }),
-    ),
-  };
+  return oidAttributeForSurface(serving().surfaceOf(file, source, moduleGraph).surface) === 'userData-oid';
 }
 
-/**
- * One recorded entry plus everything the current bytes add to it: its
- * component's authoring contract, its declared props, and (H5) the
- * authorability diagnostics that pertain to it. Returns the entry ITSELF when
- * there is nothing to add, so an unenriched index read allocates nothing.
- *
- * Note that the diagnostic lookup runs for EVERY entry, including a lowercase
- * host tag: R3F002/3/5 are ABOUT a component definition, and a definition's
- * root is usually an ordinary `<group>`/`<mesh>` — that entry is precisely the
- * one an instance row reaches through its boundary object's own `userData.oid`.
- */
+/** Add declared props to a source index entry when the resolver has them. */
 function enrichIndexEntry(
   entry: OidEntry,
-  analysis: IndexFileAnalysis,
+  stage: boolean,
   propsByTag: ReadonlyMap<string, ComponentPropSpec[]>,
 ): OidEntry {
-  const diagnostics = analysis.selectDiagnostics(entry);
-  const custom = analysis.contracts !== null && /^[A-Z]/.test(entry.tag);
-  const contract = custom ? analysis.contracts?.get(entry.tag) : undefined;
+  const custom = stage && /^[A-Z]/.test(entry.tag);
   const props = custom ? declaredPropsOf(propsByTag, entry.file, entry.tag) : undefined;
-  // `props !== undefined` means the resolver ANSWERED for this tag — an empty
-  // answer included. The flag is what lets the inspector's fallback tell a
-  // pending cold resolver from a genuine absence (see OidEntry.propsResolved).
-  const propsResolved = props !== undefined;
-  if (!contract && !props?.length && !diagnostics && !propsResolved) return entry;
-  return {
-    ...entry,
-    ...(contract ? { r3fAuthoring: contract } : {}),
-    ...(props?.length ? { props } : {}),
-    ...(propsResolved ? { propsResolved: true as const } : {}),
-    ...(diagnostics ? { diagnostics } : {}),
-  };
+  if (!props?.length) return entry;
+  return { ...entry, props };
 }
 
 function snapshotRawOidIndex(store: OidStore): Record<string, unknown> {
@@ -496,38 +234,31 @@ function snapshotRawOidIndex(store: OidStore): Record<string, unknown> {
 
 function buildEnrichedOidIndex(
   store: OidStore,
-  devServer?: ViteDevServer,
+  devServer: ViteDevServer,
   propsByTag: ReadonlyMap<string, ComponentPropSpec[]> = new Map(),
 ): Record<string, unknown> {
-  const moduleGraph = devServer?.moduleGraph;
-  const entriesByFile = indexEntriesByFile(store);
-
-  const analyses = new Map<string, IndexFileAnalysis>();
-  const analysisFor = (file: string): IndexFileAnalysis => {
-    const cached = analyses.get(file);
-    if (cached) return cached;
-    const analysis = analyzeIndexFile(file, entriesByFile.get(file) ?? new Map(), moduleGraph);
-    analyses.set(file, analysis);
-    return analysis;
+  const moduleGraph = devServer.moduleGraph;
+
+  const stageFiles = new Map<string, boolean>();
+  const stageFor = (file: string): boolean => {
+    const cached = stageFiles.get(file);
+    if (cached !== undefined) return cached;
+    const stage = isStageIndexFile(file, moduleGraph);
+    stageFiles.set(file, stage);
+    return stage;
   };
 
   const current: Record<string, unknown> = {};
   for (const [oid, entry] of store.index) {
-    current[oid] = enrichIndexEntry(entry, analysisFor(entry.file), propsByTag);
+    current[oid] = enrichIndexEntry(entry, stageFor(entry.file), propsByTag);
   }
   return current;
 }
 
-/**
- * Props/tag/diagnostic enrich is the measured 2.6 s cold cost (repeat 391 ms)
- * of first design attach: `ComponentPropResolver` builds a `ts.Program`. The Scene
- * can render without it — oids, file/line, and tags are already on the raw
- * stamp. Blocking GET /__ui-source/index on enrich froze the Vite thread
- * (and every module load) for those seconds. Serve enrichment only for an
- * unchanged source index; otherwise serve current stamps while it refreshes.
- */
+/** Resolve declared props outside the index request. Return current raw
+ * stamps while enrichment runs; cached enrichment must match the source index. */
 let lastEnrichedIndex: {
-  root: string | undefined;
+  root: string;
   sourceIndex: ReadonlyMap<string, OidEntry>;
   index: Record<string, unknown>;
 } | null = null;
@@ -543,7 +274,7 @@ const pendingPropRequests = new Map<
 >();
 
 function componentPropWorkerUrl(): URL {
-  // The serving module runs built (`dist-node/serving.mjs`), beside the worker built with it.
+  // The serving module runs built, beside the worker built with it.
   return new URL('./component-prop-worker.mjs', import.meta.url);
 }
 
@@ -557,16 +288,15 @@ function declaredPropWorker(): Worker {
   const worker = new Worker(componentPropWorkerUrl(), { name: 'volter-component-props' });
   worker.on(
     'message',
-    (message: { id?: unknown; props?: Record<string, ComponentPropSpec[]>; error?: unknown }) => {
-      if (typeof message.id !== 'number') return;
+    (message: { id: number; props: Record<string, ComponentPropSpec[]> } | { id: number; error: string }) => {
       const pending = pendingPropRequests.get(message.id);
       if (!pending) return;
       pendingPropRequests.delete(message.id);
-      if (typeof message.error === 'string') {
+      if ('error' in message) {
         pending.reject(new Error(message.error));
         return;
       }
-      pending.resolve(new Map(Object.entries(message.props ?? {})));
+      pending.resolve(new Map(Object.entries(message.props)));
     },
   );
   worker.on('error', (error: unknown) => {
@@ -596,10 +326,10 @@ function propRequestsFor(store: OidStore): Array<{ key: string; file: string; ta
 }
 
 function resolveDeclaredProps(
-  projectRoot: string | undefined,
+  projectRoot: string,
   requests: Array<{ key: string; file: string; tag: string; definition?: true }>,
 ): Promise<ReadonlyMap<string, ComponentPropSpec[]>> {
-  if (!projectRoot || requests.length === 0) {
+  if (requests.length === 0) {
     return new Promise((resolveRequest) => setImmediate(() => resolveRequest(new Map())));
   }
   const id = ++propRequestId;
@@ -611,8 +341,8 @@ function resolveDeclaredProps(
 
 function scheduleOidIndexEnrich(
   store: OidStore,
-  projectRoot?: string,
-  devServer?: ViteDevServer,
+  projectRoot: string,
+  devServer: ViteDevServer,
 ): void {
   if (enrichQueued) return;
   enrichQueued = true;
@@ -627,9 +357,7 @@ function scheduleOidIndexEnrich(
       };
     })
     .catch((error) => {
-      // A failed semantic resolver never removes source authoring. Contracts
-      // and diagnostics still enrich on the server thread; declared props
-      // degrade to the attributes physically present in source.
+      // Keep source-attribute inspection available when semantic props fail.
       process.stderr.write(
         `[ui-oid] Declared-prop analysis unavailable; using source attributes: ${String(error)}\n`,
       );
@@ -646,8 +374,8 @@ function scheduleOidIndexEnrich(
 
 function currentOidIndex(
   store: OidStore,
-  projectRoot?: string,
-  devServer?: ViteDevServer,
+  projectRoot: string,
+  devServer: ViteDevServer,
 ): Record<string, unknown> {
   scheduleOidIndexEnrich(store, projectRoot, devServer);
   const cached = lastEnrichedIndex;
@@ -664,58 +392,6 @@ function currentOidIndex(
   return snapshotRawOidIndex(store);
 }
 
-/** Test-only: wait for the in-flight background enrich, if any. */
-export function __flushOidIndexEnrichForTest(): Promise<void> {
-  return new Promise((resolve) => {
-    const finish = (): void => {
-      if (!enrichQueued) {
-        resolve();
-        return;
-      }
-      setImmediate(finish);
-    };
-    setImmediate(finish);
-  });
-}
-
-/** Test-only reset. */
-export function __resetOidIndexEnrichForTest(): void {
-  lastEnrichedIndex = null;
-  enrichQueued = false;
-  if (propWorker) {
-    void propWorker.terminate();
-    propWorker = null;
-  }
-  rejectPendingPropRequests(new Error('Declared-prop worker reset.'));
-}
-
-/** Test-only: whether the last GET returned without waiting for enrich. */
-export function __oidIndexEnrichStateForTest(): { queued: boolean; hasEnriched: boolean } {
-  return { queued: enrichQueued, hasEnriched: lastEnrichedIndex !== null };
-}
-
-/**
- * THE write point for every `/__ui-source/*` handler — and the reason a
- * vendored game's source can be stamped without reopening silent drift.
- *
- * A source write lands in one of two recorders, decided by WHERE the file is,
- * never by what the handler was doing:
- *
- *  - inside a repo-vendored game → `writeRecordedVendoredFile`, which moves the
- *    file AND its `UPSTREAM.lock` entry as ONE journalled operation, so
- *    `verify-unaltered.mjs` is green with the edit present (the edit becomes a
- *    recorded patch that reverse-applies to upstream). Undo needs no special
- *    case: it comes back through here with the previous bytes, the lock
- *    reconciles from the bytes alone, and the edit that restores upstream's own
- *    content deletes the patch entry again.
- *  - anywhere else → the plain `writeFileSync` this file always did, because a
- *    user's own project records in the user's own git.
- *
- * Centralised deliberately. Nine handlers in this file write source; routing
- * per-handler would mean nine chances to add a tenth that forgets, and a
- * forgotten one is not a visible bug — it is a vendored tree that quietly
- * stops matching its lock.
- */
 /** The kit's server capabilities this plugin was constructed with
  *  (`@volter/sdk/session/project-serving`). */
 let servingServices: ProjectServingServices | null = null;
@@ -725,46 +401,29 @@ function serving(): ProjectServingServices {
   return servingServices;
 }
 
-/**
- * THE read point for every `/__ui-source/*` handler: a crashed vendored write is rolled forward
- * before its file is read, so no handler plans against bytes the recorder is about to replace.
- * Welded to the read, the way the recorder is welded to the write, so no handler can forget it.
- */
-function readSettledSource(file: string): string {
-  serving().settleSource(file);
+/** THE read point for every `/__ui-source/*` handler. */
+function readSource(file: string): string {
   return readFileSync(file, 'utf8');
 }
 
 /**
- * THE write point for every `/__ui-source/*` handler: the kit's own write (a vendored file is
- * recorded against its lock, and the served modules it replaces are invalidated, so the next
- * mount reads the new bytes rather than a transform the dev server still holds).
+ * THE write point for every `/__ui-source/*` handler: the kit's own write (the served modules
+ * it replaces are invalidated, so the next mount reads the new bytes rather than a transform
+ * the dev server still holds).
  */
 function writeEditableSource(file: string, code: string): void {
   serving().writeSource(file, code);
 }
 
-/** Default `include` predicate (see the module doc comment above for the reasoning). */
-export function defaultProjectScopeInclude(id: string): boolean {
+/** Project source scope for JSX stamping. */
+function defaultProjectScopeInclude(id: string): boolean {
   const clean = (id.split('?')[0] ?? id).replace(/\\/g, '/');
   if (!clean.endsWith('.tsx')) return false;
   if (NODE_MODULES_RE.test(clean)) return false;
-  // A vendored GAME's source IS stamped; every other `/vendor/` tree is not.
-  // The old blanket exclusion was written under the never-modify-vendored-
-  // source rule, which the owner's code-or-data ruling superseded
-  // (ARCHITECTURE-CORE §Editor "Every edit edits the game's own CODE or DATA",
-  // §Rules "there is no unwritable base"): ownership no longer decides WHETHER
-  // an edit may be written, only WHO RECORDS it. For a repo-vendored copy the
-  // recorder is its own `UPSTREAM.lock`, written in the same gesture as the
-  // file (`server/vendored-lock-recorder.ts`), so the zero-UNRECORDED-diff bar
-  // holds WITH the edit present rather than by forbidding the edit. Stamping is
-  // what makes the game's own TSX literals addressable by the gizmo and the
-  // inspector; refusing it here is what used to make a vendored game
-  // permanently unauthorable.
+  // A vendored project records edits with its own source; dependencies remain excluded.
   if (VENDOR_RE.test(clean) && !VENDORED_GAME_SRC_RE.test(clean)) return false;
   if (isToolingSource(clean)) return false;
-  if (EDITOR_SRC_RE.test(clean) && !EDITABLE_COMPONENTS_RE.test(clean)) return false;
-  if (nearestManifestExcludesIngestReact(dirname(clean))) return false;
+  if (EDITOR_SRC_RE.test(clean)) return false;
   return true;
 }
 
@@ -775,13 +434,12 @@ function resolveEditableSourceFile(id: string, projectRoot: string): string | nu
 
   // Whole-file transactions also serve project-owned model source. This is
   // deliberately narrower than a general project-file API: TypeScript below
-  // this project's src/ tree, never vendored or an ingest-react identity.
+  // this project's src/ tree, with vendored dependencies excluded.
   const projectPath = relative(projectRoot, candidate).replace(/\\/g, '/');
   if (
     projectPath.startsWith('src/') &&
     (projectPath.endsWith('.ts') || projectPath.endsWith('.tsx')) &&
-    !VENDOR_RE.test(candidate) &&
-    !nearestManifestExcludesIngestReact(dirname(candidate))
+    !VENDOR_RE.test(candidate)
   ) {
     return candidate;
   }
@@ -806,7 +464,7 @@ function isCanonicalProjectSourcePath(projectRoot: string, file: string): boolea
 }
 
 /** The JSON response a source-endpoint handler produces (status defaults to 200). */
-export interface HandlerResult {
+interface HandlerResult {
   status?: number;
   body: unknown;
 }
@@ -837,20 +495,12 @@ function preparedSource(
   };
 }
 
-/**
- * Pure source edit preparation: computes exact bytes and hashes, never writes.
- *
- * The edit itself is planned by the tier-agnostic `planSourceEdit`
- * (`src/ui-source/plan-source-edit.ts`) — this handler only supplies what is
- * genuinely server-side: the `node:fs` reads, the css scope guard, sha256, and
- * the project-relative resource path. The hosted browser backend supplies its
- * own equivalents around the SAME planner, which is what keeps the two tiers
- * from drifting into different edit semantics.
- */
-export function handlePrepare(
+/** Prepare source bytes and hashes with ../src/source/plan-source-edit.ts.
+ * This handler owns file reads, CSS scope validation and project resource paths. */
+function handlePrepare(
   store: OidStore,
   body: Record<string, unknown>,
-  projectRoot = process.cwd(),
+  projectRoot: string,
 ): HandlerResult {
   const request = body as unknown as SourceEditRequest;
   if (request.kind === 'css' && (!request.file || !isEditableCssFile(request.file))) {
@@ -863,7 +513,7 @@ export function handlePrepare(
   const sources = new Map<string, string>();
   const files = sourceEditFiles(request, resolveOid);
   for (const file of files) {
-    sources.set(file, readSettledSource(file));
+    sources.set(file, readSource(file));
   }
   // The class-vs-inline gate is a question about the EDITED FILE's own project,
   // so it is answered here (the tier that has `node:fs`) and handed to the pure
@@ -878,16 +528,16 @@ export function handlePrepare(
   return preparedSource(plan.file, plan.prevSource, plan.newSource, plan.result, projectRoot);
 }
 
-export function handleSourceRead(
+function handleSourceRead(
   body: Record<string, unknown>,
-  projectRoot = process.cwd(),
+  projectRoot: string,
 ): HandlerResult {
   const file = body['file'];
   const resolved = typeof file === 'string' ? resolveEditableSourceFile(file, projectRoot) : null;
   if (!resolved) {
     return { status: 403, body: { error: 'file out of editable scope' } };
   }
-  const source = readSettledSource(resolved);
+  const source = readSource(resolved);
   return {
     body: {
       source,
@@ -897,9 +547,9 @@ export function handleSourceRead(
   };
 }
 
-export function handleSourceApply(
+function handleSourceApply(
   body: Record<string, unknown>,
-  projectRoot = process.cwd(),
+  projectRoot: string,
 ): HandlerResult {
   const restored = handleRestore(body, projectRoot);
   const value = restored.body as { restored: boolean; sha?: string; error?: string };
@@ -909,14 +559,11 @@ export function handleSourceApply(
   };
 }
 
-/** 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. */
+/** Surgical style/className write. A null value removes an inline property. */
 function handleWrite(
   store: OidStore,
   body: Record<string, unknown>,
-  projectRoot = process.cwd(),
+  projectRoot: string,
 ): HandlerResult {
   // A numeric `value` stays a NUMBER all the way to the writer — the JSX then
   // carries a bare `12` (React px-ifies it) instead of `'12'`, which React
@@ -928,7 +575,7 @@ function handleWrite(
   };
   const entry = store.index.get(oid);
   if (!entry) return { body: { changed: false, error: 'unknown oid' } };
-  const src = readSettledSource(entry.file);
+  const src = readSource(entry.file);
   const off = lineColToOffset(src, entry.line, entry.col);
   const result = applyStyleWriteRequest(
     src,
@@ -943,7 +590,6 @@ function handleWrite(
       changed: result.changed,
       dynamic: result.dynamic,
       route: result.route,
-      appended: result.appended,
       ...(result.tokenRef ? { tokenRef: result.tokenRef } : {}),
       ...(result.error ? { error: result.error } : {}),
       file: entry.file,
@@ -951,20 +597,9 @@ function handleWrite(
   };
 }
 
-/**
- * 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(
+/** Edit a client-selected first-party CSS rule after the scope guard.
+ * Selectors absent from source report generated CSS for caller rerouting. */
+function handleCss(
   body: Record<string, unknown>,
 ): HandlerResult {
   const { file, selector, prop, value, media } = body as {
@@ -978,7 +613,7 @@ export function handleCss(
     return { body: { changed: false, error: 'css file out of editable scope' } };
   }
   const cleanFile = file.split('?')[0] ?? file;
-  const src = readSettledSource(cleanFile);
+  const src = readSource(cleanFile);
   // `media` scopes the edit to a breakpoint: the rule inside `@media <media>`
   // (block and rule both created on demand — a breakpoint's first edit IS
   // what mints it). The base-path `generated` probe does not apply: the
@@ -993,9 +628,8 @@ export function handleCss(
 }
 
 /**
- * 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.
+ * POST `/__ui-source/text` — text-content edit. Replaces a leaf element's pure-text
+ * body in place, refusing a body with expressions or child elements.
  */
 function handleText(
   store: OidStore,
@@ -1004,18 +638,17 @@ function handleText(
   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 = readSettledSource(entry.file);
+  const src = readSource(entry.file);
   const off = lineColToOffset(src, entry.line, entry.col);
-  const prevText = getEditableText(src, off);
   const result = editTextContent(src, off, text);
   if (result.changed) writeEditableSource(entry.file, result.code);
   return {
-    body: { changed: result.changed, dynamic: result.dynamic, prevText, file: entry.file },
+    body: { changed: result.changed, dynamic: result.dynamic, file: entry.file },
   };
 }
 
 /**
- * POST `/__ui-source/prop` — Cap 4 component prop / attribute edit at the call site. The
+ * POST `/__ui-source/prop` — 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.
@@ -1027,7 +660,7 @@ function handleProp(
   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 = readSettledSource(entry.file);
+  const src = readSource(entry.file);
   const off = lineColToOffset(src, entry.line, entry.col);
   // A dotted prop is one member of an object-literal prop (`params.threshold`): the index names
   // members that way (`authoredProps`), and the member writer rewrites that literal alone.
@@ -1036,9 +669,7 @@ function handleProp(
     if (member.changed) writeEditableSource(entry.file, member.code);
     return { body: { changed: member.changed, dynamic: member.dynamic, file: entry.file } };
   }
-  // `value: null` is the REMOVAL sentinel, the same shape `/__ui-source/write`
-  // uses for `removeStyle` (D-A3). Removing a prop attribute is how the
-  // inspector reverts a prop to the component's declared default.
+  // A null value removes the prop so its component default can take effect.
   if (value === null) {
     const removed = removePropAttribute(src, off, prop);
     if (removed.changed) writeEditableSource(entry.file, removed.code);
@@ -1046,53 +677,39 @@ function handleProp(
   }
   const result = writePropChange(src, off, prop, value, {
     addIfMissing: body['addIfMissing'] === true,
-    // R2: opt-in scalar→tuple shape
-    // upgrade — see writePropChange's own doc comment. Absent/false on every
-    // pre-existing caller, so react-dom prop writes are byte-identical.
+    // Forward explicit scalar-to-tuple permission to the source writer.
     allowShapeUpgrade: body['allowShapeUpgrade'] === true,
   });
   if (result.changed) writeEditableSource(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`),
- * `create-sibling` (insert the `snippet` immediately AFTER `oid` — how a top-level element
- * is added to a world whose root JSX is an OID-less fragment), `reorder`
- * (move `oid` before `targetOid`, or to the end of `parentOid`), and `reparent` (move `oid`
- * into `parentOid`). An insert may carry `ensureImport` when its snippet names a component.
- * 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). `ReactRootAuthoringAdapter.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.
- *
- * The op switch itself lives in `planSourceEdit` and NOWHERE else. It used to be written
- * out a second time here, and the two copies drifted the moment `reparent` grew rules of
- * its own (R1–R4): one caller routed through the planner and got them, this
- * one did not. Everything that remains below is what is genuinely server-side — the
- * `node:fs` read/write, sha256, and the response envelope.
- */
-export function handleStruct(
+/** Plan a structural source edit, then apply its complete next-file bytes.
+ * The response includes before/after source and SHA values for guarded history.
+ * Scope, transform, and destination rules live in the shared source planner. */
+function handleStruct(
   store: OidStore,
   body: Record<string, unknown>,
+  kind: 'struct' | 'struct-many',
 ): HandlerResult {
-  const { oid, op } = body as { oid?: unknown; op?: unknown };
-  if (typeof oid !== 'string' || typeof op !== 'string') {
-    return { body: { changed: false, error: 'struct requests need an oid and an op' } };
+  const { oid, oids, op } = body;
+  if (kind === 'struct') {
+    if (typeof oid !== 'string' || typeof op !== 'string') {
+      return { body: { changed: false, error: 'struct requests need an oid and an op' } };
+    }
+  } else {
+    if (op !== 'delete' && op !== 'group') {
+      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 request = { ...body, kind: 'struct', oid, op } as unknown as SourceEditRequest;
+  const request = { ...body, kind } as unknown as SourceEditRequest;
   const resolveOid = (id: string): OidEntry | undefined => store.index.get(id);
   const sources = new Map<string, string>();
   for (const file of sourceEditFiles(request, resolveOid)) {
-    sources.set(file, readSettledSource(file));
+    sources.set(file, readSource(file));
   }
   const plan = planSourceEdit(request, sources, resolveOid);
   if (plan.file === null) return { body: { changed: false, ...plan.result } };
@@ -1112,96 +729,13 @@ export function handleStruct(
   };
 }
 
-/**
- * POST `/__ui-source/struct-many` — one source snapshot and one history boundary
- * for structural operations involving several OIDs. `group` wraps source siblings
- * beneath an ordinary R3F group. `delete` retains the delete-order-residual fix
- * (50f90a6d): it resolves EVERY `oid` in `oids` to an offset against ONE shared
- * `readFileSync` snapshot, then applies 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
- * `ReactRootAuthoringAdapter` — 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(
+/** Plan a component fork, collision-check the new file, and write it.
+ * Return the callsite edit unwritten for project history; undo retains the
+ * new module and restores the previous callsite. */
+function handleForkComponent(
   store: OidStore,
   body: Record<string, unknown>,
-): HandlerResult {
-  const { oids, op, wrapperTag } = body as {
-    oids?: unknown;
-    op?: string;
-    wrapperTag?: string;
-  };
-  if (op !== 'delete' && op !== 'group') {
-    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-edit across files' } };
-
-  const src = readSettledSource(file); // ONE snapshot every offset below resolves against
-  const offsets = entries.map((e) => lineColToOffset(src, e.entry!.line, e.entry!.col));
-  const result =
-    op === 'group' ? groupSiblingElements(src, offsets, wrapperTag) : deleteElements(src, offsets);
-  if (!result.changed) return { body: { changed: false, file } };
-  const prevSource = src;
-  const newSource = result.code;
-  writeEditableSource(file, newSource);
-  return {
-    body: {
-      changed: true,
-      file,
-      prevSource,
-      newSource,
-      prevSha: sha256(prevSource),
-      newSha: sha256(newSource),
-    },
-  };
-}
-
-/**
- * POST `/__ui-source/fork-component` — H7 "Fork Component…" (wave 6).
- *
- * The ONE thing this endpoint does that the client cannot: create a file. Every
- * other `/__ui-source/*` write targets a file the OID index already knows, and
- * the whole-file `apply`/`restore` pair is checksum-guarded against a file that
- * exists — there is no create path through the client write seam at all. So the
- * new module is written HERE with `node:fs`, and the CALLSITE edit is handed
- * back to the client unwritten, so it can go through project history like every
- * other source write (the fork is undoable at the callsite; the new file, being
- * outside history, survives an undo as an inert module nothing imports).
- *
- * ORDER AND ATOMICITY. `planComponentFork` computes BOTH edits from both files'
- * current bytes before anything is written, and refuses — with a sentence — on
- * every failure it can see (definition not found, tag no longer matches, name
- * or file collision). Only then is the new file written, and only if nothing is
- * at that path already: `existsSync` is checked here as well as in the planner,
- * because the planner reads a directory LISTING the caller supplied and this is
- * the last moment before the write.
- */
-export function handleForkComponent(
-  store: OidStore,
-  body: Record<string, unknown>,
-  projectRoot = process.cwd(),
+  projectRoot: string,
 ): HandlerResult {
   const { oid, definitionOid, name } = body as {
     oid?: string;
@@ -1223,11 +757,11 @@ export function handleForkComponent(
   }
   const planned = planComponentFork({
     callsiteFile: callsite.file,
-    callsiteSource: readSettledSource(callsite.file),
+    callsiteSource: readSource(callsite.file),
     callsiteLine: callsite.line,
     callsiteCol: callsite.col,
     definitionFile: definition.file,
-    definitionSource: readSettledSource(definition.file),
+    definitionSource: readSource(definition.file),
     tag: callsite.tag,
     nameSeed: typeof name === 'string' ? name : undefined,
     siblingFiles,
@@ -1251,39 +785,23 @@ export function handleForkComponent(
       newName: plan.newName,
       tag: plan.tag,
       newFile,
-      newResourcePath: sourceResourcePath(newFile, projectRoot),
       importSpecifier: plan.importSpecifier,
       label: plan.historyLabel,
       callsiteFile: plan.callsiteFile,
       callsiteResourcePath: sourceResourcePath(plan.callsiteFile, projectRoot),
       callsitePrevSource: plan.callsitePrevSource,
       callsiteNewSource: plan.callsiteNewSource,
-      callsitePrevSha: sha256(plan.callsitePrevSource),
-      callsiteNewSha: sha256(plan.callsiteNewSource),
     },
   };
 }
 
-/**
- * POST `/__ui-source/extract-component` — P1 "Extract Component…".
- *
- * The fork route's sibling, and the SECOND file-creating seam on this
- * middleware (the header on `/__ui-source/fork-component` records why file
- * creation lives server-side at all). `planComponentExtraction` computes the
- * two new modules (component + portable CSF story under `src/prefabs/`) and
- * the callsite edit from current bytes before anything is written, refusing
- * with a sentence on every failure it can see (subtree gone, lexical capture,
- * module-local reference, name/file collision). Only then are the new files
- * written — `existsSync`-guarded here as well as in the planner, because the
- * planner reads a directory LISTING and this is the last moment before the
- * write — and the CALLSITE edit is handed back unwritten so the client pushes
- * it through project history: undo restores the callsite and leaves the two
- * new files behind as an inert module + story nothing imports.
- */
-export function handleExtractComponent(
+/** Plan extraction into a component and portable story, then collision-check
+ * and write both new files. Return the callsite change for project history;
+ * undo restores that callsite while retaining the created files. */
+function handleExtractComponent(
   store: OidStore,
   body: Record<string, unknown>,
-  projectRoot = process.cwd(),
+  projectRoot: string,
 ): HandlerResult {
   const { oid, name } = body as { oid?: string; name?: string };
   const entry = typeof oid === 'string' ? store.index.get(oid) : undefined;
@@ -1298,7 +816,7 @@ export function handleExtractComponent(
   }
   const planned = planComponentExtraction({
     sourceFile: entry.file,
-    source: readSettledSource(entry.file),
+    source: readSource(entry.file),
     line: entry.line,
     col: entry.col,
     nameSeed: typeof name === 'string' ? name : undefined,
@@ -1327,31 +845,21 @@ export function handleExtractComponent(
       newName: plan.newName,
       tag: plan.tag,
       componentFile: plan.componentFile,
-      componentResourcePath: sourceResourcePath(plan.componentFile, projectRoot),
       storyFile: plan.storyFile,
-      storyResourcePath: sourceResourcePath(plan.storyFile, projectRoot),
       importSpecifier: plan.importSpecifier,
       label: plan.historyLabel,
       callsiteFile: plan.callsiteFile,
       callsiteResourcePath: sourceResourcePath(plan.callsiteFile, projectRoot),
       callsitePrevSource: plan.callsitePrevSource,
       callsiteNewSource: plan.callsiteNewSource,
-      callsitePrevSha: sha256(plan.callsitePrevSource),
-      callsiteNewSha: sha256(plan.callsiteNewSource),
     },
   };
 }
 
-/**
- * POST `/__ui-source/csf-story` — the CSF write half (design ledger:
- * stories composed and framed everywhere, written nowhere): save an arg
- * set as a new story export, rename one, or delete one. The grammar and
- * every refusal live in the pure planner (`ui-source/plan-csf-story.ts`);
- * this handler is scope-guard + read + plan + write.
- */
-export function handleCsfStory(
+/** Save, rename, or delete a CSF story through the scoped source planner. */
+function handleCsfStory(
   body: Record<string, unknown>,
-  projectRoot = process.cwd(),
+  projectRoot: string,
 ): HandlerResult {
   const { op, file, name, newName, args } = body as {
     op?: 'save' | 'rename' | 'delete';
@@ -1367,7 +875,7 @@ export function handleCsfStory(
   if (!resolved) {
     return { status: 403, body: { changed: false, error: 'file out of editable scope' } };
   }
-  const source = readSettledSource(resolved);
+  const source = readSource(resolved);
   const plan =
     op === 'save'
       ? planSaveStory(source, name, args ?? {})
@@ -1390,22 +898,10 @@ function cssValueFromJsxLiteral(name: string, raw: string): string | null {
   return null;
 }
 
-/**
- * POST `/__ui-source/named-style` — the design ledger's NAMED STYLES order
- * (Webflow prior art: a reusable style is a CSS CLASS in the project's own
- * stylesheet). Three ops on one door:
- *
- * - `create` — mint `.className` in the given first-party stylesheet
- *   (`file`, guarded by {@link isEditableCssFile}), MOVING the element's
- *   literal inline declarations into it (dynamic members stay inline — they
- *   are not the writer's to move), and adding the class token to the
- *   element. Both files are planned before either is written, so a refusal
- *   (duplicate class, dynamic className) leaves nothing half-done.
- * - `apply` / `remove` — add/remove the bare class token on the element.
- *
- * Every refusal names its gate; a `className={expr}` is never rewritten.
- */
-export function handleNamedStyle(
+/** Create a first-party CSS class from literal inline declarations, or
+ * apply/remove a class token. Creation plans both files before writing;
+ * dynamic members remain inline and dynamic className expressions refuse. */
+function handleNamedStyle(
   store: OidStore,
   body: Record<string, unknown>,
 ): HandlerResult {
@@ -1427,7 +923,7 @@ export function handleNamedStyle(
   }
   const entry = store.index.get(oid);
   if (!entry) return { body: { changed: false, error: 'unknown oid' } };
-  const src = readSettledSource(entry.file);
+  const src = readSource(entry.file);
   const off = lineColToOffset(src, entry.line, entry.col);
 
   if (op === 'apply' || op === 'remove') {
@@ -1444,11 +940,7 @@ export function handleNamedStyle(
     return { body: { changed: r.changed, file: entry.file } };
   }
 
-  // No stylesheet named ⇒ MINT one beside the element's own module (and make
-  // the module import it — an unimported stylesheet never paints, and a bare
-  // `import './styles.css'` is exactly the ecosystem-native form Vite and the
-  // game's own build both honor). No example or fresh scaffold ships project
-  // CSS today, so without this the whole feature would open on a refusal.
+  // Without an explicit stylesheet, create one beside the element module and import it.
   const cleanCss =
     typeof file === 'string'
       ? (file.split('?')[0] ?? file)
@@ -1456,7 +948,7 @@ export function handleNamedStyle(
   if (!isEditableCssFile(cleanCss)) {
     return { body: { changed: false, error: 'css file out of editable scope' } };
   }
-  const cssSrc = existsSync(cleanCss) ? readSettledSource(cleanCss) : '';
+  const cssSrc = existsSync(cleanCss) ? readSource(cleanCss) : '';
   const decls: { prop: string; value: string }[] = [];
   const moved: string[] = [];
   for (const member of collectLiteralInlineStyles(src, off)) {
@@ -1503,23 +995,11 @@ export function handleNamedStyle(
   };
 }
 
-/**
- * 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. `ReactRootAuthoringAdapter.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(
+/** Restore a complete source file only when its current SHA matches
+ * ifMatchSha. The same project scope guard applies to reads and writes. */
+function handleRestore(
   body: Record<string, unknown>,
-  projectRoot = process.cwd(),
+  projectRoot: string,
 ): HandlerResult {
   const { file, source, ifMatchSha } = body as {
     file: string;
@@ -1532,7 +1012,7 @@ export function handleRestore(
   }
   let current: string;
   try {
-    current = readSettledSource(resolved);
+    current = readSource(resolved);
   } catch (e) {
     return { status: 404, body: { restored: false, error: String(e) } };
   }
@@ -1551,67 +1031,39 @@ export function handleRestore(
   return { body: { restored: true, sha: sha256(source) } };
 }
 
-export function uiOidPlugin(
-  services: ProjectServingServices,
-  include: RegExp | ((id: string) => boolean) = defaultProjectScopeInclude,
-): Plugin {
+export function uiOidPlugin(services: ProjectServingServices): Plugin {
   servingServices = services;
   const projectRoot = services.currentProjectRoot;
-  const test = typeof include === 'function' ? include : (id: string) => include.test(id);
   const store = new OidStore();
   // Captured by `configureServer` below, read by `transform` — the dev
-  // server's own `ModuleGraph` is what lets `declaredSurfaceForProjectFileViaGraph`
+  // server's own `ModuleGraph` is what lets the surface resolver
   // reach a root entry's surface through a NON-entry file's importer chain
   // (a child component with no direct fiber import of its
   // own). `undefined` in a build/SSR context without `configureServer`
   // (e.g. a one-off transform in a test) degrades to the direct-entry-only
-  // answer, same as before this existed.
+  // answer.
   let devServer: ViteDevServer | undefined;
   return {
     name: SOURCE_WRITE_ROUTES_PLUGIN,
     enforce: 'pre',
     transform(code, id) {
-      // A VIRTUAL MODULE IS NOT A FILE, and everything below this line treats
-      // `clean` as one — `resolveOidSurface` walks up from it looking for the
-      // owning `volter.project.json`, and `transformSource` records it as the
-      // stamped file's path. Vite's convention is that a `\0`-prefixed id was
-      // synthesized by a plugin and has no path behind it, so a path plugin
-      // skips it.
-      //
-      // The `test(clean)` below happens to reject today's virtual ids for the
-      // wrong reason (they carry no extension); a synthesized id may legally
-      // end in `.tsx`, and then the extension test passes and a NUL byte
-      // reaches `readFileSync`. That exact throw was measured one layer down
-      // on 2026-09-21 — see `importerFiles` in `server/project-root-surface.ts`
-      // for the failure and what it looked like from the editor.
+      // Virtual module IDs have no filesystem path and must not reach source reads.
       if (id.startsWith('\0')) return null;
       const clean = id.split('?')[0] ?? id;
-      if (!test(clean)) return null;
-      // W1 — R3F-dialect files get ` userData-oid` (fiber pierces it into
-      // `object.userData.oid`); react-dom files keep ` data-oid` unchanged.
-      // WHICH REGION owns this exact file decides: a declaration the project
-      // made (an `include` glob or a `mounts` entry in `editor/volter.adapter.ts`), the
-      // manifest root whose `entry` it is, or reach from one through the live
-      // import graph. Nothing is inferred from the file's own bytes; a file
-      // nothing places gets the documented `data-oid` default, said out loud.
-      // The project root is threaded because an INGEST root's sources live
-      // outside its manifest's directory (see `manifestOwning`), so the walk
-      // alone cannot find the project that declares them.
+      if (!defaultProjectScopeInclude(clean)) return null;
+      // The owning region chooses the stamp; source diagnostics report any mismatch.
       const decision = services.surfaceOf(clean, code, devServer?.moduleGraph, projectRoot());
       const { code: out, entries } = transformSource(code, clean, store, {
-        attribute: decision.attribute,
+        attribute: oidAttributeForSurface(decision.surface),
         canvasComponents: decision.surface === 'canvas',
-        importedR3fContracts: importedR3fContracts(code, clean),
       });
-      // Task #45: a wrong stamp must not be silent. Reported only when this
-      // file actually GOT stamps — a module with no JSX has no selection to
-      // break, so its (irrelevant) attribute is not worth a terminal line.
+      // Report stamp diagnostics only for modules that actually contain stamped JSX.
       if (entries.length > 0) decision.report();
       return { code: out, map: null };
     },
     configureServer(server) {
       devServer = server;
-      const activeProjectRoot = (): string => projectRoot() ?? server.config.root;
+      const activeProjectRoot = projectRoot;
       // The editor's own writes invalidate the modules they replace; the kit binds the graph.
       services.bindModuleGraph(server.moduleGraph, activeProjectRoot);
       // The Express host may apply express.json() app-wide, consuming the body and
@@ -1660,25 +1112,8 @@ export function uiOidPlugin(
           isAbsolute(file) ? file : resolve(activeProjectRoot(), file),
           activeProjectRoot(),
         );
-      /**
-       * Record this write with the collaboration session and REPORT THE
-       * REVISION IT PRODUCED.
-       *
-       * The revision is what the next mutation's optimistic-concurrency guard
-       * (`assertSourceMutation`, below) compares against, and the client only
-       * learned it from the collaboration SSE stream — one event loop later.
-       * A gesture that writes the same file TWICE therefore sent a revision
-       * that its own first write had already superseded, and the second write
-       * was rejected: measured on a canvas transform drag, whose `position`
-       * channel is two props (`x` and `y`) by construction, so EVERY drag lost
-       * its whole gesture to the compensation path. An R3F pivot-rotate
-       * (position + rotation) has the same shape.
-       *
-       * Returning it here closes the window without a second channel: the
-       * writer already awaits this response, so adopting the number it carries
-       * is exactly as fresh as the write itself (`source-write-backend.ts`'s
-       * `postJson`).
-       */
+      /** Return the revision produced by this write so the next awaited mutation
+       * can use it without waiting for collaboration SSE delivery. */
       const recordEditorMutation = (
         participantId: string,
         files: readonly string[],
@@ -1701,7 +1136,7 @@ export function uiOidPlugin(
         );
       };
       // Single middleware switching on the URL — avoids connect prefix-matching subtleties.
-      // Each POST endpoint delegates to a small module-level handler (below) so this
+      // Each POST endpoint delegates to a small module-level handler so this
       // dispatcher stays flat; the try/catch + JSON plumbing lives here once.
       const post = async (
         req: import('node:http').IncomingMessage,
@@ -1711,42 +1146,15 @@ export function uiOidPlugin(
       ): Promise<void> => {
         try {
           const body = await readJson(req);
-          const claimedParticipantId = body['participantId'];
-          const trustedParticipantId = req.headers['x-volter-share-participant-id'];
-          const trustedRole = req.headers['x-volter-share-role'];
-          if (
-            typeof trustedParticipantId === 'string' &&
-            typeof claimedParticipantId === 'string' &&
-            trustedParticipantId !== claimedParticipantId
-          ) {
-            throw new Error(
-              'The authenticated share participant does not match the source mutation author.',
-            );
-          }
-          const participantId =
-            typeof trustedParticipantId === 'string' ? trustedParticipantId : claimedParticipantId;
+          const participantId = body['participantId'];
           const expectedRevision = body['expectedRevision'];
           const readOnlySourceRequest =
             url === '/__ui-source/prepare' || url === '/__ui-source/read';
           const beforeFiles = mutationFiles(body);
-          if (
-            typeof trustedParticipantId === 'string' &&
-            beforeFiles.some((file) => !isCanonicalProjectSourcePath(activeProjectRoot(), file))
-          ) {
-            throw new Error('Shared source path leaves the project root.');
-          }
           if (!readOnlySourceRequest && beforeFiles.length > 0) {
             if (typeof participantId !== 'string' || !Number.isInteger(expectedRevision)) {
               throw new Error('Source mutations require participantId and expectedRevision.');
             }
-            if (
-              typeof trustedRole === 'string' &&
-              trustedRole !== 'editor' &&
-              trustedRole !== 'terminal' &&
-              trustedRole !== 'maintainer'
-            ) {
-              throw new Error(`The ${trustedRole} share role cannot edit source.`);
-            }
             services.collaboration(activeProjectRoot()).assertSourceMutation(
               participantId,
               expectedRevision as number,
@@ -1788,8 +1196,8 @@ export function uiOidPlugin(
         '/__ui-source/css': (b) => handleCss(b),
         '/__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/struct': (b) => handleStruct(store, b, 'struct'),
+        '/__ui-source/struct-many': (b) => handleStruct(store, b, 'struct-many'),
         '/__ui-source/csf-story': (b) => handleCsfStory(b, activeProjectRoot()),
         '/__ui-source/named-style': (b) => handleNamedStyle(store, b),
         '/__ui-source/fork-component': (b) =>
@@ -1800,17 +1208,7 @@ export function uiOidPlugin(
       server.middlewares.use(async (req, res, next) => {
         const url = (req.url ?? '').split('?')[0] ?? '';
         if (url === '/__ui-source/index') {
-          // Re-resolve contracts from current project bytes on every index
-          // read — but OFF the request: a cold enrich is a 2.6 s ts.Program
-          // and must not freeze first paint. The handler returns the last
-          // enriched map (or the raw stamp) immediately; see currentOidIndex.
-          //
-          // H5 (wave 4): the R3F
-          // authorability DIAGNOSTICS ride this same response, per entry.
-          // Deliberately not a channel of their own — attaching them to the
-          // payload the R3F adapter's `refreshSourceState()` already fetches is
-          // what makes their freshness structurally identical to the index's,
-          // with no second fetch, no polling loop and no cache to invalidate.
+          // Serve current stamps or matching cached enrichment while props resolve off-request.
 
           const indexStarted = Date.now();
           const index = currentOidIndex(store, activeProjectRoot(), server);
@@ -1819,34 +1217,15 @@ export function uiOidPlugin(
             'X-Volter-Oid-Index-Enriched',
             index === lastEnrichedIndex?.index ? '1' : '0',
           );
-          if (typeof req.headers['x-volter-share-participant-id'] !== 'string') {
-            return json(res, index);
-          }
-          return json(
-            res,
-            Object.fromEntries(
-              Object.entries(index).filter(([, value]) => {
-                const file = (value as { file?: unknown } | null)?.file;
-                return (
-                  typeof file === 'string' &&
-                  isCanonicalProjectSourcePath(activeProjectRoot(), file)
-                );
-              }),
-            ),
-          );
+          return json(res, index);
         }
         if (url === '/__ui-source/component-props' && req.method === 'GET') {
-          // THE PER-DEFINITION DOOR: the props a prefab DECLARES, asked before
-          // any callsite exists. The index above only knows tags already used
-          // in a file; a drop needs the declaration itself so a REQUIRED enum
-          // prop can be written with its first option instead of nothing
-          // (`<WeaponPickup>` rendered NOTHING until `kind` was set — runhuman
-          // pass 123). Same worker, same checker, one request.
+          // Resolve declared props before a callsite exists, for component insertion defaults.
           const params = new URL(req.url ?? '', 'http://localhost').searchParams;
           const file = params.get('file') ?? '';
           const name = params.get('name') ?? '';
           const root = activeProjectRoot();
-          if (!root || !file || !name) return json(res, { props: [] });
+          if (!file || !name) return json(res, { props: [] });
           const absolute = isAbsolute(file) ? resolve(file) : resolve(root, file);
           if (
             !isCanonicalProjectSourcePath(root, absolute) ||
@@ -1859,7 +1238,7 @@ export function uiOidPlugin(
             const props = await resolveDeclaredProps(root, [
               { key, file: absolute, tag: name, definition: true },
             ]);
-            return json(res, { props: props.get(key) ?? [] });
+            return json(res, { props: props.get(key)! });
           } catch (error) {
             return json(res, {
               props: [],