@volter/editor-react 0.5.66

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

@@ -0,0 +1,228 @@
+/**
+ * Source addresses for native `@react-three/rapier` impulse joints.
+ *
+ * A joint hook has no JSX node of its own, so it cannot carry an OID. The two
+ * `<RigidBody ref={…}>` elements are its existing source anchors. This analysis
+ * joins a package-recognized hook to those elements inside the same lexical
+ * component and records only JSON-shaped data on their OID entries. Literal
+ * hook parameters can be written back in place; computed parameters remain
+ * identifiable but deliberately read-only.
+ */
+
+import ts from 'typescript';
+import { enclosingScope, numericLiteral, refIdentifier } from './ts-ast';
+
+import type { R3fJointBinding, R3fJointHook, R3fJointLiteral, R3fJointLiteralRange } from '@volter/editor-sdk/source-authoring';
+export type { R3fJointBinding, R3fJointHook, R3fJointLiteral, R3fJointLiteralRange } from '@volter/editor-sdk/source-authoring';
+
+const JOINT_HOOKS = new Set<R3fJointHook>([
+  'useFixedJoint',
+  'useSphericalJoint',
+  'useRevoluteJoint',
+  'usePrismaticJoint',
+  'useRopeJoint',
+  'useSpringJoint',
+]);
+
+function rapierNamedImports(statement: ts.Statement): readonly ts.ImportSpecifier[] {
+  if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) {
+    return [];
+  }
+  if (statement.moduleSpecifier.text !== '@react-three/rapier') return [];
+  const bindings = statement.importClause?.namedBindings;
+  return bindings && ts.isNamedImports(bindings) ? bindings.elements : [];
+}
+
+function imports(sf: ts.SourceFile): {
+  hooks: Map<string, R3fJointHook>;
+  rigidBodies: Set<string>;
+} {
+  const hooks = new Map<string, R3fJointHook>();
+  const rigidBodies = new Set<string>();
+  for (const statement of sf.statements) {
+    for (const element of rapierNamedImports(statement)) {
+      const imported = element.propertyName?.text ?? element.name.text;
+      if (imported === 'RigidBody') rigidBodies.add(element.name.text);
+      if (JOINT_HOOKS.has(imported as R3fJointHook)) {
+        hooks.set(element.name.text, imported as R3fJointHook);
+      }
+    }
+  }
+  return { hooks, rigidBodies };
+}
+
+type BodyIndex = Map<ts.FunctionLikeDeclaration | null, Map<string, ts.JsxOpeningLikeElement[]>>;
+
+interface JointBindingPair {
+  readonly first: ts.JsxOpeningLikeElement;
+  readonly second: ts.JsxOpeningLikeElement;
+  readonly binding: Omit<R3fJointBinding, 'endpoint'>;
+}
+
+function bindingPairForCall(
+  call: ts.CallExpression,
+  sf: ts.SourceFile,
+  hooks: ReadonlyMap<string, R3fJointHook>,
+  bodies: BodyIndex,
+): JointBindingPair | null {
+  if (!ts.isIdentifier(call.expression)) return null;
+  const hook = hooks.get(call.expression.text);
+  const body1 = call.arguments[0];
+  const body2 = call.arguments[1];
+  const paramsExpression = call.arguments[2];
+  if (!hook || !body1 || !body2 || !paramsExpression) return null;
+  if (!ts.isIdentifier(body1) || !ts.isIdentifier(body2)) return null;
+  const scopeBodies = bodies.get(enclosingScope(call));
+  const first = scopeBodies?.get(body1.text);
+  const second = scopeBodies?.get(body2.text);
+  // More than one element using one ref is not a writable address.
+  if (first?.length !== 1 || second?.length !== 1) return null;
+  const literal = literalValue(paramsExpression);
+  const params = Array.isArray(literal) && validParams(hook, literal) ? literal : undefined;
+  const ranges = params ? literalRanges(paramsExpression) : undefined;
+  const { line, character } = sf.getLineAndCharacterOfPosition(call.getStart(sf));
+  return {
+    first: first[0]!,
+    second: second[0]!,
+    binding: {
+      hook,
+      line: line + 1,
+      col: character,
+      body1Ref: body1.text,
+      body2Ref: body2.text,
+      ...(params
+        ? {
+            params,
+            ...(Array.isArray(ranges) ? { paramRanges: ranges } : {}),
+          }
+        : {}),
+    },
+  };
+}
+
+function literalValue(expression: ts.Expression): R3fJointLiteral | undefined {
+  const numeric = numericLiteral(expression);
+  if (numeric !== undefined) return numeric;
+  if (expression.kind === ts.SyntaxKind.TrueKeyword) return true;
+  if (expression.kind === ts.SyntaxKind.FalseKeyword) return false;
+  if (!ts.isArrayLiteralExpression(expression)) return undefined;
+  const result: R3fJointLiteral[] = [];
+  for (const element of expression.elements) {
+    if (ts.isSpreadElement(element) || ts.isOmittedExpression(element)) return undefined;
+    const value = literalValue(element);
+    if (value === undefined) return undefined;
+    result.push(value);
+  }
+  return result;
+}
+
+function literalRanges(expression: ts.Expression): R3fJointLiteralRange | undefined {
+  if (numericLiteral(expression) !== undefined) {
+    return { start: expression.getStart(), end: expression.getEnd() };
+  }
+  if (
+    expression.kind === ts.SyntaxKind.TrueKeyword ||
+    expression.kind === ts.SyntaxKind.FalseKeyword
+  ) {
+    return { start: expression.getStart(), end: expression.getEnd() };
+  }
+  if (!ts.isArrayLiteralExpression(expression)) return undefined;
+  const result: R3fJointLiteralRange[] = [];
+  for (const element of expression.elements) {
+    if (ts.isSpreadElement(element) || ts.isOmittedExpression(element)) return undefined;
+    const range = literalRanges(element);
+    if (!range) return undefined;
+    result.push(range);
+  }
+  return result;
+}
+
+function validParams(hook: R3fJointHook, params: readonly R3fJointLiteral[]): boolean {
+  const vec = (value: R3fJointLiteral | undefined, length: number): boolean =>
+    Array.isArray(value) &&
+    value.length === length &&
+    value.every((part) => typeof part === 'number');
+  switch (hook) {
+    case 'useFixedJoint':
+      return (
+        params.length === 4 &&
+        vec(params[0], 3) &&
+        vec(params[1], 4) &&
+        vec(params[2], 3) &&
+        vec(params[3], 4)
+      );
+    case 'useSphericalJoint':
+      return params.length === 2 && vec(params[0], 3) && vec(params[1], 3);
+    case 'useRevoluteJoint':
+    case 'usePrismaticJoint':
+      return (
+        (params.length === 3 || params.length === 4) &&
+        vec(params[0], 3) &&
+        vec(params[1], 3) &&
+        vec(params[2], 3) &&
+        (params.length === 3 || vec(params[3], 2))
+      );
+    case 'useRopeJoint':
+      return (
+        params.length === 3 &&
+        vec(params[0], 3) &&
+        vec(params[1], 3) &&
+        typeof params[2] === 'number'
+      );
+    case 'useSpringJoint':
+      return (
+        params.length === 5 &&
+        vec(params[0], 3) &&
+        vec(params[1], 3) &&
+        params.slice(2).every((part) => typeof part === 'number')
+      );
+  }
+}
+
+/** Joint bindings keyed by the existing `<RigidBody>` opening element. */
+export function jointBindingsByElement(
+  sf: ts.SourceFile,
+): Map<ts.JsxOpeningLikeElement, readonly R3fJointBinding[]> {
+  const imported = imports(sf);
+  const result = new Map<ts.JsxOpeningLikeElement, R3fJointBinding[]>();
+  if (imported.hooks.size === 0 || imported.rigidBodies.size === 0) return result;
+
+  const bodies: BodyIndex = new Map();
+  const collectBodies = (node: ts.Node): void => {
+    if (
+      (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) &&
+      imported.rigidBodies.has(node.tagName.getText(sf))
+    ) {
+      const ref = refIdentifier(node);
+      if (ref) {
+        const scope = enclosingScope(node);
+        const scoped = bodies.get(scope) ?? new Map();
+        const matches = scoped.get(ref) ?? [];
+        matches.push(node);
+        scoped.set(ref, matches);
+        bodies.set(scope, scoped);
+      }
+    }
+    ts.forEachChild(node, collectBodies);
+  };
+  collectBodies(sf);
+
+  const attach = (element: ts.JsxOpeningLikeElement, binding: R3fJointBinding): void => {
+    const bindings = result.get(element) ?? [];
+    bindings.push(binding);
+    result.set(element, bindings);
+  };
+
+  const collectHooks = (node: ts.Node): void => {
+    if (ts.isCallExpression(node)) {
+      const pair = bindingPairForCall(node, sf, imported.hooks, bodies);
+      if (pair) {
+        attach(pair.first, { ...pair.binding, endpoint: 0 });
+        attach(pair.second, { ...pair.binding, endpoint: 1 });
+      }
+    }
+    ts.forEachChild(node, collectHooks);
+  };
+  collectHooks(sf);
+  return result;
+}

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

