@vgai/engine 0.5.2 → 0.5.4

package/src/ecs/game-component.ts

@@ -1,260 +0,0 @@
-import type RAPIER2D from '@dimforge/rapier2d-compat';
-import type RAPIER3D from '@dimforge/rapier3d-compat';
-import type * as PIXI from 'pixi.js';
-import type * as THREE from 'three';
-import type { z } from 'zod';
-import type { SystemPhaseName } from '../core/types';
-import type { AdapterSurface, WorldInstance } from '../runtime/game';
-import type { GameContext } from '../runtime/types';
-import type { World2DContext } from '../world2d/types';
-
-/**
- * Map a {@link AdapterSurface} to its native world node type (T7.2, D8 —
- * `docs/GAME-COMPONENT-GENERALIZATION.md` §2). `react` maps to `never`: react
- * entities host no GameComponents (they render from game state via the T7.4
- * state bridge instead).
- */
-export type NodeOf<K extends AdapterSurface> = K extends 'threejs'
-  ? THREE.Object3D
-  : K extends 'pixijs'
-    ? PIXI.Container
-    : never;
-
-/** Map a {@link AdapterSurface} to its native Rapier rigid-body type. */
-export type BodyOf<K extends AdapterSurface> = K extends 'threejs'
-  ? RAPIER3D.RigidBody
-  : K extends 'pixijs'
-    ? RAPIER2D.RigidBody
-    : never;
-
-/** Map a {@link AdapterSurface} to its native Rapier collider type. */
-export type ColliderOf<K extends AdapterSurface> = K extends 'threejs'
-  ? RAPIER3D.Collider
-  : K extends 'pixijs'
-    ? RAPIER2D.Collider
-    : never;
-
-/** Native lifecycle context for a component's declared surface. */
-export type ComponentContextOf<K extends AdapterSurface> = K extends 'pixijs'
-  ? World2DContext
-  : GameContext;
-
-/**
- * Base class for game components attached to entities.
- *
- * Generalized (T7.2, D8 — `docs/GAME-COMPONENT-GENERALIZATION.md`) over the
- * world kind `K` (default `'threejs'`, so every existing component — all of
- * which extend the bare `GameComponent` — compiles and runs unchanged). The
- * world's native node IS the entity — there is no separate entity id and no
- * mirror/sync layer (Track A). Each component instance holds a direct
- * reference to its node and (if any) its Rapier rigid body/collider. The
- * ComponentManager wires these up in `attach()`.
- *
- * Similar to Unity's MonoBehaviour or Godot's Node scripts:
- * - `init()` — called once after the entity is fully constructed
- * - `update(dt, ctx)` — called every fixed timestep, in the component's phase
- * - `dispose(ctx)` — called when the entity is destroyed
- * - `onTriggerEnter/onTriggerExit` — called when a sensor collider overlap
- *   starts/stops, with the other party's native node
- *
- * State lives on `this` (instance properties). On HMR, the engine swaps the
- * prototype via Object.setPrototypeOf — instance state survives, method bodies
- * update to the new code.
- *
- * `update` is deliberately mandatory, not optional like `init`/`dispose`
- * (owner decision, issue #101): components are for BEHAVIOR. If your
- * subclass's `update(dt, ctx)` body is empty, that is a signal the class may
- * not need to be a component at all — a plain state-holder with only
- * `init`/event methods (score/hits counters, etc.) usually belongs as a
- * plain object or a static-scenery/UI object instead (see the "GameComponents
- * are for things with behavior only" rule).
- */
-/**
- * Cross-copy brand (`Symbol.for` is process-global, so every physical copy of
- * the engine shares ONE symbol): `x.prototype instanceof GameComponent` is
- * FALSE when a project resolves TWO copies of the engine at once — the
- * published `@vgai/engine/*` subpaths next to the `@engine/*` source alias,
- * exactly what a scaffolded project's node-side scripts do (meteor-dodge
- * dry-run friction: `validate-scenes --components` reported every field of a
- * pristine scaffold's `SceneCamera` as unknown). Structural checks
- * (`isGameComponentClass`) test this brand as well as `instanceof`.
- */
-export const GAME_COMPONENT_BRAND = Symbol.for('vgai.GameComponent');
-
-/**
- * HMR class lineage. A true component hot-swap deliberately replaces a live
- * instance's prototype with the newly imported class, but other already-live
- * project modules can still hold the previous class object. Native
- * `instanceof PreviousClass` would then become false even though the object is
- * still the same component under the same hot-reload lineage. That broke both
- * ordinary trigger guards (`component instanceof PlayerController`) and the
- * canonical React-state selector (`game.queryByComponent(PlayerController)`).
- *
- * Keep this as class-to-class lineage rather than a string/name registry:
- * minified classes, aliases, and two unrelated components with the same name
- * remain distinct. The WeakMap owns no game/entity state and introduces no
- * second identity model; it records only the exact constructor pairs the
- * existing HMR boundary has actually swapped.
- */
-type HmrComponentConstructor = abstract new (...args: never[]) => object;
-
-const hmrLineages = new WeakMap<HmrComponentConstructor, Set<HmrComponentConstructor>>();
-
-/** @internal Called only by ComponentManager's successful HMR swap path. */
-export function linkGameComponentHmrClasses(
-  previous: HmrComponentConstructor,
-  next: HmrComponentConstructor,
-): void {
-  const previousLineage = hmrLineages.get(previous);
-  const nextLineage = hmrLineages.get(next);
-  const merged = new Set<HmrComponentConstructor>([previous, next]);
-  if (previousLineage) {
-    for (const member of previousLineage) merged.add(member);
-  }
-  if (nextLineage) {
-    for (const member of nextLineage) merged.add(member);
-  }
-  for (const member of merged) hmrLineages.set(member, merged);
-}
-
-function classesShareHmrLineage(a: HmrComponentConstructor, b: HmrComponentConstructor): boolean {
-  return a === b || hmrLineages.get(a)?.has(b) === true;
-}
-
-export abstract class GameComponent<K extends AdapterSurface = 'threejs'> {
-  /** Which phase this component's update runs in. Override in subclasses. */
-  static phase: SystemPhaseName = 'gameLogic';
-
-  /** See {@link GAME_COMPONENT_BRAND} — inherited by every subclass. */
-  static readonly [GAME_COMPONENT_BRAND] = true;
-
-  /**
-   * Preserve ordinary JavaScript `instanceof` across a true HMR prototype
-   * swap. Subclasses inherit this static hook, so `value instanceof
-   * PlayerController` first performs the native prototype-chain check and,
-   * only when that fails, accepts an exact constructor lineage previously
-   * linked by ComponentManager.hotSwap(). Non-HMR values retain byte-for-byte
-   * native semantics.
-   */
-  static [Symbol.hasInstance](value: unknown): boolean {
-    // biome-ignore lint/complexity/noThisInStatic: Symbol.hasInstance is inherited; `this` must be the queried subclass, not the GameComponent base.
-    const expected = this as HmrComponentConstructor;
-    const nativeMatch = Function.prototype[Symbol.hasInstance].call(expected, value) as boolean;
-    if (nativeMatch) return true;
-    if (value === null || (typeof value !== 'object' && typeof value !== 'function')) return false;
-    const actual = (value as { constructor?: unknown }).constructor;
-    return (
-      typeof actual === 'function' &&
-      classesShareHmrLineage(expected, actual as HmrComponentConstructor)
-    );
-  }
-
-  /**
-   * Runtime-checkable declaration of which {@link AdapterSurface} this component
-   * is written for (T7.2, D8 §3 — `docs/GAME-COMPONENT-GENERALIZATION.md`).
-   * TS's `K` type parameter is erased at runtime, so this static is what the
-   * ComponentManager checks at attach time: a node whose world's kind
-   * doesn't match `declaredKind` THROWS at attach (a `GameComponent<'pixijs'>`
-   * attached to a threejs entity, or vice versa). Kind-agnostic components —
-   * written only against `node`/`this.world`, never the typed `object3D`
-   * accessor or a kind-specific field — may declare `'any'` and attach in
-   * any world components are legal in (every world except `'react'`, which
-   * always throws regardless of `declaredKind` — see the ComponentManager).
-   */
-  static declaredKind: AdapterSurface | 'any' = 'threejs';
-
-  /**
-   * Optional Zod object schema for this component's authored fields. When set,
-   * scene data is validated + defaulted through `schema.parse(data)` before being
-   * assigned onto the instance. Also powers (later) the editor's schema-driven
-   * inspector and HMR defaults.
-   */
-  static schema?: z.ZodObject<z.ZodRawShape>;
-
-  /** The native world node. The node IS the entity. */
-  node!: NodeOf<K>;
-
-  /** The world instance this component's entity lives in (wired at attach). */
-  world!: WorldInstance;
-
-  /**
-   * Typed accessor, threejs roots only — kept for compatibility. On a
-   * `GameComponent` (default `K`) this types as `THREE.Object3D`, so every
-   * existing component compiles unchanged. On a non-threejs instance it
-   * THROWS a descriptive error rather than ever returning a wrong-kind node —
-   * use `this.node` (or `this.world.kind` to check first) instead.
-   */
-  get object3D(): THREE.Object3D {
-    const kind = this.world?.kind;
-    if (kind !== undefined && kind !== 'threejs') {
-      throw new Error(
-        `${this.constructor.name}.object3D: this component's world (kind: "${kind}") is not a ` +
-          'threejs world — `object3D` only ever returns a THREE.Object3D; use `this.node` instead.',
-      );
-    }
-    // When the world isn't wired yet (silo-attached 2D components until
-    // T7.3; bare instances), fall back to the static declaration so a
-    // GameComponent<'pixijs'> can never silently hand out its Container
-    // typed as an Object3D.
-    if (kind === undefined) {
-      const declared = (this.constructor as typeof GameComponent).declaredKind;
-      if (declared !== 'threejs' && declared !== 'any') {
-        throw new Error(
-          `${this.constructor.name}.object3D: this component declares kind "${declared}" — ` +
-            '`object3D` only ever returns a THREE.Object3D; use `this.node` instead.',
-        );
-      }
-    }
-    return this.node as unknown as THREE.Object3D;
-  }
-
-  /** The entity's native rigid body, if it has physics. */
-  rigidBody: BodyOf<K> | null = null;
-
-  /** The entity's native collider, if it has physics. */
-  collider: ColliderOf<K> | null = null;
-
-  /** Called once after the entity is fully constructed (node, physics, etc.). */
-  init?(ctx: ComponentContextOf<K>): void | Promise<void>;
-
-  /** Called every fixed timestep. */
-  abstract update(dt: number, ctx: ComponentContextOf<K>): void;
-
-  /** Called when the entity is destroyed or the component is removed. */
-  dispose?(ctx: ComponentContextOf<K>): void;
-
-  /** Called when a sensor overlap with `other` begins. */
-  onTriggerEnter?(other: NodeOf<K>, ctx: ComponentContextOf<K>): void;
-
-  /** Called when a sensor overlap with `other` ends. */
-  onTriggerExit?(other: NodeOf<K>, ctx: ComponentContextOf<K>): void;
-}
-
-/** Constructor type for one surface's GameComponent subclasses. The default
- * remains Three so existing scene registries stay surface-narrowed. */
-export type GameComponentClass<K extends AdapterSurface = 'threejs'> =
-  (new () => GameComponent<K>) & {
-    declaredKind: AdapterSurface | 'any';
-    phase?: SystemPhaseName;
-    schema?: z.ZodObject<z.ZodRawShape>;
-  };
-
-/** Cross-surface constructor contract for tooling such as HMR and script
- * discovery. React contributes no class because React nodes cannot host
- * GameComponents. Runtime attach still enforces each class's declaredKind. */
-export type AnyGameComponentClass = GameComponentClass<'threejs'> | GameComponentClass<'pixijs'>;
-
-export function gameComponentClassMatchesSurface(
-  component: AnyGameComponentClass,
-  surface: 'threejs',
-): component is GameComponentClass<'threejs'>;
-export function gameComponentClassMatchesSurface(
-  component: AnyGameComponentClass,
-  surface: 'pixijs',
-): component is GameComponentClass<'pixijs'>;
-export function gameComponentClassMatchesSurface(
-  component: AnyGameComponentClass,
-  surface: 'threejs' | 'pixijs',
-): boolean {
-  return component.declaredKind === surface || component.declaredKind === 'any';
-}

