@volter/editor-react 0.5.210 → 0.5.212

package/src/source/r3f-contract-resolver.ts

@@ -1,26 +1,14 @@
-/**
- * The project-contract RESOLVER, host-neutral: how one module's relative
- * imports are followed to the component contracts and prop-shape type aliases
- * they bring into scope. Pure TypeScript AST work over a {@link ContractHost}
- * that supplies the three things a file system used to — read a file, test
- * for one, join a relative specifier — so the walk itself is independent of
- * WHERE the sources are read from. The dev server supplies them with
- * `node:fs` and a stamp-checked cache (`r3f-project-contracts.ts`); any other
- * reader supplies its own, and gets the same contracts rather than a second
- * answer ("HeroBox does not expose a scale prop" while the dev server wrote
- * it — one editor, two answers — is what this split exists to prevent).
- */
+/** Resolve relative project imports to visible and exported R3F contracts and
+ * prop-shape aliases. The server supplies file reads and a stamp-checked cache. */
 
 import ts from 'typescript';
 import {
   analyzeR3fComponentContracts,
   builtinR3fContractsOfImport,
-  type ComponentPropSpec,
   exportedR3fTypeAliases,
   type R3fComponentContract,
   type R3fTypeAlias,
 } from './oid-transform';
-import { localComponentPropSpecs } from './syntactic-prop-specs';
 import { hasModifier, parseAuthoringTsx } from './ts-ast';
 
 export interface ModuleAnalysis {
@@ -28,14 +16,9 @@ export interface ModuleAnalysis {
   exported: Map<string, R3fComponentContract>;
   /** This module's own `export type X = …` declarations, for its importers. */
   exportedTypeAliases: Map<string, R3fTypeAlias>;
-  /** Syntactic declared-prop specs per exported component
-   *  (`syntactic-prop-specs.ts`) — the checker-free surface attached to OID
-   *  entries so override detection and Apply-to-Component gate on facts
-   *  instead of an absent `ts.Program`. */
-  exportedProps: Map<string, ComponentPropSpec[]>;
 }
 
-export const SOURCE_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js'] as const;
+const SOURCE_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js'] as const;
 
 /** What a resolver needs from its host. Paths are whatever vocabulary the host
  *  speaks (absolute on the server, project-relative in storage); the resolver
@@ -49,10 +32,8 @@ export interface ContractHost {
   extname(file: string): string;
   /** `<base>/<name>` — the `index.*` candidate under a directory specifier. */
   join(base: string, name: string): string;
-  /** Optional shared cache around one file's analysis (the server's
-   *  stamp-checked map). Called with a thunk so the host decides whether to
-   *  run it; a host without one analyzes every time within one resolver. */
-  analyzeFileCached?(file: string, analyze: () => ModuleAnalysis): ModuleAnalysis;
+  /** Shared stamp-checked cache for one file's analysis. */
+  analyzeFileCached(file: string, analyze: () => ModuleAnalysis): ModuleAnalysis;
 }
 
 function resolveRelativeModule(
@@ -93,52 +74,6 @@ export class ProjectContractResolver {
 
   constructor(private readonly host: ContractHost) {}
 
-  importedForSource(code: string, file: string): Map<string, R3fComponentContract> {
-    return this.importedBindings(parseAuthoringTsx(file, code), file);
-  }
-
-  typeAliasesForSource(code: string, file: string): Map<string, R3fTypeAlias> {
-    return this.importedTypeAliases(parseAuthoringTsx(file, code), file);
-  }
-
-  /**
-   * Declared-prop specs for every component a file's JSX can name — its own
-   * top-level components plus its relative imports (a local declaration
-   * shadows an import, the language's own rule). This is what the hosted
-   * stamping hook attaches to OID entries in place of the dev server's
-   * checker-resolved specs.
-   */
-  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one bounded import-declaration pass, the same dispatch importedBindings carries.
-  propSpecsForSource(code: string, file: string): Map<string, ComponentPropSpec[]> {
-    const sf = parseAuthoringTsx(file, code);
-    const specs = new Map<string, ComponentPropSpec[]>();
-    for (const statement of sf.statements) {
-      if (
-        !ts.isImportDeclaration(statement) ||
-        !ts.isStringLiteral(statement.moduleSpecifier) ||
-        !statement.importClause
-      ) {
-        continue;
-      }
-      const target = resolveRelativeModule(this.host, file, statement.moduleSpecifier.text);
-      if (!target) continue;
-      const exported = this.analyzeFile(target).exportedProps;
-      const defaultName = statement.importClause.name?.text;
-      const defaultSpecs = exported.get('default');
-      if (defaultName && defaultSpecs) specs.set(defaultName, defaultSpecs);
-      const bindings = statement.importClause.namedBindings;
-      if (!bindings || !ts.isNamedImports(bindings)) continue;
-      for (const element of bindings.elements) {
-        const imported = exported.get(element.propertyName?.text ?? element.name.text);
-        if (imported) specs.set(element.name.text, imported);
-      }
-    }
-    for (const [name, local] of localComponentPropSpecs(sf, this.importedTypeAliases(sf, file))) {
-      specs.set(name, local);
-    }
-    return specs;
-  }
-
   analyzeSource(code: string, file: string): ModuleAnalysis {
     const sf = parseAuthoringTsx(file, code);
     const imported = this.importedBindings(sf, file);
@@ -151,17 +86,10 @@ export class ProjectContractResolver {
       imported,
       this.importedTypeAliases(sf, file),
     );
-    const props = localComponentPropSpecs(sf, this.importedTypeAliases(sf, file));
     return {
       visible,
       exported: this.exportsOf(sf, file, visible, (target) => this.analyzeFile(target).exported),
       exportedTypeAliases: exportedR3fTypeAliases(sf),
-      exportedProps: this.exportsOf(
-        sf,
-        file,
-        props,
-        (target) => this.analyzeFile(target).exportedProps,
-      ),
     };
   }
 
@@ -173,7 +101,6 @@ export class ProjectContractResolver {
         visible: new Map(),
         exported: new Map(),
         exportedTypeAliases: new Map(),
-        exportedProps: new Map(),
       };
     }
     this.visiting.add(file);
@@ -185,13 +112,10 @@ export class ProjectContractResolver {
               visible: new Map(),
               exported: new Map(),
               exportedTypeAliases: new Map(),
-              exportedProps: new Map(),
             }
           : this.analyzeSource(source, file);
       };
