@volter/editor-core 0.5.57

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

@@ -0,0 +1,327 @@
+/**
+ * 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).
+ */
+
+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 {
+  visible: Map<string, R3fComponentContract>;
+  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;
+
+/** What a resolver needs from its host. Paths are whatever vocabulary the host
+ *  speaks (absolute on the server, project-relative in storage); the resolver
+ *  only passes them back. */
+export interface ContractHost {
+  /** The file's text, or null when it cannot be read. */
+  read(file: string): string | null;
+  exists(file: string): boolean;
+  /** `dirname(fromFile)` joined with a relative specifier, normalized. */
+  resolve(fromFile: string, specifier: string): string;
+  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;
+}
+
+function resolveRelativeModule(
+  host: ContractHost,
+  fromFile: string,
+  specifier: string,
+): string | null {
+  if (!specifier.startsWith('.')) return null;
+  const base = host.resolve(fromFile, specifier);
+  const candidates = host.extname(base)
+    ? [base]
+    : [
+        ...SOURCE_EXTENSIONS.map((extension) => `${base}${extension}`),
+        ...SOURCE_EXTENSIONS.map((extension) => host.join(base, `index${extension}`)),
+      ];
+  return candidates.find((candidate) => host.exists(candidate)) ?? null;
+}
+
+/** The project-local module a `import { … } from './x'` statement names, with
+ *  its binding elements — or null when the statement is not one of those. */
+function relativeNamedImport(
+  host: ContractHost,
+  statement: ts.Statement,
+  file: string,
+): { target: string; elements: readonly ts.ImportSpecifier[] } | null {
+  if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) {
+    return null;
+  }
+  const target = resolveRelativeModule(host, file, statement.moduleSpecifier.text);
+  const bindings = statement.importClause?.namedBindings;
+  if (!target || !bindings || !ts.isNamedImports(bindings)) return null;
+  return { target, elements: bindings.elements };
+}
+
+export class ProjectContractResolver {
+  private readonly cache = new Map<string, ModuleAnalysis>();
+  private readonly visiting = new Set<string>();
+
+  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);
+    // `analyzeR3fComponentContracts` re-parses `code`, so the aliases below
+    // must be resolved against the file each was WRITTEN in, not against this
+    // one — that pairing is what `R3fTypeAlias` carries.
+    const visible = analyzeR3fComponentContracts(
+      code,
+      file,
+      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,
+      ),
+    };
+  }
+
+  private analyzeFile(file: string): ModuleAnalysis {
+    const cached = this.cache.get(file);
+    if (cached) return cached;
+    if (this.visiting.has(file)) {
+      return {
+        visible: new Map(),
+        exported: new Map(),
+        exportedTypeAliases: new Map(),
+        exportedProps: new Map(),
+      };
+    }
+    this.visiting.add(file);
+    try {
+      const analyze = (): ModuleAnalysis => {
+        const source = this.host.read(file);
+        return source === null
+          ? {
+              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();
+      this.cache.set(file, analysis);
+      return analysis;
+    } finally {
+      this.visiting.delete(file);
+    }
+  }
+
+  /**
+   * 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.
+   */
+  private importedTypeAliases(sf: ts.SourceFile, file: string): Map<string, R3fTypeAlias> {
+    const aliases = new Map<string, R3fTypeAlias>();
+    for (const statement of sf.statements) {
+      const named = relativeNamedImport(this.host, statement, file);
+      if (!named) continue;
+      const exported = this.analyzeFile(named.target).exportedTypeAliases;
+      for (const element of named.elements) {
+        const alias = exported.get(element.propertyName?.text ?? element.name.text);
+        if (alias) aliases.set(element.name.text, alias);
+      }
+    }
+    return aliases;
+  }
+
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one bounded import-declaration pass keeps alias/default/named binding resolution together.
+  private importedBindings(sf: ts.SourceFile, file: string): Map<string, R3fComponentContract> {
+    const imported = new Map<string, R3fComponentContract>();
+    for (const statement of sf.statements) {
+      if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) {
+        continue;
+      }
+      const target = resolveRelativeModule(this.host, file, statement.moduleSpecifier.text);
+      if (!target) {
+        // An installed package has no source here to walk. It contributes a
+        // contract only when the hand-audited built-in table names it; every
+        // other external binding stays conservative.
+        for (const [name, contract] of builtinR3fContractsOfImport(statement)) {
+          imported.set(name, contract);
+        }
+        continue;
+      }
+      if (!statement.importClause) continue;
+      const exported = this.analyzeFile(target).exported;
+      const defaultName = statement.importClause.name?.text;
+      const defaultContract = exported.get('default');
+      if (defaultName && defaultContract) imported.set(defaultName, defaultContract);
+      const bindings = statement.importClause.namedBindings;
+      if (!bindings || !ts.isNamedImports(bindings)) continue;
+      for (const element of bindings.elements) {
+        const contract = exported.get(element.propertyName?.text ?? element.name.text);
+        if (contract) imported.set(element.name.text, contract);
+      }
+    }
+    return imported;
+  }
+
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: this is a bounded TypeScript export-syntax dispatcher, not application control flow.
+  private exportsOf<T>(
+    sf: ts.SourceFile,
+    file: string,
+    visible: ReadonlyMap<string, T>,
+    moduleExports: (target: string) => ReadonlyMap<string, T>,
+  ): Map<string, T> {
+    const exported = new Map<string, T>();
+    for (const statement of sf.statements) {
+      if (
+        (ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) &&
+        statement.name &&
+        hasModifier(statement, ts.SyntaxKind.ExportKeyword)
+      ) {
+        const contract = visible.get(statement.name.text);
+        if (contract) {
+          exported.set(
+            hasModifier(statement, ts.SyntaxKind.DefaultKeyword) ? 'default' : statement.name.text,
+            contract,
+          );
+        }
+      }
+      if (
+        ts.isVariableStatement(statement) &&
+        hasModifier(statement, ts.SyntaxKind.ExportKeyword)
+      ) {
+        for (const declaration of statement.declarationList.declarations) {
+          if (!ts.isIdentifier(declaration.name)) continue;
+          const contract = visible.get(declaration.name.text);
+          if (contract) exported.set(declaration.name.text, contract);
+        }
+      }
+      if (ts.isExportAssignment(statement) && ts.isIdentifier(statement.expression)) {
+        const contract = visible.get(statement.expression.text);
+        if (contract) exported.set('default', contract);
+      }
+      if (!ts.isExportDeclaration(statement)) continue;
+      const target =
+        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.
+      if (!statement.exportClause) {
+        if (!target) continue;
+        for (const [name, contract] of moduleExports(target)) {
+          if (name !== 'default') exported.set(name, contract);
+        }
+        continue;
+      }
+      const sourceContracts = target ? moduleExports(target) : visible;
+      if (!ts.isNamedExports(statement.exportClause)) continue;
+      for (const element of statement.exportClause.elements) {
+        const sourceName = element.propertyName?.text ?? element.name.text;
+        const contract = sourceContracts.get(sourceName);
+        if (contract) exported.set(element.name.text, contract);
+      }
+    }
+    return exported;
+  }
+}