package/src/ecs/hmr-swap-report.ts

@@ -1,65 +0,0 @@
-/**
- * HMR swap-miss report — T5.4 (docs/BACKBONE-TASKS.md's Track 5 table:
- * "Deterministic HMR: registry-keyed hotSwap (not `constructor.name`), schema
- * re-parse on swap, loud swap-miss warnings"). `ComponentManager.hotSwap` keys
- * live instances by the `componentRegistry` name recorded on them at attach
- * (see `component-manager.ts`'s `attach`/`hotSwap`), NOT the live
- * `constructor.name` — fragile under minification, class renames, or two
- * classes sharing one name. This module is the structured, greppable
- * `console.warn` a swap-miss warrants, mirrored on the established
- * prefix + JSON-payload pattern (`packages/editor/src/achieved-tier.ts`'s
- * `TIER_SHORTFALL_PREFIX`, `packages/editor/src/authoring/overlay-report.ts`'s
- * `OVERLAY_REPORT_PREFIX`) — kept dependency-free (no `window`/editor-console
- * import) so it stays importable from a headless engine/runtime context,
- * same discipline as those two files.
- *
- * Two independent miss reasons, per the BACKBONE-TASKS detail note:
- *   - `'no-live-instance'` — the incoming hot update's key (the
- *     `componentRegistry` name the recompiled module was re-exported under)
- *     matches no currently-attached instance's recorded registry key (nor,
- *     for an instance attached WITHOUT a registry key — an ad-hoc,
- *     code-attached component — its `constructor.name`). This is the
- *     "renamed class → loud miss" case: a class rename changes the export
- *     key a hot update arrives under, so no live instance is found under the
- *     NEW key — the OLD prototype is simply left in place (never silently
- *     dropped, never crashed).
- *   - `'schema-reparse-failed'` — at least one matched instance's swap
- *     succeeded (prototype replaced), but re-validating its authored props
- *     against the NEW class's `static schema` threw; that instance's fields
- *     are left exactly as they were (last-good props), never partially or
- *     invalidly overwritten.
- */
-
-/** Greppable prefix shared by every swap-miss log line this module produces. */
-export const HMR_SWAP_MISS_PREFIX = 'hmr-swap-miss';
-
-export type HmrSwapMissReport =
-  | { key: string; reason: 'no-live-instance' }
-  | { key: string; reason: 'schema-reparse-failed'; error: string };
-
-/**
- * The one shared message shape — greppable on the prefix, JSON-parseable on
- * the trailing payload (the LAST `{...}` in the string — the human-readable
- * `detail` clause never itself contains a brace, even for the
- * `'schema-reparse-failed'` reason, whose full Zod error text — itself a
- * JSON-issues blob, braces included — is carried only in `report.error`
- * inside that trailing payload, never inlined into `detail`).
- */
-export function formatHmrSwapMissMessage(report: HmrSwapMissReport): string {
-  const detail =
-    report.reason === 'no-live-instance'
-      ? `no live instance's registry key (or, for an ad-hoc/unregistered instance, its class name) ` +
-        `matches "${report.key}" — the hot update had nothing to swap (old class, if any, left in place)`
-      : `schema re-parse failed for "${report.key}" after swap — keeping the instance's last-good ` +
-        `props (Zod error in the trailing payload's "error" field)`;
-  return (
-    `${HMR_SWAP_MISS_PREFIX} ${detail} (T5.4, docs/BACKBONE-TASKS.md). ` +
-    `${HMR_SWAP_MISS_PREFIX} ${JSON.stringify(report)}`
-  );
-}
-
-/** Emit the ONE structured `console.warn` a swap-miss warrants — never a silent no-op. */
-export function logHmrSwapMiss(report: HmrSwapMissReport): void {
-  // biome-ignore lint/suspicious/noConsole: structured, greppable swap-miss warning (T5.4) — mirrors achieved-tier.ts/overlay-report.ts's deliberate direct console.warn
-  console.warn(formatHmrSwapMissMessage(report));
-}