@@ -0,0 +1,81 @@
+/** Source addresses for Drei's native THREE.LOD projection (`<Detailed>`). */
+
+import ts from 'typescript';
+import { jsxAttribute, numericLiteral } from './ts-ast';
+
+import type { R3fLodBinding, R3fLodNumberBinding } from '@volter/editor-sdk/source-authoring';
+export type { R3fLodBinding, R3fLodNumberBinding } from '@volter/editor-sdk/source-authoring';
+
+function detailedNames(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;
+    }
+    if (!statement.moduleSpecifier.text.startsWith('@react-three/drei')) continue;
+    const bindings = statement.importClause?.namedBindings;
+    if (bindings && ts.isNamedImports(bindings)) {
+      for (const element of bindings.elements) {
+        if ((element.propertyName?.text ?? element.name.text) === 'Detailed') {
+          names.add(element.name.text);
+        }
+      }
+    } else if (bindings && ts.isNamespaceImport(bindings)) {
+      names.add(`${bindings.name.text}.Detailed`);
+    }
+  }
+  return names;
+}
+
+function expressionOf(attribute: ts.JsxAttribute | undefined): ts.Expression | undefined {
+  return attribute?.initializer && ts.isJsxExpression(attribute.initializer)
+    ? attribute.initializer.expression
+    : undefined;
+}
+
+function numberBinding(
+  expression: ts.Expression,
+  sf: ts.SourceFile,
+): R3fLodNumberBinding | undefined {
+  const value = numericLiteral(expression);
+  return value === undefined
+    ? undefined
+    : { value, start: expression.getStart(sf), end: expression.getEnd() };
+}
+
+/** Bind every recognized `<Detailed>` even when its values are computed: the
+ * live THREE.LOD remains inspectable, while only literal tokens are writable. */
+export function lodBindingsByElement(
+  sf: ts.SourceFile,
+): Map<ts.JsxOpeningLikeElement, R3fLodBinding> {
+  const names = detailedNames(sf);
+  const result = new Map<ts.JsxOpeningLikeElement, R3fLodBinding>();
+  const visit = (node: ts.Node): void => {
+    if (
+      (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) &&
+      names.has(node.tagName.getText(sf))
+    ) {
+      const distancesExpression = expressionOf(jsxAttribute(node, 'distances'));
+      const distanceBindings =
+        distancesExpression && ts.isArrayLiteralExpression(distancesExpression)
+          ? distancesExpression.elements.map((element) => numberBinding(element, sf))
+          : [];
+      const distances =
+        distanceBindings.length > 0 && distanceBindings.every((value) => value !== undefined)
+          ? (distanceBindings as R3fLodNumberBinding[])
+          : undefined;
+      const hysteresisExpression = expressionOf(jsxAttribute(node, 'hysteresis'));
+      const hysteresis = hysteresisExpression ? numberBinding(hysteresisExpression, sf) : undefined;
+      const { line, character } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+      result.set(node, {
+        line: line + 1,
+        col: character,
+        ...(distances ? { distances } : {}),
+        ...(hysteresis ? { hysteresis } : {}),
+      });
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return result;
+}

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

@@ -0,0 +1,213 @@
+/** Source address for a native three.quarks `ParticleSystem` emitter shape. */
+
+import ts from 'typescript';
+import { enclosingScope, numericLiteral } from './ts-ast';
+
+import type { QuarksEmitterShape, R3fParticleBinding, R3fParticleNumberBinding } from '@volter/editor-sdk/source-authoring';
+export type { QuarksEmitterShape, R3fParticleBinding, R3fParticleNumberBinding } from '@volter/editor-sdk/source-authoring';
+
+const SHAPES: Record<string, QuarksEmitterShape> = {
+  PointEmitter: 'point',
+  SphereEmitter: 'sphere',
+  HemisphereEmitter: 'hemisphere',
+  ConeEmitter: 'cone',
+  CircleEmitter: 'circle',
+  DonutEmitter: 'donut',
+  RectangleEmitter: 'rectangle',
+  GridEmitter: 'grid',
+};
+
+interface Imports {
+  readonly particleSystems: Set<string>;
+  readonly shapes: Map<string, { imported: string; shape: QuarksEmitterShape }>;
+  readonly useMemo: Set<string>;
+}
+
+function namedImports(statement: ts.Statement, module: string): readonly ts.ImportSpecifier[] {
+  if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) {
+    return [];
+  }
+  if (statement.moduleSpecifier.text !== module) return [];
+  const bindings = statement.importClause?.namedBindings;
+  return bindings && ts.isNamedImports(bindings) ? bindings.elements : [];
+}
+
+function importsOf(sf: ts.SourceFile): Imports {
+  const particleSystems = new Set<string>();
+  const shapes = new Map<string, { imported: string; shape: QuarksEmitterShape }>();
+  const useMemo = new Set<string>();
+  for (const statement of sf.statements) {
+    for (const element of namedImports(statement, 'three.quarks')) {
+      const imported = element.propertyName?.text ?? element.name.text;
+      if (imported === 'ParticleSystem') particleSystems.add(element.name.text);
+      const shape = SHAPES[imported];
+      if (shape) shapes.set(element.name.text, { imported, shape });
+    }
+    for (const element of namedImports(statement, 'quarks.core')) {
+      const imported = element.propertyName?.text ?? element.name.text;
+      const shape = SHAPES[imported];
+      if (shape) shapes.set(element.name.text, { imported, shape });
+    }
+    for (const element of namedImports(statement, 'react')) {
+      const imported = element.propertyName?.text ?? element.name.text;
+      if (imported === 'useMemo') useMemo.add(element.name.text);
+    }
+  }
+  return { particleSystems, shapes, useMemo };
+}
+
+function returnedExpression(
+  fn: ts.ArrowFunction | ts.FunctionExpression,
+): ts.Expression | undefined {
+  if (!ts.isBlock(fn.body)) return fn.body;
+  return fn.body.statements.find(ts.isReturnStatement)?.expression;
+}
+
+function particleSystemExpression(
+  expression: ts.Expression,
+  imported: Imports,
+): ts.NewExpression | undefined {
+  if (
+    ts.isNewExpression(expression) &&
+    ts.isIdentifier(expression.expression) &&
+    imported.particleSystems.has(expression.expression.text)
+  ) {
+    return expression;
+  }
+  if (
+    !ts.isCallExpression(expression) ||
+    !ts.isIdentifier(expression.expression) ||
+    !imported.useMemo.has(expression.expression.text)
+  ) {
+    return undefined;
+  }
+  const factory = expression.arguments[0];
+  if (!factory || (!ts.isArrowFunction(factory) && !ts.isFunctionExpression(factory)))
+    return undefined;
+  const returned = returnedExpression(factory);
+  return returned ? particleSystemExpression(returned, imported) : undefined;
+}
+
+function propertyName(name: ts.PropertyName, sf: ts.SourceFile): string {
+  return ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)
+    ? name.text
+    : name.getText(sf);
+}
+
+function property(
+  object: ts.ObjectLiteralExpression,
+  name: string,
+  sf: ts.SourceFile,
+): ts.PropertyAssignment | undefined {
+  return object.properties.find(
+    (candidate): candidate is ts.PropertyAssignment =>
+      ts.isPropertyAssignment(candidate) && propertyName(candidate.name, sf) === name,
+  );
+}
+
+function bindingOf(
+  system: string,
+  declaration: ts.VariableDeclaration,
+  sf: ts.SourceFile,
+  imported: Imports,
+): R3fParticleBinding | undefined {
+  const initializer = declaration.initializer;
+  if (!initializer) return undefined;
+  const construction = particleSystemExpression(initializer, imported);
+  const options = construction?.arguments?.[0];
+  if (!options || !ts.isObjectLiteralExpression(options)) return undefined;
+  const shapeProperty = property(options, 'shape', sf);
+  const shapeExpression = shapeProperty?.initializer;
+  if (
+    !shapeExpression ||
+    !ts.isNewExpression(shapeExpression) ||
+    !ts.isIdentifier(shapeExpression.expression)
+  ) {
+    return undefined;
+  }
+  const shape = imported.shapes.get(shapeExpression.expression.text);
+  if (!shape) return undefined;
+  const parameters = shapeExpression.arguments?.[0];
+  const fields: Record<string, R3fParticleNumberBinding> = {};
+  if (parameters && ts.isObjectLiteralExpression(parameters)) {
+    for (const candidate of parameters.properties) {
+      if (!ts.isPropertyAssignment(candidate)) continue;
+      const value = numericLiteral(candidate.initializer);
+      if (value === undefined) continue;
+      fields[propertyName(candidate.name, sf)] = {
+        value,
+        start: candidate.initializer.getStart(sf),
+        end: candidate.initializer.getEnd(),
+      };
+    }
+  }
+  const { line, character } = sf.getLineAndCharacterOfPosition(shapeExpression.getStart(sf));
+  return {
+    system,
+    shape: shape.shape,
+    constructor: shape.imported,
+    line: line + 1,
+    col: character,
+    fields,
+  };
+}
+
+function primitiveSystem(element: ts.JsxOpeningLikeElement): string | undefined {
+  if (element.tagName.getText() !== 'primitive') return undefined;
+  const object = element.attributes.properties.find(
+    (candidate): candidate is ts.JsxAttribute =>
+      ts.isJsxAttribute(candidate) && candidate.name.getText() === 'object',
+  );
+  const expression =
+    object?.initializer && ts.isJsxExpression(object.initializer)
+      ? object.initializer.expression
+      : undefined;
+  return expression &&
+    ts.isPropertyAccessExpression(expression) &&
+    ts.isIdentifier(expression.expression) &&
+    expression.name.text === 'emitter'
+    ? expression.expression.text
+    : undefined;
+}
+
+/** Native particle bindings keyed by `<primitive object={system.emitter}>`. */
+export function particleBindingsByElement(
+  sf: ts.SourceFile,
+): Map<ts.JsxOpeningLikeElement, R3fParticleBinding> {
+  const imported = importsOf(sf);
+  const byScope = new Map<ts.FunctionLikeDeclaration | null, Map<string, R3fParticleBinding>>();
+  const collectSystems = (node: ts.Node): void => {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {
+      const binding = bindingOf(node.name.text, node, sf, imported);
+      if (binding) {
+        const scope = enclosingScope(node);
+        const systems = byScope.get(scope) ?? new Map();
+        systems.set(node.name.text, binding);
+        byScope.set(scope, systems);
+      }
+    }
+    ts.forEachChild(node, collectSystems);
+  };
+  collectSystems(sf);
+
+  const result = new Map<ts.JsxOpeningLikeElement, R3fParticleBinding>();
+  const resolve = (node: ts.Node, system: string): R3fParticleBinding | undefined => {
+    let scope: ts.FunctionLikeDeclaration | null = enclosingScope(node);
+    for (;;) {
+      const binding = byScope.get(scope)?.get(system);
+      if (binding) return binding;
+      if (scope === null) return undefined;
+      scope = enclosingScope(scope);
+    }
+  };
+  const join = (node: ts.Node): void => {
+    if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) {
+      const system = primitiveSystem(node);
+      const binding = system ? resolve(node, system) : undefined;
+      if (binding) result.set(node, binding);
+    }
+    ts.forEachChild(node, join);
+  };
+  join(sf);
+  return result;
+}