@volter/editor-react 0.5.211 → 0.5.212

package/src/source/oid-transform.ts

@@ -1,49 +1,71 @@
-/**
- * OID instrumentation (C1/C2) — the visual-edit "stamp every JSX element with a
- * stable source id" trick, ported to volter using the TypeScript compiler API
- * (volter has `typescript`; it does NOT have @babel/*). Hand-authored React UI
- * component source is transformed at build/dev time to carry a `data-oid` on every
- * JSX element, and an OID -> {file,line,col,component,tag} index is built so the
- * editor can map a clicked element back to its exact source location.
- *
- * Stability (C1): unlike visual-edit's line:col key (which shifts every id below an
- * edit), we key by a CONTENT signature `component:tag:nthOccurrence`, so an edit on
- * an unrelated line keeps existing ids stable. The `data-oid` lives ONLY in the
- * transformed output, never on disk (the writer edits the original source instead).
- */
+/** Instrument authored JSX with source IDs using the TypeScript compiler API.
+ * IDs key file, component, tag, and occurrence, so unrelated line edits keep
+ * their identities. Stamps exist only in transform output; source writes use
+ * the original files and the recorded index locations. */
 import { isMemberLiteral, memberKey } from './prop-member-writer';
 import ts from 'typescript';
-import {
-  environmentBindingsByElement,
-  type R3fEnvironmentBinding,
-} from './r3f-environment-binding';
-import { jointBindingsByElement, type R3fJointBinding } from './r3f-joint-binding';
-import { lodBindingsByElement, type R3fLodBinding } from './r3f-lod-binding';
-import { particleBindingsByElement, type R3fParticleBinding } from './r3f-particle-binding';
+import { dreiDetailedLocalNames } from './drei-detailed-names';
 import { physicsBindingsByElement, type R3fPhysicsBinding } from './r3f-physics-binding';
 import { parseAuthoringTsx, refIdentifier } from './ts-ast';
 