package/src/physics/trigger-dispatch.ts

@@ -1,97 +0,0 @@
-import type RAPIER from '@dimforge/rapier3d-compat';
-import type * as THREE from 'three';
-import type { ComponentManager } from '../ecs/component-manager';
-import type { GameContext } from '../runtime/types';
-import type { CollisionHandler } from './collision-system';
-import type { PhysicsRegistry } from './physics-registry';
-
-/**
- * Build a {@link CollisionHandler} that turns Rapier sensor overlaps into
- * `onTriggerEnter` / `onTriggerExit` callbacks on the GameComponents of the two
- * involved Object3Ds.
- *
- * Rapier collision events report collider *handles*; we resolve each to its
- * Object3D via the physics registry's reverse index, then notify each side's
- * components with the *other* Object3D. Only sensor-involved collisions dispatch
- * triggers (a solid-vs-solid contact is a regular collision, not a trigger).
- *
- * Tracks currently-active trigger partners so that if one side is unregistered
- * (despawned) from the physics registry before Rapier's own exit event is
- * drained, the still-live side still gets its `onTriggerExit` (T1.12d) — see
- * `physics.onRemove` below.
- *
- * Register with `collisions.onCollision(createTriggerDispatch(...))`.
- */
-export function createTriggerDispatch(
-  physics: PhysicsRegistry,
-  components: ComponentManager,
-  rapierWorld: RAPIER.World,
-  ctx: GameContext,
-): CollisionHandler {
-  const activePartners = new Map<THREE.Object3D, Set<THREE.Object3D>>();
-
-  const link = (a: THREE.Object3D, b: THREE.Object3D): void => {
-    let set = activePartners.get(a);
-    if (!set) {
-      set = new Set();
-      activePartners.set(a, set);
-    }
-    set.add(b);
-  };
-  const unlink = (a: THREE.Object3D, b: THREE.Object3D): void => {
-    const set = activePartners.get(a);
-    if (!set) return;
-    set.delete(b);
-    if (set.size === 0) activePartners.delete(a);
-  };
-
-  // Flush pending exits at unregister: an entity removed from the physics
-  // registry (e.g. despawned) may still have queued Rapier "stopped" events
-  // that never reach drain(), or may never generate one at all (the collider
-  // is simply gone). Either way, any object still tracked as its trigger
-  // partner must get its onTriggerExit now, not silently never.
-  physics.onRemove((object3D) => {
-    const partners = activePartners.get(object3D);
-    if (!partners || partners.size === 0) return;
-    for (const other of partners) {
-      notify(components, other, object3D, false, ctx);
-      notify(components, object3D, other, false, ctx);
-      unlink(other, object3D);
-    }
-    activePartners.delete(object3D);
-  });
-
-  return (handleA, handleB, started) => {
-    const colA = rapierWorld.getCollider(handleA);
-    const colB = rapierWorld.getCollider(handleB);
-    if (!colA?.isSensor() && !colB?.isSensor()) return;
-
-    const objA = physics.getByColliderHandle(handleA);
-    const objB = physics.getByColliderHandle(handleB);
-    if (!objA || !objB) return;
-
-    if (started) {
-      link(objA, objB);
-      link(objB, objA);
-    } else {
-      unlink(objA, objB);
-      unlink(objB, objA);
-    }
-
-    notify(components, objA, objB, started, ctx);
-    notify(components, objB, objA, started, ctx);
-  };
-}
-
-function notify(
-  components: ComponentManager,
-  self: THREE.Object3D,
-  other: THREE.Object3D,
-  started: boolean,
-  ctx: GameContext,
-): void {
-  for (const inst of components.getComponents(self)) {
-    if (started) inst.onTriggerEnter?.(other, ctx);
-    else inst.onTriggerExit?.(other, ctx);
-  }
-}