-      const analysis = this.host.analyzeFileCached
-        ? this.host.analyzeFileCached(file, analyze)
-        : analyze();
+      const analysis = this.host.analyzeFileCached(file, analyze);
       this.cache.set(file, analysis);
       return analysis;
     } finally {
@@ -199,21 +123,8 @@ export class ProjectContractResolver {
     }
   }
 
-  /**
-   * The prop-shape type aliases one module imports, under their local names.
-   *
-   * The component-contract walk above already follows relative imports; this
-   * is the same walk for the OTHER thing a shared module exports. Without it,
-   * `typeAllowsStandardRootProps` stopped at the file boundary, so a project
-   * that declares its canonical prop shape once — the thing the authoring
-   * convention is asking for — read as forwarding nothing, and every prefab
-   * annotated with it drew a permanent R3F002 telling it to do what it was
-   * already doing.
-   *
-   * Only relative specifiers resolve. An installed package's `.d.ts` is not
-   * source this walk can trust, and the built-in prop-type table is how a
-   * package surface earns recognition instead.
-   */
+  /** Resolve imported prop-shape aliases under their local names. Only
+   * relative project sources are followed; package surfaces use builtin types. */
   private importedTypeAliases(sf: ts.SourceFile, file: string): Map<string, R3fTypeAlias> {
     const aliases = new Map<string, R3fTypeAlias>();
     for (const statement of sf.statements) {
@@ -301,12 +212,7 @@ export class ProjectContractResolver {
         statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier)
           ? resolveRelativeModule(this.host, file, statement.moduleSpecifier.text)
           : null;
-      // A BARREL (`export * from './Ramp'`) re-exports every name, and dropping
-      // it dropped the whole contract: racing-game reaches every one of its
-      // components through `src/models/index.ts`, so `<Ramp/>`, `<Train/>` and
-      // `<Vehicle/>` all read as "definition not in this file" and refused
-      // every transform write at their callsites. `export *` skips `default` by
-      // the language's own rule.
+      // A barrel's `export *` carries every named contract except `default`.
       if (!statement.exportClause) {
         if (!target) continue;
         for (const [name, contract] of moduleExports(target)) {

package/src/source/r3f-physics-binding.ts

@@ -1,144 +1,20 @@
-/**
- * WHERE A PHYSICS-OWNED NODE IS ACTUALLY PLACED — the source fact that says an
- * element's transform is written by a body rather than by the element's own
- * JSX, and which artifact owns that body's SPAWN.
- *
- * ## The measured defect
- *
- * `@react-three/cannon` drives a node by writing its MATRIX:
- * `object.matrixAutoUpdate = false; object.matrix.copy(compose(p, q, ONE))`
- * (`node_modules/@react-three/cannon/dist/index.js`'s `apply`). Two consequences,
- * both of which the editor got wrong before this module existed:
- *
- *  - The node's own `position`/`rotation`/`scale` JSX props are DEAD. Writing
- *    one produces a file that says the object is somewhere it will never be:
- *    the body re-spawns from the hook's argument and overwrites the matrix on
- *    the next frame. Measured on the racing-game ingest — a moved chassis wrote
- *    its leaf element and the remount re-spawned at the binding's
- *    `[-110, 0.75, 220]`, digit for digit.
- *  - `scale` goes with them: `apply` composes with a fixed `(1,1,1)`, so a
- *    cannon body erases its node's scale as surely as its position.
- *
- * The transform is therefore owned by the BINDING — the `useBox(…)` /
- * `useCompoundBody(…)` call that attached the body to this element's ref — and
- * an honest editor writes where the binding reads, or refuses by name.
- *
- * ## Where the binding reads, measured rather than assumed
- *
- * Over the whole vendored cannon corpus (`vendor/games/racing-game`: `Chassis`,
- * `Wheel`, `Ramp`, `Train`, `Goal`, `Heightmap`, `BoundingBox`) **not one hook
- * argument carries an inline position literal.** Every binding takes its spawn
- * from the component's OWN PROPS — `useBox(() => ({ …props }))`, or the
- * shorthand `useBox(() => ({ args, position, rotation }))` over a destructured
- * prop — so the literal that places the body is the one at the component's
- * CALLSITE (`<Ramp position={[2, -1, 168.55]} />`, `App.tsx:57`). That is the
- * prop literal the write routes to, and the ordinary JSX prop writer already
- * reaches it; what was missing was a contract that admits the forwarding is
- * real, which is `forwarded` below.
- *
- * `literal` is the other shape — a spawn spelled at the hook itself. It is
- * recorded so a refusal can NAME it (`position is owned by useBox at
- * Ramp.tsx:8`) rather than pretending the element's own prop is writable. No
- * writer for it ships: a hook argument is not a JSX element, it has no oid, and
- * building an address for a shape with zero occurrences in the corpus would be
- * a writer with no caller.
- *
- * ## Why this is a SOURCE analysis and not the runtime flag
- *
- * `matrixAutoUpdate === false` is a true runtime tell for cannon, and a useless
- * one for routing: it says a driver owns the node, never WHERE the driver reads
- * its spawn. It is also not general — `@react-three/rapier` writes
- * `object.position.copy(…)`/`object.quaternion.copy(…)` and leaves
- * `matrixAutoUpdate` alone, so the flag misses rapier entirely while the source
- * says plainly that `<RigidBody position={…}>` is the spawn (which is why the
- * built-in rapier contract in `oid-transform.ts` already routes it correctly).
- * The binding is a fact about the file; the write anchor has to be too.
- *
- * Nothing here is a general "physics abstraction": it recognizes ONE package's
- * body hooks by import specifier, the same hand-audited way
- * `BUILTIN_R3F_CONTRACTS` recognizes `<RigidBody>`, because guessing at an
- * unknown library's ownership is how an editor writes props a library ignores.
- */
+/** Analyze Cannon body hooks that own a JSX element's transform. Forwarded
+ * spawn props contribute to the component contract; channels driven through
+ * the body API each frame remain simulation owned. Bind refs within their
+ * enclosing scopes rather than guessing from runtime matrix flags. */
 
 import ts from 'typescript';
 import { enclosingScope, refIdentifier } from './ts-ast';
 
-import type { PhysicsChannel, R3fPhysicsBinding } from '@volter/sdk/source-authoring';
-export type { PhysicsChannel, R3fPhysicsBinding } from '@volter/sdk/source-authoring';
-
-/** What an element carrying a binding looks like to a writer. Structural rather
- *  than the whole `OidEntry`, so this stays the browser-safe half. */
-export interface PhysicsBoundElement {
-  readonly file: string;
-  readonly physicsBinding?: R3fPhysicsBinding | undefined;
-  /** The callsite half of the same fact: the component this element
-   *  instantiates hands `channel` to a body binding inside itself, so the
-   *  literal written HERE is the spawn the simulation reads
-   *  (`oid-transform.ts`'s `bodyForwarded`). */
-  readonly r3fAuthoring?: { readonly bodyForwarded?: readonly string[] | undefined } | undefined;
-}
-
-/**
- * Is this element's `channel` PLACED BY A SIMULATED BODY — the fact that makes
- * an edit here a `physics-binding` write rather than an ordinary `source-prop`
- * one, in `WriteAnchorKind`'s vocabulary (`@volter/project/adapter`'s `authoring.ts`).
- *
- * Two shapes, and both are the same question ("does a body read this value?")
- * asked of the two places a body can be attached, which is why they answer from
- * one function rather than one per lane:
- *
- *  - the element carries the binding itself (`<mesh ref={ref}>` whose ref a
- *    `useBox` bound) — its own props are dead on arrival, so the write is
- *    refused, and the KIND still says which lane owns the value;
- *  - the element is a CALLSITE whose component hands the channel to a binding
- *    inside it (`<Ramp position={…}/>`, `<CitadelTower position={…}/>`) — the
- *    literal a body actually spawns from, and the WRITABLE case. This is the
- *    one whose authored value has to survive the re-settle, which is the whole
- *    reason `physics-binding` is a kind of its own.
- *
- * Deliberately beside {@link physicsRefusal}: the refusal names who owns the
- * placement and this names the lane, and two derivations of "who owns this
- * placement" living in different files is exactly how a subject came to be
- * classified in one lane while its edit travelled another.
- */
-export function bodyPlacedChannel(
-  element: PhysicsBoundElement | undefined,
-  channel: string,
-): boolean {
-  if (channel !== 'position' && channel !== 'rotation' && channel !== 'scale') return false;
-  if (element?.physicsBinding) return true;
-  return element?.r3fAuthoring?.bodyForwarded?.includes(channel) === true;
-}
-
-/**
- * WHY a write to this element's own `channel` would be lost — `null` when no
- * body owns it, which is the ordinary case.
- *
- * ONE derivation, read by both writers (the first-party R3F source lane's
- * `transformEditability` and the ingest lane's `oid-source-persistence`), so
- * the two can never disagree about who owns a placement. Each sentence names
- * the binding and where to go instead; "does not forward position" would send
- * an author to add a prop the body would ignore.
- */
-export function physicsRefusal(
-  element: PhysicsBoundElement | undefined,
-  channel: string,
-): string | null {
-  const binding = element?.physicsBinding;
-  if (!binding) return null;
-  if (channel !== 'position' && channel !== 'rotation' && channel !== 'scale') return null;
-  const at = `${element!.file.split('/').pop() ?? element!.file}:${binding.line}`;
-  const owned = `${channel} is owned by ${binding.hook} at ${at}`;
-  if ((binding.forwarded as readonly string[]).includes(channel)) {
-    return `${owned}, which reads this component's own ${channel} prop — write it where the instance is placed, not on this element`;
-  }
-  if ((binding.literal as readonly string[]).includes(channel)) {
-    return `${owned} — the body spawns from that hook's own argument, and a hook argument has no write anchor`;
-  }
-  // Including `scale`, always: the body re-composes the node's matrix with a
-  // fixed unit scale (`@react-three/cannon`'s `apply`), so a scale written here
-  // is erased on the next frame exactly like a position.
-  return `${owned} — this node is placed by the simulation, so a ${channel} written here is overwritten on the next frame`;
+type PhysicsChannel = 'position' | 'rotation' | 'scale';
+/** Transform channels owned by an element's Cannon body hook. */
+export interface R3fPhysicsBinding {
+  /** Channels whose spawn the hook takes from the component's own props — the
+   *  write belongs at this component's CALLSITE. */
+  forwarded: PhysicsChannel[];
+  /** Transform channels written through the body API inside useFrame.
+   * Omit the field when no channel is driven. */
+  apiDriven?: PhysicsChannel[];
 }
 
 /**
@@ -164,10 +40,9 @@ const CANNON_BODY_HOOKS = new Set([
 
 const PHYSICS_PACKAGES = new Set(['@react-three/cannon']);
 
-/** A cannon body hook's LOCAL name (an `import { useBox as box }` keeps working)
- *  → the imported hook name. */
-function bodyHookNames(sf: ts.SourceFile): Map<string, string> {
-  const names = new Map<string, string>();
+/** Local names imported as Cannon body hooks, including aliases. */
+function bodyHookNames(sf: ts.SourceFile): Set<string> {
+  const names = new Set<string>();
   for (const statement of sf.statements) {
     if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) {
       continue;
@@ -177,7 +52,7 @@ function bodyHookNames(sf: ts.SourceFile): Map<string, string> {
     if (!bindings || !ts.isNamedImports(bindings)) continue;
     for (const element of bindings.elements) {
       const imported = element.propertyName?.text ?? element.name.text;
-      if (CANNON_BODY_HOOKS.has(imported)) names.set(element.name.text, imported);
+      if (CANNON_BODY_HOOKS.has(imported)) names.add(element.name.text);
     }
   }
   return names;
@@ -238,14 +113,6 @@ function bodyArgumentObject(call: ts.CallExpression): ts.ObjectLiteralExpression
   return undefined;
 }
 
-function isVec3Literal(expression: ts.Expression): boolean {
-  if (!ts.isArrayLiteralExpression(expression) || expression.elements.length !== 3) return false;
-  return expression.elements.every((element) => {
-    const inner = ts.isPrefixUnaryExpression(element) ? element.operand : element;
-    return ts.isNumericLiteral(inner);
-  });
-}
-
 /** Does this expression read one of the enclosing component's own props? */
 function readsProp(expression: ts.Expression, scope: PropScope, channel: PhysicsChannel): boolean {
   if (ts.isIdentifier(expression)) return scope.named.has(expression.text);
@@ -257,14 +124,8 @@ function readsProp(expression: ts.Expression, scope: PropScope, channel: Physics
   );
 }
 
-/**
- * How each channel's spawn is spelled in one hook argument.
- *
- * LAST WINS, the way an object literal actually evaluates: `{ position: […],
- * ...props }` is placed by `props`, and `{ ...props, position: […] }` by the
- * literal. Getting that backwards would name the wrong owner in a refusal.
- */
-type ChannelOwner = 'forwarded' | 'literal' | 'expression';
+/** The last assignment to each channel determines whether it forwards props. */
+type ChannelOwner = 'forwarded' | 'expression';
 
 /**
  * What ONE property of a hook argument says about placement.
@@ -296,29 +157,20 @@ function propertyOwnership(
   if (!ts.isPropertyAssignment(property) || !ts.isIdentifier(property.name)) return [];
   const name = property.name.text;
   if (!isPhysicsChannel(name)) return [];
-  if (isVec3Literal(property.initializer)) return [[name, 'literal']];
   return [[name, readsProp(property.initializer, scope, name) ? 'forwarded' : 'expression']];
 }
 
 function channelOwnership(
   literalObject: ts.ObjectLiteralExpression,
   scope: PropScope,
-): { forwarded: PhysicsChannel[]; literal: PhysicsChannel[] } {
+): PhysicsChannel[] {
   const owner = new Map<PhysicsChannel, ChannelOwner>();
   for (const property of literalObject.properties) {
     for (const [channel, kind] of propertyOwnership(property, scope)) owner.set(channel, kind);
   }
-  const pick = (kind: ChannelOwner): PhysicsChannel[] =>
-    [...owner.entries()].filter(([, value]) => value === kind).map(([channel]) => channel);
-  return { forwarded: pick('forwarded'), literal: pick('literal') };
+  return [...owner.entries()].filter(([, value]) => value === 'forwarded').map(([channel]) => channel);
 }
 
-/**
- * The ref identifier a body hook binds — either the ref it was HANDED
- * (`useBox(fn, ref)`, the forwardRef spelling) or the one it HANDS BACK
- * (`const [ref] = useBox(fn)`, the plain spelling). Both occur in the vendored
- * corpus and they are the same binding.
- */
 /** The API identifier a body hook's tuple hands back (`const [, api] = useBox(…)`),
  *  or null when the call does not destructure one. */
 function boundApiName(call: ts.CallExpression): string | null {
@@ -363,6 +215,7 @@ function apiDrivenChannels(
   return [...found];
 }
 
+/** Resolve a hook's returned ref or its explicitly supplied ref argument. */
 function boundRefName(call: ts.CallExpression): string | null {
   const declaration = call.parent;
   if (ts.isVariableDeclaration(declaration) && ts.isArrayBindingPattern(declaration.name)) {
@@ -377,14 +230,7 @@ function boundRefName(call: ts.CallExpression): string | null {
   return null;
 }
 
-/**
- * Every JSX element in `sf` whose ref a physics body binds, mapped to the
- * binding that owns its transform.
- *
- * Keyed by the OPENING element so both readers join on the same node: the
- * component-contract analysis (which asks about a component's root) and the
- * stamping transform (which asks about each element it stamps).
- */
+/** Join scoped body-hook refs to JSX elements for component-contract analysis. */
 export function physicsBindingsByElement(
   sf: ts.SourceFile,
 ): Map<ts.JsxOpeningLikeElement, R3fPhysicsBinding> {
@@ -396,22 +242,19 @@ export function physicsBindingsByElement(
    *  bound it: two components may each call their ref `ref`. */
   const byScope = new Map<ts.Node | null, Map<string, R3fPhysicsBinding>>();
 
-  const record = (call: ts.CallExpression, hook: string): void => {
+  const record = (call: ts.CallExpression): void => {
     const refName = boundRefName(call);
     if (!refName) return;
     const scope = enclosingScope(call);
     const argument = bodyArgumentObject(call);
-    const ownership = argument
+    const forwarded = argument
       ? channelOwnership(argument, propScopeOf(scope?.parameters))
-      : { forwarded: [], literal: [] };
-    const { line } = sf.getLineAndCharacterOfPosition(call.getStart(sf));
+      : [];
     const api = boundApiName(call);
     const driven = api ? apiDrivenChannels(scope, sf, api) : [];
     const scoped = byScope.get(scope) ?? new Map<string, R3fPhysicsBinding>();
     scoped.set(refName, {
-      hook,
-      line: line + 1,
-      ...ownership,
+      forwarded,
       ...(driven.length > 0 ? { apiDriven: driven } : {}),
     });
     byScope.set(scope, scoped);
@@ -419,8 +262,7 @@ export function physicsBindingsByElement(
 
   const collect = (node: ts.Node): void => {
     if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
-      const hook = hooks.get(node.expression.text);
-      if (hook) record(node, hook);
+      if (hooks.has(node.expression.text)) record(node);
     }
     ts.forEachChild(node, collect);
   };

package/src/source/r3f-project-contracts.ts

@@ -15,7 +15,6 @@ import {
   isBuiltinR3fContract,
   type R3fAuthoringDiagnostic,
   type R3fComponentContract,
-  type R3fTypeAlias,
   runtimeMotionRefs,
 } from './oid-transform';
 import {
@@ -25,41 +24,9 @@ import {
 } from './r3f-contract-resolver';
 import { parseAuthoringTsx } from './ts-ast';
 
-/** Re-exported from its declaration site. The type moved to `oid-transform.ts`
- *  (browser-safe, no `node:fs`) when H5 made a diagnostic travel on an
- *  `OidEntry`; this module still PRODUCES them, and remains the import site
- *  every existing caller already uses. */
-export type { R3fAuthoringDiagnostic };
-
-/**
- * THE ON-DISK HALF OF THE WALK, CACHED ACROSS CALLS — stamped by the file's
- * own bytes, so it still "naturally tracks the latest bytes on disk without a
- * cache invalidation protocol" (the property the fresh-resolver-per-call rule
- * below exists to keep), while no longer re-deriving the same unchanged module
- * once per importer.
- *
- * WHY IT HAD TO EXIST. `uiOidPlugin`'s `transform` builds one resolver per
- * MODULE TRANSFORM (`vite-plugin-ui-oid.ts`, `importedR3fContracts(code,
- * clean)`), and each resolver walks that module's whole transitive
- * RELATIVE-import closure with `ts.createSourceFile`. The per-resolver cache
- * therefore only ever helped inside one file's walk and was thrown away
- * immediately after, so a project's shared modules were re-parsed once per
- * importer — quadratic in the shared-component fan-in, and invisible on a
- * small project. Measured on an imported 3D FPS project port (528 source files,
- * ~200 project modules served during one editor boot), V8 CPU profile of the
- * dev server across the whole ready -> page-bound window: **46.9s of 72.7s
- * sampled (64.5%) inside `typescript.js`**, entered from here and from
- * `oid-transform.ts`. The server's event loop was blocked ~80-90% of every
- * 5s bucket for two minutes, which is why a static `editor-mark.svg` took
- * 38s to serve and the browser's own module waterfall could not start.
- *
- * THE STAMP IS TAKEN TWICE, AROUND THE READ. A single stat cannot tell a
- * concurrent save from a quiet file: stat-then-read caches new bytes under an
- * old stamp, read-then-stat caches old bytes under a new one, and either way
- * the entry is stale FOREVER because its stamp looks current. Only a
- * before/after pair that AGREES proves nothing was written across the read;
- * a disagreeing pair is simply not cached (the analysis is still returned).
- */
+/** Cache disk analysis by file stamp. Matching stats before and after the
+ * read establish that the source stayed unchanged; concurrent saves produce
+ * uncached analysis. A fresh resolver joins the current import closure. */
 const analysisByFile = new Map<string, { stamp: string; analysis: ModuleAnalysis }>();
 /** Bound: a dev session may open many projects, and nothing else evicts. */
 const MAX_CACHED_ANALYSES = 4096;
@@ -105,37 +72,11 @@ function newResolver(): ProjectContractResolver {
   return new ProjectContractResolver(nodeContractHost);
 }
 
-/** Resolve the contracts of component identifiers imported into one source
- * module. A fresh resolver per call makes save/HMR behavior naturally track
- * the latest bytes on disk without a cache invalidation protocol; the walk's
- * on-disk half reuses {@link analysisByFile}, which keeps that property by
- * stamping every entry with the bytes it was derived from. */
-export function importedR3fContracts(
-  code: string,
-  file: string,
-): Map<string, R3fComponentContract> {
-  return newResolver().importedForSource(code, file);
-}
-
-/** The prop-shape type aliases one module's relative imports bring into
- * scope, under their local names — the alias half of `importedR3fContracts`,
- * and the other input `transformSource` needs to read a shared prop shape. */
-export function importedR3fTypeAliases(code: string, file: string): Map<string, R3fTypeAlias> {
-  return newResolver().typeAliasesForSource(code, file);
-}
-
-/** All local and imported component bindings visible to one module. Used by
- * the live index endpoint to refresh metadata after a shared component HMRs. */
-export function visibleR3fContracts(code: string, file: string): Map<string, R3fComponentContract> {
-  return newResolver().analyzeSource(code, file).visible;
-}
-
 /**
  * The component a `default` export names, when the export is
  * `export default World` or `export default function World() {…}`.
  *
- * A three root's entry module default-exports its component (D26,
- * the editor's `roots/r3f-root.tsx`) — the same contract dom roots use. That component IS the
+ * A three root's entry module default-exports its component — the same contract dom roots use. That component IS the
  * adapter root, so the single-spatial-root rule must not fire on it: a world
  * legitimately returns a fragment of lights, scenery and players.
  */
@@ -190,17 +131,8 @@ function returnedRootComponent(element: ts.JsxElement | ts.JsxSelfClosingElement
   return null;
 }
 
-/**
- * R3F002's subject: a component with one native root that does not route every
- * authored transform channel to it.
- *
- * A simulation-owned root is NOT that (FX-9/PD-11). The component's own source
- * already says who writes the transform — it takes no transform prop and drives
- * its root ref every frame — so asking it to "keep instances movable" asks for
- * an authored placement the next tick overwrites. The warning was permanent and
- * unactionable on exactly the components (prey, projectiles, anything mapped
- * over simulation state) it fired on most.
- */
+/** Warn when a single native root omits authored transform forwarding.
+ * Simulation-owned roots accept no authored transform and are excluded. */
 function needsForwardedTransforms(
   contract: R3fComponentContract | undefined,
 ): contract is R3fComponentContract {
@@ -245,32 +177,10 @@ function isKeyedListItem(
 }
 
 export interface R3fAuthoringDiagnosticsOptions {
-  /**
-   * The caller has RESOLVED this file's region and it is a `three` one —
-   * `server/project-root-surface.ts`'s `resolveOidSurface`, which reads the
-   * region's declared `include` globs, the manifest's root entries, and live
-   * import reach. Absent or `false` means the caller resolved something else,
-   * or resolved nothing, and this analyzer stays silent.
-   *
-   * It USED to default to a source-text sniff — does this file's text name
-   * `@react-three/fiber`? — and that sniff is the reason a project could not
-   * centralize its R3F imports: a terminal whose 138 components take their
-   * prop shape from one shared `prefab.ts` and otherwise render nothing but
-   * intrinsic `<group>`/`<mesh>` tags had 12 files pass it and 126 SILENTLY
-   * SKIPPED, reported as no findings. Silence that cannot be distinguished
-   * from a clean bill of health is the worst thing an analyzer can produce,
-   * and reach answers all 138 because reach does not care where a project
-   * keeps its imports.
-   *
-   * Refusing to answer without a resolved surface is not a smaller analyzer,
-   * it is an honest one: a project's DOM regions run through here too
-   * (`project-validation.ts` validates every source file, whatever its
-   * adapter), and every rule below would fire on a `<div>`-rooted component —
-   * R3F002 would tell it to forward `position`. A caller with no region answer
-   * has an AMBIGUOUS file, which `resolveOidSurface` already reports as
-   * `OID001`/`OID002` with the declaration that fixes it.
-   */
-  knownThreeSurface?: boolean;
+  /** Whether the caller resolved this file to a stage region through declared
+   * includes, manifest roots and import reach. False suppresses R3F-specific
+   * diagnostics for DOM or unresolved regions. */
+  knownStageSurface: boolean;
 }
 
 /** Convention diagnostics for ordinary R3F source. These are warnings, not a
@@ -279,16 +189,16 @@ export interface R3fAuthoringDiagnosticsOptions {
 export function r3fAuthoringDiagnostics(
   code: string,
   file: string,
-  opts?: R3fAuthoringDiagnosticsOptions,
+  opts: R3fAuthoringDiagnosticsOptions,
 ): R3fAuthoringDiagnostic[] {
-  if (!opts?.knownThreeSurface) return [];
+  if (!opts.knownStageSurface) return [];
   const analysis = newResolver().analyzeSource(code, file);
   const sf = parseAuthoringTsx(file, code);
   const diagnostics: R3fAuthoringDiagnostic[] = [];
   const diagnosedDefinitions = new Set<string>();
   const diagnosedMultiRoots = new Set<string>();
   const diagnosedMotionRoots = new Set<string>();
-  // `export default World` IS the adapter root (D26 — the one entry shape).
+  // The default-exported component is the adapter root.
   const adapterRootComponents = new Set<string>();
   const defaultExport = defaultExportedComponent(sf);
   if (defaultExport) adapterRootComponents.add(defaultExport);