package/src/ui-source/r3f-diagnostic-index.ts

@@ -0,0 +1,165 @@
+/**
+ * "warnings live on the row".
+ *
+ * The join that carries an R3F authorability diagnostic from where it is
+ * PRODUCED (a whole-file analysis, `r3fAuthoringDiagnostics`) to where it is
+ * READ (one hierarchy row). Pure, browser-safe, and unit-testable without a
+ * dev server: the two halves below are the entire mapping, and both the
+ * server-side annotator (`currentOidIndex`, `vite-plugin-ui-oid.ts`) and the
+ * client-side reader (`R3fSourceAuthoringAdapter.diagnosticsFor`) call one of
+ * them rather than re-deriving it.
+ *
+ * ## Why the join is by IDENTITY the index already holds, never by name
+ *
+ * Before H5 these diagnostics reached exactly one place: the dev server's
+ * terminal (and the `/__editor/state` warnings map), formatted to a string by
+ * `server/project-validation.ts`'s `validateSource`. A string in a log has no
+ * row identity at all, so the first question was what identity to give it.
+ *
+ * A diagnostic carries `{file, line, col, component}`. An `OidEntry` carries
+ * `{file, line, col, component, tag}` — where `component` is the component
+ * whose BODY lexically contains the element. Those two `component` fields mean
+ * the same thing on the definition side, and both positions come from
+ * `node.getStart()`, so the entry-side selection below needs no name
+ * resolution, no import walking, and no second derivation that could disagree
+ * with the first:
+ *
+ * - **at this element** — the diagnostic's `(file,line,col)` IS this entry's.
+ *   That is R3F004 ("`<Enemy>` has no name"), whose subject is the callsite
+ *   element itself. (R3F002/3/5 point at a function/variable NAME identifier
+ *   or a `ref={…}` identifier, never at a `<`, so they can never collide with
+ *   an element position and be misread as this kind.)
+ * - **inside this component** — the diagnostic names the component whose body
+ *   contains this element (`d.component === entry.component`, same file). That
+ *   is R3F002/R3F003/R3F005, which are ABOUT a definition.
+ *
+ * The second rule is what gets a definition-side warning onto an INSTANCE row
+ * in another file, and it needs no cross-file resolution: the oid transform
+ * stamps a component boundary with BOTH its callsite oid
+ * (`userData.authoringInstance`) and its definition-root oid (`userData.oid`),
+ * so the client already holds both index entries for one row — the same two
+ * entries H3's `sourceLocation`/`definitionLocation` return. {@link
+ * mergeRowDiagnostics} unions them.
+ *
+ * ## Why this cannot drift from index freshness
+ *
+ * It is not a separate channel. The diagnostics are attached to the entries of
+ * the very payload `refreshSourceState()` already fetches, computed in the same
+ * pass from the same file bytes. There is no second fetch to fall behind, no
+ * cache to invalidate, and no clock of its own: whatever makes the index stale
+ * makes them stale together, and whatever refreshes it refreshes them.
+ *
+ * ## A diagnostic that lands on no row does not vanish
+ *
+ * Some will not reach a row, and that is expected rather than a hole to be
+ * plugged: a component defined but never instantiated has no live object, a
+ * component whose definition file is not stamped as R3F is never analyzed here
+ * at all, and a hosted (no-dev-server) session has no analyzer (see
+ * `browser-oid-index.ts`). Nothing is LOST in any of those cases — this join is
+ * PURELY ADDITIVE. The channel these diagnostics have always had is untouched:
+ * `server/project-validation.ts`'s `validateSource` still formats every one of
+ * them into the dev server's terminal warning block and into the project
+ * warnings map that `/__editor/state` (and so `vgai status`) reports. Rows are
+ * a second, better-placed audience, not a replacement.
+ */
+
+import type { OidEntry, R3fAuthoringDiagnostic } from './oid-transform';
+
+/** The per-entry selector {@link fileDiagnosticJoin} builds. */
+export type EntryDiagnosticSelector = (
+  entry: Pick<OidEntry, 'line' | 'col' | 'component' | 'parentOid'>,
+) => R3fAuthoringDiagnostic[] | undefined;
+
+const position = (at: { line: number; col: number }): string => `${at.line}:${at.col}`;
+
+/**
+ * Build the selector for ONE file: which of that file's diagnostics pertain to
+ * each of that file's oid entries. Both arguments must belong to the same
+ * file — the caller already has them grouped that way, so nothing here
+ * re-filters by file.
+ *
+ * The two rules of the module doc are applied as a PARTITION, not as an `||`,
+ * and that distinction is load-bearing. A diagnostic whose position is one of
+ * this file's stamped elements is ABOUT that element (R3F004); everything else
+ * is about a component definition (R3F002/3/5). Without the partition, an
+ * R3F004 on `<Enemy>` in a file that ALSO defines `Enemy` would match the
+ * component rule too and badge every element inside `Enemy`'s body — a warning
+ * about one callsite smeared across the definition's internals.
+ *
+ * Deriving the split from the data (does this position name a stamped
+ * element?) rather than from a hand-kept list of which codes are
+ * callsite-scoped is deliberate: a new R3F00x code classifies itself.
+ *
+ * The component rule additionally lands on that component's ROOT element only
+ * — the outermost stamped element of its body, recognized through `parentOid`
+ * (no parent, or a parent belonging to a different component). Two reasons,
+ * one practical and one exact: a definition's internals are not what an author
+ * is being warned about, and the root element is PRECISELY the entry an
+ * instance row reaches, because that oid is what the transform stamps on the
+ * boundary object as `userData.oid`. Anything looser would badge every
+ * `<mesh>` inside the component as well.
+ *
+ * The returned selector yields a fresh array, or `undefined` when nothing
+ * pertains — so the caller omits the field entirely instead of shipping an
+ * empty array on every entry.
+ */
+export function fileDiagnosticJoin(
+  fileEntries: ReadonlyMap<string, OidEntry>,
+  fileDiagnostics: readonly R3fAuthoringDiagnostic[],
+): EntryDiagnosticSelector {
+  if (fileDiagnostics.length === 0) return () => undefined;
+  const elementPositions = new Set<string>();
+  for (const [, entry] of fileEntries) elementPositions.add(position(entry));
+
+  const atElement: R3fAuthoringDiagnostic[] = [];
+  const aboutComponent: R3fAuthoringDiagnostic[] = [];
+  for (const diagnostic of fileDiagnostics) {
+    (elementPositions.has(position(diagnostic)) ? atElement : aboutComponent).push(diagnostic);
+  }
+
+  const isComponentRoot = (entry: Pick<OidEntry, 'component' | 'parentOid'>): boolean => {
+    if (entry.parentOid === undefined) return true;
+    return fileEntries.get(entry.parentOid)?.component !== entry.component;
+  };
+
+  return (entry) => {
+    const pertinent = [
+      ...atElement.filter((d) => d.line === entry.line && d.col === entry.col),
+      ...(entry.component === null || !isComponentRoot(entry)
+        ? []
+        : aboutComponent.filter((d) => d.component === entry.component)),
+    ];
+    return pertinent.length > 0 ? pertinent : undefined;
+  };
+}
+
+/** Stable identity of one diagnostic, for the union below. Code + position is
+ *  exact: two diagnostics of the same code at the same place ARE the same
+ *  finding reached through two entries, which is the normal case when a
+ *  component is defined and instantiated in one file. */
+function diagnosticKey(diagnostic: R3fAuthoringDiagnostic): string {
+  return `${diagnostic.code}|${diagnostic.file}|${diagnostic.line}|${diagnostic.col}`;
+}
+
+/**
+ * Union of the diagnostics reachable from one ROW's index entries — its
+ * callsite entry and its definition-root entry — in that order, deduped.
+ * `undefined`/absent entries are skipped, so a row with only one of the two
+ * (a plain host element; an instance whose index entry has not landed) is the
+ * ordinary case, not a special one.
+ */
+export function mergeRowDiagnostics(
+  ...entries: ReadonlyArray<Pick<OidEntry, 'diagnostics'> | undefined>
+): R3fAuthoringDiagnostic[] {
+  const seen = new Set<string>();
+  const merged: R3fAuthoringDiagnostic[] = [];
+  for (const entry of entries) {
+    for (const diagnostic of entry?.diagnostics ?? []) {
+      const key = diagnosticKey(diagnostic);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      merged.push(diagnostic);
+    }
+  }
+  return merged;
+}