package/src/react/root-adapter.tsx

@@ -1,49 +0,0 @@
-import { type ComponentType, createElement } from 'react';
-import { flushSync } from 'react-dom';
-import { createRoot } from 'react-dom/client';
-import type { MountedReactGame, ReactRootAdapter, ReactWorldHost } from '../runtime/create-runtime';
-import { isAdapterRegistered, registerAdapter } from '../runtime/mount-game';
-import { GameProvider } from './game-state';
-
-interface ReactEntryModule {
-  readonly default?: ComponentType;
-}
-
-/** Construct one canonical React root adapter for direct host composition. */
-export function createReactRootAdapter(id: string, Entry: ComponentType): ReactRootAdapter {
-  return {
-    id,
-    async mount(host: ReactWorldHost): Promise<MountedReactGame> {
-      if (!host.game) throw new Error(`React root "${id}" requires a Game host.`);
-      const reactRoot = createRoot(host.container);
-      flushSync(() => {
-        reactRoot.render(createElement(GameProvider, { game: host.game! }, createElement(Entry)));
-      });
-      return {
-        kind: 'react',
-        container: host.container,
-        drivesOwnLoop: false,
-        dispose: () => reactRoot.unmount(),
-      };
-    },
-  };
-}
-
-/**
- * Register the engine's React adapter-root factory. This module is an
- * explicit optional React entry point: engine core never imports it, while a
- * React game host imports it once and receives the canonical root lifecycle.
- */
-export function registerReactAdapter(): void {
-  if (isAdapterRegistered('react')) return;
-  registerAdapter('react', (root, { entryModule }) => {
-    const Entry = (entryModule as ReactEntryModule | undefined)?.default;
-    if (!Entry) {
-      throw new Error(
-        `React root "${root.id}" entry "${root.entry ?? '(missing)'}" must default-export a component.`,
-      );
-    }
-
-    return { kind: 'react', adapter: createReactRootAdapter(root.id, Entry) };
-  });
-}