-import type { DeclaredRootSurface, OidEntry, R3fComponentContract, R3fTransformProp, SourceDialectEvidence } from '@volter/sdk/source-authoring';
-export type { ComponentPropSpec, DeclaredRootSurface, OidEntry, R3fAuthoringDiagnostic, R3fComponentContract, R3fTransformProp, SourceDialectEvidence } from '@volter/sdk/source-authoring';
-
-export type {
-  R3fEnvironmentBinding,
-  R3fEnvironmentNumberBinding,
-  R3fEnvironmentStringBinding,
-} from './r3f-environment-binding';
-export type {
-  R3fJointBinding,
-  R3fJointHook,
-  R3fJointLiteral,
-  R3fJointLiteralRange,
-} from './r3f-joint-binding';
-export type { R3fLodBinding, R3fLodNumberBinding } from './r3f-lod-binding';
-export type {
-  QuarksEmitterShape,
-  R3fParticleBinding,
-  R3fParticleNumberBinding,
-} from './r3f-particle-binding';
-export type { PhysicsChannel, R3fPhysicsBinding } from './r3f-physics-binding';
+import type { ComponentContract, DeclaredRootSurface, OidEntry as SourceOidEntry } from '@volter/sdk/source-authoring';
+export type { ComponentPropSpec, DeclaredRootSurface } from '@volter/sdk/source-authoring';
+
+export type { OidEntry } from '@volter/sdk/source-authoring';
+type OidEntry = SourceOidEntry;
+
+/** R3F authoring-convention warning returned by the source diagnostics service. */
+export interface R3fAuthoringDiagnostic {
+  code: 'R3F002' | 'R3F003' | 'R3F004' | 'R3F005';
+  severity: 'warning';
+  file: string;
+  /** 1-based source position computed from node.getStart(). */
+  line: number;
+  col: number;
+  /** The component the warning is ABOUT: the definition it names (R3F002/3/5)
+   *  or the tag at the offending callsite (R3F004). */
+  component: string;
+  message: string;
+}
+type R3fTransformProp = 'position' | 'rotation' | 'scale';
+/** The R3F authoring contract of a component definition: the kit's `ComponentContract` and what R3F reads
+ * beside it. */
+export interface R3fComponentContract extends ComponentContract {
+  root: 'single' | 'multiple' | 'non-spatial' | 'unknown';
+  rootTag?: string;
+  transformProps: R3fTransformProp[];
+  /** The callsite's native `visible` prop is proven to reach the single
+   * Object3D root. Omitted is deliberately false/unknown, so an editor never
+   * writes a decorative prop that the component silently ignores. */
+  visibleProp?: true;
+  /** The component drives its root transform through a ref in useFrame and
+   * accepts no authored transform. Suppress forwarding and motion-conflict
+   * diagnostics for that simulation-owned transform. */
+  simulationOwnedTransform?: boolean;
+
+}
+/**
+ * What ONE file's own bytes say about which reconciler its JSX targets.
+ *
+ * DIAGNOSTIC EVIDENCE ONLY — it decides no attribute anywhere. What a file
+ * renders is REPORTED (`serving/source-diagnostics.ts`'s `OID003`/`OID004`);
+ * which region it belongs to is a declaration or a reach, never a property of
+ * its bytes.
+ *
+ * Deliberately a cheap regex scan, not an AST walk, because it runs in a
+ * `transform` hook on every project `.tsx`. COMMENTS are
+ * stripped first (see {@link stripCommentsForScan}) so prose that merely
+ * NAMES a tag cannot count as rendering it; a mention inside a string still
+ * matches, which is deliberate — import specifiers ARE strings.
+ */
+export interface SourceDialectEvidence {
+  /** Scanned source includes the R3F package specifier. */
+  reconcilerImport: boolean;
+  /** Distinct tags observed by the R3F-only JSX scan. */
+  r3fOnlyTags: string[];
+  /** Distinct tags observed by the DOM-only JSX scan. */
+  domOnlyTags: string[];
+}
 
 /** A number as the writer reads one: `3`, `-3`, `+0.5` (the writer's `NUMBER_LITERAL_SOURCE`). */
 function signedNumericLiteral(expression: ts.Expression): boolean {
@@ -202,7 +224,7 @@ const BUILTIN_R3F_CONTRACTS: Readonly<
  * Package prop types that are themselves a proved native-root prop surface.
  * Kept beside the component contract because both facts come from the same
  * hand-audited public API. This lets ordinary wrappers preserve the package's
- * own type (`Omit<RigidBodyProps, ...>`) without pretending every imported
+ * own type (`Omit<RigidBodyProps,...>`) without pretending every imported
  * type is spatial.
  */
 const BUILTIN_R3F_ROOT_PROP_TYPES: Readonly<Record<string, Readonly<Record<string, string>>>> = {
@@ -299,8 +321,8 @@ function unwrapExpression(expression: ts.Expression): ts.Expression {
 function returnedExpression(body: ts.ConciseBody): ts.Expression | undefined {
   if (!ts.isBlock(body)) return unwrapExpression(body);
   const returns = body.statements.filter(ts.isReturnStatement);
-  if (returns.length !== 1 || !returns[0]?.expression) return undefined;
-  return unwrapExpression(returns[0].expression);
+  if (returns.length !== 1 || !returns[0]!.expression) return undefined;
+  return unwrapExpression(returns[0]!.expression);
 }
 
 /**
@@ -385,10 +407,10 @@ function typeAllowsStandardRootProps(
   return false;
 }
 
-function spatialRootOpening(expression: ts.Expression): ts.JsxOpeningLikeElement | undefined {
-  if (ts.isJsxSelfClosingElement(expression)) return expression;
-  if (!ts.isJsxElement(expression)) return undefined;
-  return expression.openingElement;
+function spatialRootOpening(
+  expression: ts.JsxElement | ts.JsxSelfClosingElement,
+): ts.JsxOpeningLikeElement {
+  return ts.isJsxSelfClosingElement(expression) ? expression : expression.openingElement;
 }
 
 type FragmentRootCardinality = 0 | 1 | 'multiple' | 'unknown';
@@ -473,8 +495,7 @@ function jsxChildRootCardinality(
   if (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child)) {
     return jsxRootCardinality(child, sf, knownContracts);
   }
-  if (ts.isJsxFragment(child)) return fragmentRootCardinality(child, sf, knownContracts);
-  return 'unknown';
+  return fragmentRootCardinality(child, sf, knownContracts);
 }
 
 function fragmentRootCardinality(
@@ -527,9 +548,8 @@ function fragmentComponentContract(
  * prevent elsewhere in these rules.
  *
  * Recognized by suffix because three's naming is regular here and the set is
- * open — every release adds materials and geometries, and an exhaustive list
- * would silently rot into false positives again. The three exact names are the
- * scene-level attachables that carry no suffix.
+ * open. The three exact names are the scene-level attachables that carry no
+ * suffix.
  */
 function isNonSpatialNativeTag(tag: string): boolean {
   if (/^[A-Z]/.test(tag)) return false;
@@ -678,7 +698,7 @@ function forwardedObjectProps(
  *
  * Optional chaining is part of the pattern, not an edge case: `useRef<
  * THREE.Group>(null)` types `.current` as nullable, so `body.current?.position
- * .copy(…)` is the ordinary spelling and `body.current.position.copy(…)` the
+ *.copy(…)` is the ordinary spelling and `body.current.position.copy(…)` the
  * non-null-asserted one. Both must read the same.
  */
 const RUNTIME_MOTION_MUTATION_RE =
@@ -743,7 +763,6 @@ function componentContract(
   }
 
   const opening = spatialRootOpening(expression);
-  if (!opening) return { root: 'unknown', transformProps: [] };
   const rootTag = opening.tagName.getText(sf);
   // A material/geometry/attribute root is not a spatial instance at all — see
   // `isNonSpatialNativeTag`. Classified here rather than suppressed at each
@@ -753,38 +772,15 @@ function componentContract(
   if (/^[A-Z]/.test(rootTag) && !delegated) return { root: 'unknown', transformProps: [] };
   if (delegated && delegated.root !== 'single') return delegated;
   const nativeRootTag = delegated?.rootTag ?? rootTag;
-  // A channel this component hands to the PHYSICS BINDING that places its root
-  // is forwarded exactly as truly as one written onto the root's own tag — the
-  // body is what puts the object in the world, so the callsite literal the hook
-  // reads IS this instance's placement (`r3f-physics-binding.ts`). Without this
-  // the contract said `Ramp` "does not forward position to its native root"
-  // and refused `<Ramp position={[2, -1, 168.55]} />`, the one literal in the
-  // whole chain that actually places the ramp.
+  // Physics spawn channels forwarded from component props contribute to its contract.
   const rootBinding = physicsBindings.get(opening);
-  // A channel the component's OWN `useFrame` drives through the body's api is
-  // NOT forwarded in any sense a write can rely on: the hook may read the
-  // callsite literal at spawn, but the per-frame driver has the last word and
-  // the authored value is dead on the next tick (racing-game's `Train` — a
-  // Kinematic body re-posed from its animated group every frame; the doctor's
-  // settle leg measured the authored spawn discarded, digit for digit). Those
-  // channels leave the forwarded set here, and the component is classified
-  // simulation-owned below, so a callsite write refuses with the sentence
-  // that names the real owner instead of persisting a literal that lies.
+  // Exclude channels driven each frame through the body API from writable forwarding.
   const apiDriven = (rootBinding?.apiDriven ?? []) as readonly string[];
   const toBinding = ((rootBinding?.forwarded ?? []) as readonly string[]).filter(
     (channel) => !apiDriven.includes(channel),
   );
   const declared = propForwarding(parameters[0], nativeRootTag, sf, typeAliases, builtinPropTypes);
-  // A GUARD WRAPPER spells its props AS the component it delegates to —
-  // `props: Parameters<typeof WeaponModelBody>[0]` — and spreads them whole.
-  // `typeAllowsStandardRootProps` reads type TEXT and aliases, so that spelling
-  // reads as "accepts no root props" and the wrapper was reported as forwarding
-  // nothing: first-person's `WeaponModel` (the hook-free discriminator check in
-  // front of `WeaponModelBody` that its own header documents, bought by runhuman
-  // pass 97) drew a permanent R3F002 telling the author to forward
-  // position/rotation/scale it already forwards, all three, through `{...props}`.
-  // The delegate's contract is resolved just above, so a wrapper whose props are
-  // SPELLED as the delegate's accepts exactly what the delegate accepts.
+  // A wrapper typed from its delegate accepts the delegate's root props.
   const forwarding =
     !declared.standardRootProps &&
     delegated &&
@@ -801,25 +797,16 @@ function componentContract(
   const forwardsVisible =
     toTag.includes('visible') && (!delegated || delegated.visibleProp === true);
 
-  // A built-in package contract may only ADD authorability. A component that
-  // returns an external component while forwarding no transform channel to it
-  // is exactly as opaque as it was before the table existed — reading the
-  // package's root as its own would claim a native root the component never
-  // routes anything to, and turn a silent unknown into a "does not forward"
-  // warning about source the author cannot act on.
+  // An external root contributes authorability only through forwarded channels.
+  // Keep wrappers opaque when they expose none of the package transform props.
   if (isBuiltinR3fContract(delegated) && transformProps.length === 0) {
     return { root: 'unknown', transformProps: [] };
   }
 
-  // WHICH of the forwarded channels a BODY reads, kept because the answer
-  // changes what an authored write has to survive (see `bodyForwarded`).
-  const bodyForwarded = transformProps.filter((channel) => toBinding.includes(channel));
-
   return {
     root: 'single',
     rootTag: nativeRootTag,
     transformProps,
-    ...(bodyForwarded.length > 0 ? { bodyForwarded } : {}),
     ...(forwardsVisible ? { visibleProp: true as const } : {}),
     ...simulationOwnership(opening, transformProps, motionRefs),
     // The api-driven case (see `apiDriven` above): the component drives its
@@ -864,8 +851,8 @@ function componentDefinitions(statement: ts.Statement): R3fComponentDefinition[]
 
 function collectR3fComponentContracts(
   sf: ts.SourceFile,
-  importedContracts: ReadonlyMap<string, R3fComponentContract> = new Map(),
-  importedTypeAliases: ReadonlyMap<string, R3fTypeAlias> = new Map(),
+  importedContracts: ReadonlyMap<string, R3fComponentContract>,
+  importedTypeAliases: ReadonlyMap<string, R3fTypeAlias>,
 ): Map<string, R3fComponentContract> {
   // Imported first, so a local declaration of the same name shadows it exactly
   // as JavaScript lexical scope does — the same rule `importedContracts`
@@ -931,7 +918,7 @@ export function analyzeR3fComponentContracts(
  * author states or the host EXECUTES, while a tag list is a guess about a file
  * whose imports it cannot see. What the scan is still for is telling an author
  * what the editor OBSERVED: the `OID003`/`OID004` messages in
- * `server/project-root-surface.ts` name the tags a file renders, and `OID004` —
+ * `serving/source-diagnostics.ts` name the tags a file renders, and `OID004` —
  * a file rendering both dialects' intrinsics, which one attribute cannot serve
  * — is nothing BUT this observation.
  *
@@ -939,7 +926,7 @@ export function analyzeR3fComponentContracts(
  * element sets, so nothing here can be a DOM tag. `line`, `points`, `sprite`,
  * `audio`, `color` and `fog` are all real R3F intrinsics but are EXCLUDED from
  * this list where SVG/HTML also spells them (`<line>`, `<audio>`) — the list is
- * evidence, not a catalogue, and a wrong entry would flip a genuine DOM file.
+ * evidence, not a catalogue; a wrong entry would falsely report R3F evidence in DOM source.
  * `[a-z][A-Za-z]*(Geometry|Material)` covers the whole geometry/material family
  * (`boxGeometry`, `meshStandardMaterial`, `shaderMaterial`, …) without naming
  * each one; the leading lowercase class is what keeps it from matching a
@@ -954,7 +941,7 @@ const R3F_ONLY_INTRINSIC_RE =
  *
  * DIAGNOSTIC EVIDENCE ONLY, on the same terms as the R3F list above: it
  * classifies no file. What a file renders is reported (`OID003`/`OID004` in
- * `server/project-root-surface.ts`); which region a file BELONGS to is a
+ * `serving/source-diagnostics.ts`); which region a file BELONGS to is a
  * declaration or a reach, never a property of its bytes. Excludes every name R3F also spells as an intrinsic
  * (`line`, `points`, `sprite`, `audio`, `color`, `fog`, `path`, `circle`), so
  * a hit here is unambiguous.
@@ -964,24 +951,13 @@ const DOM_ONLY_INTRINSIC_RE =
 
 function distinctTags(code: string, pattern: RegExp): string[] {
   const found = new Set<string>();
-  for (const match of code.matchAll(pattern)) if (match[1]) found.add(match[1]);
+  for (const match of code.matchAll(pattern)) found.add(match[1]!);
   return [...found];
 }
 
-/**
- * Drop line and block comments before the dialect scan, copying string
- * literals through untouched. The shipped case that bought this: the starter
- * dev-tools JSDoc names its command shape `cheat.<group>.<label>` — `group`
- * is an R3F-only intrinsic and `label` a DOM-only one, so ONE comment line
- * made a fresh scaffold boot with a dialect-mixing diagnostic about a file
- * with no JSX in it. A diagnostic channel agents are told to trust cannot
- * cry wolf over prose.
- *
- * Single pass, no AST — the transform-hook perf bar stands. Known residual
- * imprecision, accepted: a regex literal containing `//` or `/*` is misread
- * as a comment and drops the rest of itself — which degrades toward "no
- * evidence" (the safe default), never toward a fabricated tag.
- */
+/** Strip comments before dialect scanning and preserve quoted string literals.
+ * This bounded scan treats comment markers inside regex literals as comments,
+ * which can discard evidence but cannot fabricate a rendered tag. */
 function stripCommentsForScan(code: string): string {
   const kept: string[] = [];
   let i = 0;
@@ -1041,60 +1017,18 @@ export function sourceDialectEvidence(code: string): SourceDialectEvidence {
   };
 }
 
-/** True when a file's own bytes prove it authors for the R3F reconciler. */
+/** Whether the scan finds R3F import or intrinsic-tag evidence in this file. */
 export function sourceProvesR3f(evidence: SourceDialectEvidence): boolean {
   return evidence.reconcilerImport || evidence.r3fOnlyTags.length > 0;
 }
 
-/**
- * THE SOURCE-ID ATTRIBUTE for one file, decided by its REGION and nothing else.
- *
- * 1. **The region (authoritative).** `surface` is the answer
- *    `file-region-resolver.ts` gave for THIS file — a declaration the game
- *    made (a region `include` glob, a region `mounts` entry, or the manifest
- *    root whose `entry` this file is) or the region whose import closure
- *    reaches it. `'three'` stamps `userData-oid`; `'canvas'`/`'dom'` stamp
- *    `data-oid`. It is resolved from OUTSIDE the file, exactly where the fact
- *    lives, which is what makes it right for a world whose entry
- *    default-exports a component and does not import `@react-three/fiber`
- *    (legal: R3F's global JSX-intrinsics augmentation,
- *    or an entry composed entirely of already-typed child components, needs no
- *    import in THIS file). Every call site threads it from a context that
- *    resolved it per file: `binding-resolver.ts`'s per-surface resolvers, the
- *    browser bundle's own per-file resolution
- *    (`browser-transpile.ts`), and the dev server's
- *    `server/project-root-surface.ts` — shared with `classifyProjectHotUpdate`,
- *    the HMR half of this same decision, so the two cannot drift apart by hand.
- *
- * 2. **The DEFAULT.** When `surface` is `undefined` — no region placed the
- *    file (an ad-hoc file with no `volter.project.json` above it, or a module no
- *    region's import closure reaches and none declares) — the answer is
- *    `data-oid`, the documented default, and the CALLER says so out loud
- *    (`server/project-root-surface.ts`'s `OID001`/`OID002`). There is
- *    deliberately no source-text rung: a probe over a file's own bytes answered
- *    for a file it could not place, silently, and being wrong that way is
- *    indistinguishable from being right. Zero inference (ARCHITECTURE-CORE
- *    §The editor protocol) makes the fix a declaration — an `include` glob or
- *    a `mounts` entry in `editor/volter.adapter.ts` — not a better heuristic.
- *
- * Nothing about a file's own bytes outranks the region — not even a file that
- * renders THREE host elements while its region says `dom`. That disagreement is
- * FATAL rather than noisy (`data-oid` on a THREE object pierces inside fiber,
- * writes `object.data`, and throws on the next apply), which is exactly why it
- * is reported at full volume as declared-vs-measured DRIFT
- * (`server/project-root-surface.ts`'s `OID003`) and repaired by fixing the
- * declaration. A stamp derived from the bytes instead would make the
- * declaration untestable, which is how a wrong one stays invisible.
- *
- * Lives HERE, beside the transform it parameterizes, rather than in
- * `vite-plugin-ui-oid.ts` (which re-exports it for its existing callers):
- * a caller in a page reaches the same `transformSource`, and that path cannot
- * import a `node:fs`-bearing module.
- */
+/** Choose the source-ID attribute from the owning region: stage uses
+ * userData-oid; DOM, canvas, and unplaced files use data-oid. Source dialect
+ * diagnostics report disagreement without overriding the region declaration. */
 export function oidAttributeForSurface(
   declaredSurface?: DeclaredRootSurface,
 ): 'data-oid' | 'userData-oid' {
-  return declaredSurface === 'three' ? 'userData-oid' : 'data-oid';
+  return declaredSurface === 'stage' ? 'userData-oid' : 'data-oid';
 }
 
 /**
@@ -1142,49 +1076,18 @@ const SEEDED_USER_DATA_TAGS = new Set<string>([
 
 /** Options for {@link transformSource}. */
 export interface TransformSourceOptions {
-  /**
-   * The attribute name stamped on every JSX element (default `data-oid`).
-   * R3F-dialect files (spike W1) pass `userData-oid` instead:
-   * react-three-fiber's dashed-prop piercing writes `object.userData.oid`
-   * on the constructed Object3D at reconcile time — zero runtime cost, and
-   * the editor's R3F authoring adapter reads it back off the live scene
-   * graph. The OID→{file,line,col} index is attribute-agnostic (keyed by
-   * oid only), so every `/__ui-source/*` endpoint works unchanged for
-   * either dialect.
-   */
+  /** Attribute stamped on JSX elements. R3F uses userData-oid to place the
+   * identity on the constructed Three object; DOM uses data-oid. */
   attribute?: string;
-  /** Contracts for ordinary project-local imported component bindings. */
-  importedR3fContracts?: ReadonlyMap<string, R3fComponentContract>;
-  /** The prop-shape type aliases those same imports bring into scope. A
-   *  project that writes its canonical prop shape once and imports it is
-   *  otherwise read as forwarding nothing. */
-  importedR3fTypeAliases?: ReadonlyMap<string, R3fTypeAlias>;
   /** The file is mounted by @pixi/react. Local component callsites propagate
    * their OID onto the component's first native Pixi host, exactly as R3F
    * does with userData, but through ordinary data-* constructor fields. */
   canvasComponents?: boolean;
 }
 
-/**
- * The local names bound to drei's `<Html>` in this file — the ONE seam where a
- * three-surface file renders through **react-dom** instead of the R3F
- * reconciler. `<Html>` creates a real `<div>`, mounts a `createRoot` on it and
- * renders its children there, so every host element inside it is a DOM element
- * and the R3F-pierced identity props this transform stamps on host elements
- * (`userData-oid`, `userData-authoringInstance`, `userData-authoringLabel`,
- * and the `userData={{}}` seed) have nowhere to land.
- *
- * Measured: the starter template's own `BotHud` — screen-pinned dev chrome
- * built on `<Html>`, the documented way to put DOM in a Three world — logged
- * FOUR `React does not recognize the \`userData-…\` prop on a DOM element`
- * errors on every bot run, one per stamped prop. Inside an `<Html>` subtree we
- * therefore stamp `data-oid`, byte-for-byte what a `dom` root gets.
- *
- * Lexical by design: this reads the subtree written in THIS file, which is the
- * whole extent the transform can see. A component defined elsewhere and
- * rendered inside `<Html>` is transformed by its own pass against its own
- * declared surface.
- */
+/** Local JSX names imported as Drei Html. Its descendants render through
+ * react-dom and receive data-oid rather than R3F identity props. The decision
+ * is lexical to this file; imported components receive their own transform. */
 function dreiHtmlLocalNames(sf: ts.SourceFile): Set<string> {
   const names = new Set<string>();
   for (const statement of sf.statements) {
@@ -1203,36 +1106,10 @@ function dreiHtmlLocalNames(sf: ts.SourceFile): Set<string> {
   return names;
 }
 
-/**
- * Local JSX names bound by an import from an INSTALLED PACKAGE — every
- * specifier that is not relative (`./x`, `../x`), which is exactly the line
- * `r3f-project-contracts.ts`'s `resolveRelativeModule` already draws between
- * "source this editor walks" and "a dependency it never guesses about".
- *
- * Why the callsite stamp must skip them: `__volterOid`/`__volterLabel` are a
- * CONTRACT BETWEEN TWO HALVES OF THIS TRANSFORM. The callsite half writes
- * them; the only thing that ever reads them is the callee half —
- * `componentInstanceExpressions` destructuring them out of the component's own
- * parameters and re-emitting them as `userData-authoringInstance` on that
- * component's host elements. Nothing anywhere reads them off a React instance
- * or a DOM node. A package module is never served through this transform, so
- * the callee half never runs for it: the props have no reader by construction,
- * and the only thing they can still do is escape.
- *
- * And they do. Measured on the vendored `racing-game` ingest: `App.tsx` is a
- * MIXED file (an R3F `Scene` and a DOM `Hud` in one module, so the file's one
- * dialect is `userData-oid`), and its `<Canvas>` — `@react-three/fiber`'s own,
- * which spreads its rest props onto the `<div>` it wraps the canvas in — put
- * `__volterOid` and `__volterLabel` straight into the DOM, for two permanent
- * `React does not recognize the \`__volterOid\` prop on a DOM element` errors on
- * every mount of a real game. Nothing was lost by not stamping it, because
- * nothing was reading it.
- *
- * The one package component that DOES carry editor identity earns it through
- * the hand-audited contract table instead (`BUILTIN_R3F_CONTRACTS`), which
- * describes the native root the package forwards to — a claim about a specific
- * package's public API, never a guess made at a callsite.
- */
+/** Local names imported from installed packages. Those modules do not run
+ * the callee half of this transform, so private component-instance props
+ * would have no reader and could escape through rest-prop spreads. Known
+ * native Three wrappers receive host OID stamps at their own handling site. */
 function packageImportedLocalNames(sf: ts.SourceFile): Set<string> {
   const names = new Set<string>();
   for (const statement of sf.statements) {
@@ -1280,35 +1157,10 @@ function dreiCameraLocalNames(sf: ts.SourceFile): Set<string> {
   return names;
 }
 
-/**
- * Component-shaped JSX names bound by a function PARAMETER — the second way a
- * tag's callee is unknowable at transform time, and the same hazard as
- * {@link packageImportedLocalNames} for exactly the same reason.
- *
- * `__volterOid`/`__volterLabel` are a contract between two halves of this
- * transform: the callsite half writes them, the callee half destructures them
- * out of the component's own parameters. A tag bound to a parameter names
- * WHATEVER the caller passed, so this module cannot know whether the callee
- * half ever ran for it — and where it did not, the props' only remaining
- * behaviour is to escape into the DOM through any rest-prop spread.
- *
- * MEASURED on the vendored `racing-game` ingest, against the SERVED modules:
- * `useToggle.tsx`'s `<ToggledComponent {...props} />` (its `ToggledComponent`
- * is a parameter — drei's `Stats`/`OrbitControls`, cannon's `Debug`, or a
- * project component, depending on the call) and every R3F `*.stories.tsx`
- * decorator's `<Story />`. Two standing
- * `React does not recognize the \`__volterOid\` prop on a DOM element` errors on
- * every run of the acceptance portfolio.
- *
- * Nothing is lost by not stamping, and identity actually IMPROVES: a forwarder
- * spreads the caller's own props first, so the oid the REAL callsite wrote
- * (`<ToggledMap/>` in `App.tsx`) now reaches the wrapped component instead of
- * being overwritten by a literal naming the forwarder's own line.
- *
- * Scope is the whole file rather than lexical scope on purpose: a name that is
- * a parameter ANYWHERE in a module is not a stable component identity to stamp
- * against, and a per-scope walk would buy precision this decision does not use.
- */
+/** Component-shaped names bound by function parameters. Their callees are
+ * unknown to this transform, so preserve caller identity rather than adding
+ * private instance props that may escape to DOM hosts. Names are collected
+ * across the whole file, without resolving individual lexical scopes. */
 function parameterBoundLocalNames(sf: ts.SourceFile): Set<string> {
   const names = new Set<string>();
   const addBinding = (name: ts.BindingName): void => {
@@ -1359,16 +1211,6 @@ function reactFragmentNames(sf: ts.SourceFile): Set<string> {
   return names;
 }
 
-/**
- * Transform source: insert `data-oid="…"` (or `opts.attribute="…"`) on every
- * JSX element and register the index. In the R3F dialect, a custom component
- * callsite receives editor-only props whose values are propagated onto the
- * component's existing host Object3Ds. Every transformed project component,
- * on every surface, consumes those props at its parameter boundary so a
- * cross-surface component or ordinary `{...props}` spread cannot forward them
- * into game DOM. That preserves per-instance source identity without inserting
- * a wrapper into the native tree. Returns the transformed code + index entries.
- */
 /** Whether any JSX (an element, a self-closing element or a fragment) appears under `node`. */
 function containsJsx(node: ts.Node): boolean {
   let found = false;
@@ -1384,6 +1226,16 @@ function containsJsx(node: ts.Node): boolean {
   return found;
 }
 
+/**
+ * Transform source: insert `data-oid="…"` (or `opts.attribute="…"`) on every
+ * JSX element and register the index. In the R3F dialect, a custom component
+ * callsite receives editor-only props whose values are propagated onto the
+ * component's existing host Object3Ds. Object- and identifier-bound props
+ * consume those fields at the parameter boundary, so ordinary `{...props}`
+ * spreads do not forward them into project DOM. That preserves per-instance
+ * source identity without inserting a wrapper into the native tree. Returns
+ * the transformed code + index entries.
+ */
 export function transformSource(
   code: string,
   file: string,
@@ -1397,30 +1249,7 @@ export function transformSource(
     attribute === 'userData-oid' || opts?.canvasComponents === true;
   const sourceEdits: SourceEdit[] = [];
   const entries: OidEntry[] = [];
-  const r3fComponentContracts =
-    attribute === 'userData-oid'
-      ? collectR3fComponentContracts(sf, opts?.importedR3fContracts, opts?.importedR3fTypeAliases)
-      : new Map();
-  const physicsBindings =
-    attribute === 'userData-oid'
-      ? physicsBindingsByElement(sf)
-      : new Map<ts.JsxOpeningLikeElement, R3fPhysicsBinding>();
-  const jointBindings =
-    attribute === 'userData-oid'
-      ? jointBindingsByElement(sf)
-      : new Map<ts.JsxOpeningLikeElement, readonly R3fJointBinding[]>();
-  const particleBindings =
-    attribute === 'userData-oid'
-      ? particleBindingsByElement(sf)
-      : new Map<ts.JsxOpeningLikeElement, R3fParticleBinding>();
-  const lodBindings =
-    attribute === 'userData-oid'
-      ? lodBindingsByElement(sf)
-      : new Map<ts.JsxOpeningLikeElement, R3fLodBinding>();
-  const environmentBindings =
-    attribute === 'userData-oid'
-      ? environmentBindingsByElement(sf)
-      : new Map<ts.JsxOpeningLikeElement, R3fEnvironmentBinding>();
+  const detailedNames = attribute === 'userData-oid' ? dreiDetailedLocalNames(sf) : new Set<string>();
   const componentStack: Array<{
     name: string;
     instanceExpression: string;
@@ -1447,9 +1276,7 @@ export function transformSource(
         text: '__volterOid, __volterLabel, ',
       });
       // After the WHOLE parameter, including a type annotation:
-      // `({ name, ...props }: T)` must become `({ __volterOid, …, name, ...props }: T = {})`.
-      // Inserting at the binding's end produced `} = {}: T`, which is not
-      // TypeScript and broke every typed scene export the look verb imports.
+      // `({ name,...props }: T)` must become `({ __volterOid, …, name,...props }: T = {})`.
       if (!first.initializer) {
         sourceEdits.push({ pos: first.getEnd(), text: ' = {}' });
       }
@@ -1459,7 +1286,7 @@ export function transformSource(
       // Preserve the authored identifier as the REST binding. Code below the
       // parameter continues to read `props`, but it now sees only game props:
       // `function Card(props: Props)` becomes
-      // `function Card({ __volterOid, __volterLabel, ...props }: Props)`.
+      // `function Card({ __volterOid, __volterLabel,...props }: Props)`.
       // Remove an optional marker while replacing the identifier; a binding
       // pattern cannot itself be optional, so its equivalent is a `{}` default.
       sourceEdits.push({
@@ -1476,21 +1303,17 @@ export function transformSource(
   };
 
   const pushComponent = (
-    name: string | undefined,
-    parameters: ts.NodeArray<ts.ParameterDeclaration> | undefined,
+    name: string,
+    parameters: ts.NodeArray<ts.ParameterDeclaration>,
     body: ts.Node,
   ): boolean => {
-    if (!name || !/^[A-Z]/.test(name) || !parameters) return false;
-    // A capitalised function that renders no JSX is not a component, whatever its name: a table
-    // helper like `const PATCH = (key) => ({ key, … })` had its parameter rewritten into props
-    // destructuring and received an object of its string's characters. Nothing in it is stamped,
-    // and it consumes no transport props, so it is left as written.
+    if (!/^[A-Z]/.test(name)) return false;
+    // Only functions containing JSX consume the component transport props.
     if (!containsJsx(body)) return false;
     // Component membership participates in the stable OID signature on every
     // JSX dialect. Three/Canvas callsites inject the transport props, while
-    // every project component consumes them: a component declared on a DOM
-    // mount can therefore be called safely from a Three-region module without
-    // leaking editor metadata through its own rest props.
+    // supported props bindings consume them before spreading ordinary props
+    // into a DOM host.
     componentStack.push({ name, ...componentInstanceExpressions(parameters) });
     return true;
   };
@@ -1539,7 +1362,6 @@ export function transformSource(
       const tag = node.tagName.getText(sf);
       if (fragmentNames.has(tag)) {
         ts.forEachChild(node, visit);
-        if (pushed) componentStack.pop();
         return;
       }
       const componentContext = componentStack[componentStack.length - 1];
@@ -1553,10 +1375,6 @@ export function transformSource(
       // `dreiHtmlLocalNames`. Everything below reads this, not `attribute`.
       const elementAttribute = domSubtreeDepth > 0 ? 'data-oid' : attribute;
       const { line, character } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
-      const localContract =
-        elementAttribute === 'userData-oid' && /^[A-Z]/.test(tag)
-          ? r3fComponentContracts.get(tag)
-          : undefined;
       const entry: OidEntry = {
         file,
         line: line + 1,
@@ -1564,14 +1382,6 @@ export function transformSource(
         component,
         tag,
         authoredProps: authoredPropsOf(node, sf),
-        ...(localContract ? { r3fAuthoring: localContract } : {}),
-        ...(physicsBindings.has(node) ? { physicsBinding: physicsBindings.get(node)! } : {}),
-        ...(jointBindings.has(node) ? { jointBindings: jointBindings.get(node)! } : {}),
-        ...(particleBindings.has(node) ? { particleBinding: particleBindings.get(node)! } : {}),
-        ...(lodBindings.has(node) ? { lodBinding: lodBindings.get(node)! } : {}),
-        ...(environmentBindings.has(node)
-          ? { environmentBinding: environmentBindings.get(node)! }
-          : {}),
         ...(jsxStack.length > 0 ? { parentOid: jsxStack[jsxStack.length - 1]! } : {}),
       };
       store.index.set(oid, entry);
@@ -1581,51 +1391,47 @@ export function transformSource(
         (elementAttribute === 'userData-oid' || opts?.canvasComponents === true) &&
         /^[A-Z]/.test(tag);
       if (isProjectCustomComponent) {
-        const element = ts.isJsxOpeningElement(node) ? node.parent : node;
-        if (ts.isJsxElement(element) || ts.isJsxSelfClosingElement(element)) {
-          // An installed package's module never passes through this transform,
-          // so the callee half of the `__volterOid` contract never runs for it and
-          // the props can only escape (into the DOM, via any package component
-          // that spreads its rest props onto a host element). The callsite is
-          // still INDEXED above — the source entry, its parent and its contract
-          // are unchanged; only the unreadable runtime prop is withheld. See
-          // {@link packageImportedLocalNames}.
-          if (packageNames.has(tag.split('.')[0] ?? tag)) {
-            // Detailed and the two Drei cameras spread their remaining props
-            // onto a native Three host, where the ordinary R3F OID belongs.
-            if (lodBindings.has(node) || dreiCameraNames.has(tag)) {
-              sourceEdits.push({ pos: node.attributes.end, text: ` userData-oid="${oid}"` });
-            }
-            ts.forEachChild(node, visit);
-            if (pushed) componentStack.pop();
-            return;
-          }
-          // A tag bound to a PARAMETER names whatever the caller passed, so the
-          // callee half may never have run for it either — same withholding,
-          // same reason, and the callsite stays indexed. See
-          // {@link parameterBoundLocalNames}.
-          if (parameterNames.has(tag.split('.')[0] ?? tag)) {
-            ts.forEachChild(node, visit);
-            if (pushed) componentStack.pop();
-            return;
+        const tagRoot = tag.split('.')[0]!;
+        // An installed package's module never passes through this transform,
+        // so the callee half of the `__volterOid` contract never runs for it and
+        // the props can only escape (into the DOM, via any package component
+        // that spreads its rest props onto a host element). The callsite is
+        // still INDEXED above — the source entry, its parent and its contract
+        // are unchanged; only the unreadable runtime prop is withheld. See
+        // {@link packageImportedLocalNames}.
+        if (packageNames.has(tagRoot)) {
+          // Detailed and the two Drei cameras spread their remaining props
+          // onto a native Three host, where the ordinary R3F OID belongs.
+          if (detailedNames.has(tag) || dreiCameraNames.has(tag)) {
+            sourceEdits.push({ pos: node.attributes.end, text: ` userData-oid="${oid}"` });
           }
-          const authoredName = node.attributes.properties.find(
-            (property): property is ts.JsxAttribute =>
-              ts.isJsxAttribute(property) && property.name.getText(sf) === 'name',
-          );
-          const label =
-            authoredName?.initializer && ts.isStringLiteral(authoredName.initializer)
-              ? authoredName.initializer.text
-              : tag;
-          const labelAttribute =
-            authoredName?.initializer && ts.isJsxExpression(authoredName.initializer)
-              ? `__volterLabel={${authoredName.initializer.expression?.getText(sf) ?? JSON.stringify(tag)}}`
-              : `__volterLabel=${JSON.stringify(label)}`;
-          sourceEdits.push({
-            pos: node.attributes.end,
-            text: ` __volterOid="${oid}" ${labelAttribute}`,
-          });
+          ts.forEachChild(node, visit);
+          return;
+        }
+        // A tag bound to a PARAMETER names whatever the caller passed, so the
+        // callee half may never have run for it either — same withholding,
+        // same reason, and the callsite stays indexed. See
+        // {@link parameterBoundLocalNames}.
+        if (parameterNames.has(tagRoot)) {
+          ts.forEachChild(node, visit);
+          return;
         }
+        const authoredName = node.attributes.properties.find(
+          (property): property is ts.JsxAttribute =>
+            ts.isJsxAttribute(property) && property.name.getText(sf) === 'name',
+        );
+        const label =
+          authoredName?.initializer && ts.isStringLiteral(authoredName.initializer)
+            ? authoredName.initializer.text
+            : tag;
+        const labelAttribute =
+          authoredName?.initializer && ts.isJsxExpression(authoredName.initializer)
+            ? `__volterLabel={${authoredName.initializer.expression?.getText(sf) ?? JSON.stringify(tag)}}`
+            : `__volterLabel=${JSON.stringify(label)}`;
+        sourceEdits.push({
+          pos: node.attributes.end,
+          text: ` __volterOid="${oid}" ${labelAttribute}`,
+        });
       } else {
         // Host elements carry their identity directly.
         // Append after authored attributes. In R3F, an authored `userData={{…}}`
@@ -1651,24 +1457,9 @@ export function transformSource(
         }
         if (
           elementAttribute === 'userData-oid' &&
-          // NEVER on `<primitive>`. Its object is the GAME's, constructed before
-          // React ever sees it, and `userData={{}}` REPLACES that object's own
-          // `userData` wholesale — measured: a root carrying
-          // `markComponentRoot(node, 'Stage')` from its constructor came out of
-          // mount with nothing but the three editor keys, so every hierarchy
-          // mark a class-owned root sets was destroyed by the editor's own
-          // serve-time transform. An adopted object always HAS a `userData`
-          // (three sets one on every Object3D/geometry/material), which is
-          // precisely why the initializer below is unnecessary here and
-          // destructive. That initializer's real subjects are the resources R3F
-          // itself constructs.
+          // Primitive objects already own userData. Do not replace it when adopting an object.
           tag !== 'primitive' &&
-          // ONLY where the constructed object has no `userData` of its own. The
-          // seed is a new `{}` on every render, and Fiber REPLACES `userData`
-          // whenever that prop changes: seeded on an Object3D, a material or a
-          // custom host, it wiped what the game kept there on each rerender
-          // (measured: a mesh's `userData.probe`, set once on mount, gone after
-          // 13 renders, leaving only the editor's keys).
+          // Seed userData only on host types that do not construct their own object.
           SEEDED_USER_DATA_TAGS.has(tag) &&
           !node.attributes.properties.some(
             (property) => ts.isJsxAttribute(property) && property.name.getText(sf) === 'userData',
@@ -1699,7 +1490,6 @@ export function transformSource(
       if (opensDomSubtree) domSubtreeDepth--;
       if (enclosingOid !== undefined) jsxStack.pop();
       visit(node.closingElement);
-      if (pushed) componentStack.pop();
       return;
     }