package/src/ui-source/r3f-environment-binding.ts

@@ -0,0 +1,133 @@
+/** Exact source tokens for native R3F scene attachments.
+ *
+ * These are not a VGAI environment format. `<color attach="background">`,
+ * `<fog attach="fog">`, and `<fogExp2 attach="fog">` are ordinary Fiber
+ * projections of THREE.Scene properties. The live Scene remains runtime truth;
+ * this metadata only identifies literal constructor arguments that can be
+ * changed without interpreting arbitrary project code.
+ */
+
+import ts from 'typescript';
+import { jsxAttribute, numericLiteral } from './ts-ast';
+
+export interface R3fEnvironmentNumberBinding {
+  readonly value: number;
+  readonly start: number;
+  readonly end: number;
+}
+
+export interface R3fEnvironmentStringBinding {
+  readonly value: string;
+  readonly start: number;
+  readonly end: number;
+  readonly quote: "'" | '"' | '`';
+}
+
+export type R3fEnvironmentBinding =
+  | {
+      readonly kind: 'background-color';
+      readonly color?: R3fEnvironmentStringBinding;
+    }
+  | {
+      readonly kind: 'fog';
+      readonly color?: R3fEnvironmentStringBinding;
+      readonly near?: R3fEnvironmentNumberBinding;
+      readonly far?: R3fEnvironmentNumberBinding;
+    }
+  | {
+      readonly kind: 'fog-exp2';
+      readonly color?: R3fEnvironmentStringBinding;
+      readonly density?: R3fEnvironmentNumberBinding;
+    };
+
+function attributeString(attribute: ts.JsxAttribute | undefined): string | undefined {
+  const initializer = attribute?.initializer;
+  if (!initializer) return undefined;
+  if (ts.isStringLiteral(initializer)) return initializer.text;
+  const expression = ts.isJsxExpression(initializer) ? initializer.expression : undefined;
+  return expression &&
+    (ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression))
+    ? expression.text
+    : undefined;
+}
+
+function args(element: ts.JsxOpeningLikeElement): readonly ts.Expression[] | undefined {
+  const initializer = jsxAttribute(element, 'args')?.initializer;
+  const expression =
+    initializer && ts.isJsxExpression(initializer) ? initializer.expression : undefined;
+  return expression && ts.isArrayLiteralExpression(expression)
+    ? expression.elements.filter(ts.isExpression)
+    : undefined;
+}
+
+function numberBinding(
+  expression: ts.Expression | undefined,
+  sf: ts.SourceFile,
+): R3fEnvironmentNumberBinding | undefined {
+  if (!expression) return undefined;
+  const value = numericLiteral(expression);
+  return value === undefined
+    ? undefined
+    : { value, start: expression.getStart(sf), end: expression.getEnd() };
+}
+
+function stringBinding(
+  expression: ts.Expression | undefined,
+  sf: ts.SourceFile,
+): R3fEnvironmentStringBinding | undefined {
+  if (
+    !expression ||
+    (!ts.isStringLiteral(expression) && !ts.isNoSubstitutionTemplateLiteral(expression))
+  ) {
+    return undefined;
+  }
+  const start = expression.getStart(sf);
+  const quote = sf.text[start];
+  if (quote !== "'" && quote !== '"' && quote !== '`') return undefined;
+  return { value: expression.text, start, end: expression.getEnd(), quote };
+}
+
+/** Bind recognized native scene attachments, including dynamic ones. Dynamic
+ * arguments deliberately produce a binding with missing tokens: the World
+ * Inspector can still identify the native mode but must keep that field
+ * read-only. */
+export function environmentBindingsByElement(
+  sf: ts.SourceFile,
+): Map<ts.JsxOpeningLikeElement, R3fEnvironmentBinding> {
+  const result = new Map<ts.JsxOpeningLikeElement, R3fEnvironmentBinding>();
+  const visit = (node: ts.Node): void => {
+    if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) {
+      const tag = node.tagName.getText(sf);
+      const attachedTo = attributeString(jsxAttribute(node, 'attach'));
+      const values = args(node);
+      if (tag === 'color' && attachedTo === 'background') {
+        const color = stringBinding(values?.[0], sf);
+        result.set(node, {
+          kind: 'background-color',
+          ...(color ? { color } : {}),
+        });
+      } else if (tag === 'fog' && attachedTo === 'fog') {
+        const color = stringBinding(values?.[0], sf);
+        const near = numberBinding(values?.[1], sf);
+        const far = numberBinding(values?.[2], sf);
+        result.set(node, {
+          kind: 'fog',
+          ...(color ? { color } : {}),
+          ...(near ? { near } : {}),
+          ...(far ? { far } : {}),
+        });
+      } else if (tag === 'fogExp2' && attachedTo === 'fog') {
+        const color = stringBinding(values?.[0], sf);
+        const density = numberBinding(values?.[1], sf);
+        result.set(node, {
+          kind: 'fog-exp2',
+          ...(color ? { color } : {}),
+          ...(density ? { density } : {}),
+        });
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return result;
+}