package/src/scene/asset-paths.ts

@@ -1,121 +0,0 @@
-import type { SceneEntity, SceneEnvironment, SceneFile } from './scene-types';
-import type { SceneMaterial } from './schema/material';
-
-/**
- * Every material field that holds a texture-file path, as [group, key] pairs —
- * group `null` for top-level fields, otherwise the physical feature group
- * (clearcoat/transmission/sheen/iridescence) the key nests under. One table
- * drives both collect and rename so the two can never disagree;
- * `asset-paths.test.ts` derives the expected set from SceneMaterialSchema's
- * `.describe()` strings so this list can't silently fall behind the schema.
- */
-const MATERIAL_TEXTURE_FIELDS: ReadonlyArray<readonly [string | null, string]> = [
-  [null, 'map'],
-  [null, 'normalMap'],
-  [null, 'emissiveMap'],
-  [null, 'aoMap'],
-  [null, 'lightMap'],
-  [null, 'roughnessMap'],
-  [null, 'metalnessMap'],
-  [null, 'displacementMap'],
-  ['clearcoat', 'clearcoatMap'],
-  ['clearcoat', 'clearcoatRoughnessMap'],
-  ['transmission', 'transmissionMap'],
-  ['sheen', 'sheenColorMap'],
-  ['sheen', 'sheenRoughnessMap'],
-  ['iridescence', 'iridescenceMap'],
-  ['iridescence', 'iridescenceThicknessMap'],
-];
-
-/** Visit every authored texture path on a material (inline or override). */
-function forEachMaterialTexturePath(
-  material: Partial<SceneMaterial>,
-  fn: (holder: Record<string, unknown>, key: string, value: string) => void,
-): void {
-  for (const [group, key] of MATERIAL_TEXTURE_FIELDS) {
-    const holder = group
-      ? (material as Record<string, unknown>)[group]
-      : (material as Record<string, unknown>);
-    if (!holder || typeof holder !== 'object') continue;
-    const value = (holder as Record<string, unknown>)[key];
-    if (typeof value === 'string') fn(holder as Record<string, unknown>, key, value);
-  }
-}
-
-function isFilePrefab(value: string): boolean {
-  return value.includes('/');
-}
-
-function walkEntities(entities: SceneEntity[], fn: (e: SceneEntity) => void): void {
-  for (const e of entities) {
-    fn(e);
-    if (e.children) walkEntities(e.children, fn);
-  }
-}
-
-/**
- * Collect all external asset paths referenced by a scene's entities and environment.
- */
-export function collectAssetPaths(
-  entities: SceneEntity[],
-  environment?: SceneEnvironment,
-): Set<string> {
-  const paths = new Set<string>();
-
-  walkEntities(entities, (e) => {
-    if (e.mesh?.type === 'gltf' && e.mesh.src) paths.add(e.mesh.src);
-    if (e.mesh?.instances) paths.add(e.mesh.instances);
-
-    if (e.material) {
-      forEachMaterialTexturePath(e.material, (_holder, _key, value) => paths.add(value));
-    }
-
-    if (e.materialRef) paths.add(e.materialRef);
-
-    if (e.particles?.material?.map) paths.add(e.particles.material.map);
-
-    if (e.audio?.src) paths.add(e.audio.src);
-    if (e.prefab && isFilePrefab(e.prefab)) paths.add(e.prefab);
-  });
-
-  if (environment?.skybox) paths.add(environment.skybox);
-
-  return paths;
-}
-
-/** Replace oldPath with newPath in a single entity's asset fields. Mutates in place. */
-function renameInEntity(e: SceneEntity, oldPath: string, newPath: string): void {
-  if (e.mesh?.type === 'gltf' && e.mesh.src === oldPath) {
-    e.mesh.src = newPath;
-  }
-  if (e.mesh?.instances === oldPath) e.mesh.instances = newPath;
-
-  if (e.material) {
-    forEachMaterialTexturePath(e.material, (holder, key, value) => {
-      if (value === oldPath) holder[key] = newPath;
-    });
-  }
-
-  if (e.materialRef === oldPath) e.materialRef = newPath;
-
-  if (e.particles?.material?.map === oldPath) e.particles.material.map = newPath;
-
-  if (e.audio?.src === oldPath) e.audio.src = newPath;
-  if (e.prefab === oldPath) e.prefab = newPath;
-}
-
-/**
- * Deep-clone a scene document and replace all occurrences of oldPath with newPath
- * in asset reference fields. Returns the new document.
- */
-export function applyAssetRename(doc: SceneFile, oldPath: string, newPath: string): SceneFile {
-  const cloned: SceneFile = JSON.parse(JSON.stringify(doc));
-
-  walkEntities(cloned.entities, (e) => renameInEntity(e, oldPath, newPath));
-
-  if (cloned.environment?.skybox === oldPath) {
-    cloned.environment.skybox = newPath;
-  }
-
-  return cloned;
-}