@vgai/engine 0.2.0

package/src/runtime/types.ts

@@ -0,0 +1,196 @@
+import type RAPIER from '@dimforge/rapier3d-compat';
+import type { EffectComposer } from 'postprocessing';
+import type * as THREE from 'three';
+import type { SystemAdapters } from '../adapter/system-adapter';
+import type { AnimGraph } from '../animation/anim-graph';
+import type { AssetCache } from '../assets';
+import type { createSystemRunner } from '../core/system-runner';
+import type { createDebugDraw } from '../dev/debug-draw';
+import type { ComponentManager } from '../ecs/component-manager';
+import type { InputManager } from '../input/input-manager';
+import type { CollisionSystem } from '../physics/collision-system';
+import type { PhysicsRegistry } from '../physics/physics-registry';
+import type { SceneFile } from '../scene/scene-types';
+import type { AudioContext as GameAudio } from '../setup/setup-audio';
+import type { ParticlesContext } from '../setup/setup-particles';
+import type { Game, WorldInstance } from './game';
+import type { SceneUIGameServices } from './scene-ui-bridge';
+
+/**
+ * All engine subsystems, passed to every game `setup(ctx)` and to each
+ * GameComponent lifecycle method (`init`/`update`/`dispose`/trigger callbacks).
+ *
+ * The surface is intentionally split in two:
+ *
+ * - **Raw libraries** — the actual Three.js / Rapier / postprocessing objects.
+ *   Call their documented APIs directly; do NOT build wrappers around them.
+ * - **Engine handles** — thin VGAI-owned managers that bridge those libraries
+ *   into the phase-ordered game loop. Reach for these when you need behavior the
+ *   raw library doesn't provide (physics↔Object3D mapping, system phases, etc.).
+ */
+export interface GameContext {
+  // ─── Raw libraries (the real library objects — call them directly) ───
+
+  /** Three.js scene graph root. Add/remove any `Object3D` (meshes, lights,
+   *  groups) here. This is THE scene — there is no separate engine scene. */
+  scene: THREE.Scene;
+  /** The single render camera. Move/aim it directly, or (preferred) drive it
+   *  from a camera GameComponent — see the camera-precedence note below. */
+  camera: THREE.PerspectiveCamera;
+  /** The Rapier physics `World`. Step/query it, create bodies & colliders via
+   *  `ctx.rapier`. One shared world for the whole scene. */
+  rapierWorld: RAPIER.World;
+  /** The Rapier module namespace itself (`RigidBodyDesc`, `ColliderDesc`,
+   *  `Vector3`, enums, …). Use to construct physics descriptors. */
+  rapier: typeof RAPIER;
+  /** The `postprocessing` EffectComposer driving the final render. Use to
+   *  add/remove passes (bloom, vignette, …) or reach the underlying
+   *  `WebGLRenderer` via `composer.getRenderer()`. */
+  composer: EffectComposer;
+
+  // ─── Engine handles (VGAI managers — use when the raw lib isn't enough) ───
+
+  /** Keyboard/mouse/gamepad input. Polled once per frame in the `input` phase;
+   *  read action/axis state inside your `update`. */
+  input: InputManager;
+  /** Rapier collision-event dispatcher. Register handlers with
+   *  `collisions.onCollision(...)`; it is drained each `postPhysics`. Prefer a
+   *  GameComponent's `onTriggerEnter/Exit` for per-entity sensor logic. */
+  collisions: CollisionSystem;
+  /** `Object3D ↔ Rapier body/collider` registry (+ collider→Object3D reverse
+   *  index). Use to find an entity's body/collider, or the entity behind a
+   *  raw collision. Inside a component, `this.rigidBody`/`this.collider` are
+   *  pre-resolved from here. */
+  physics: PhysicsRegistry;
+  /** Procedural audio: master gain, listener, and one-shot/impact helpers.
+   *  Use for SFX and music; the listener tracks the camera. */
+  audio: GameAudio;
+  /** three.quarks particle system: the batched renderer + spawn helpers. Use
+   *  to emit runtime particle effects; declarative scene particles register
+   *  here automatically. */
+  particles: ParticlesContext;
+  /** Immediate-mode debug drawing (`line`/`box`/`sphere`/`arrow`). Drawn
+   *  objects persist until you call `debugDraw.clear()` yourself (the
+   *  adapter also clears on scene dispose/hot-reload) — nothing clears it
+   *  automatically per frame. Dev-only visualization — not for shipped
+   *  visuals. */
+  debugDraw: ReturnType<typeof createDebugDraw>;
+  /** Active animation graphs, keyed by their `Object3D`; ticked in the
+   *  `animation` phase. Look up an entity's `AnimGraph` to set params/triggers.
+   *  GLTF/scene-defined graphs register here automatically. */
+  animGraphs: Map<THREE.Object3D, AnimGraph>;
+  /** Shared GLTF/texture cache. Use `assets.loadGLTF(...)` etc. to load+cache
+   *  models at runtime so repeated loads reuse geometry/material. */
+  assets: AssetCache;
+  /** The phase-ordered system runner. `systems.add(phase, fn)` registers a
+   *  per-frame callback. Reserve this for non-gameplay infra (audio mixers,
+   *  network send); per-entity GAMEPLAY belongs in a GameComponent. */
+  systems: ReturnType<typeof createSystemRunner>;
+  /** Manager for all live GameComponent instances (attach/detach/HMR). The
+   *  scene loader drives this; gameplay code rarely touches it directly. */
+  components: ComponentManager;
+  /** DOM element overlaying the canvas for game UI (React via `mountUI`, or
+   *  vanilla). `pointer-events:none` by default — set `auto` on interactive
+   *  elements. Cleared on scene switch / hot-reload. */
+  uiContainer: HTMLDivElement;
+  /** Register a game-owned `SystemAdapters` capability (networking,
+   *  navigation, …) on the mounted game's adapter surface, so the editor's
+   *  introspection panels (via `getActiveSystems()`) can see it. The engine
+   *  wires the first-party physics/input/assets/animation entries itself;
+   *  capabilities the GAME owns (a Colyseus connection, a NavMeshManager)
+   *  are registered here by the game's setup. Optional capability — absent
+   *  in contexts that expose no adapter surface (some test harnesses);
+   *  call as `ctx.registerSystemAdapter?.(…)`.
+   *
+   *  Ordering contract: **game registrations always win** — the engine seeds
+   *  its first-party entries (physics/input/assets/animation) BEFORE setup()
+   *  runs, so a game that registers any of those same kinds during its own
+   *  setup overrides the engine's entry, not the other way around. This also
+   *  holds across a warm restart (`hotReload`): every kind the outgoing game
+   *  registered is stripped back to the engine's entry (or absent, for
+   *  game-only kinds like networking/navigation) before the incoming game's
+   *  setup runs, so a disposed game's adapter is never left stale on the
+   *  mounted surface. */
+  registerSystemAdapter?<K extends keyof SystemAdapters>(kind: K, adapter: SystemAdapters[K]): void;
+
+  /**
+   * Register (or replace) this game's scene-UI game-time services — the data
+   * source, custom onEvent handler, and/or worldProjector overrides a scene's
+   * authored UI mounts against (design/24-scene-ui.md D2/D7). Optional, same
+   * precedent as `registerSystemAdapter`: absent in contexts with no scene-UI
+   * surface at all (bare test harnesses).
+   *
+   * Timing is safe by construction: the scene loader awaits
+   * `componentManager.initAll()` before `loadScene`/`loadSceneFromData`
+   * return, and the adapter mounts scene UI only after that — so calling this
+   * from a `GameComponent.init()` always beats the mount (its services are
+   * folded into the FIRST render, not a late update). A call AFTER the mount
+   * (e.g. from a click handler) updates the live mount in place instead
+   * (`SceneUIHandle.update`, or a dispose+remount if the renderer has none).
+   *
+   * Per-key merge (D2): a key set here always wins over both the project's
+   * registration-time registry and the engine's own D4/D5/D6 defaults. Hot
+   * reload strips every game-registered key back to none before the incoming
+   * game's `init()` runs — same contract as `registerSystemAdapter`'s re-seed.
+   */
+  setSceneUIServices?(services: SceneUIGameServices): void;
+
+  // ─── Game root (T7.1 slice 1 — GAME-ROOT-DESIGN.md D6) ───
+
+  /** The Game root — the loop, the world registry, and game-scoped handles.
+   *  Absent only in bare test harnesses that construct a partial context (the
+   *  host always sets it in `createGameRuntime`). Optional so every existing
+   *  harness that builds a hand-rolled `ctx` object keeps compiling
+   *  unmodified — the same precedent as `registerSystemAdapter`. */
+  game?: Game | undefined;
+  /** Alias for `game.worlds` — the live, declaration-ordered world registry.
+   *  Same optionality/absence rule as `game` above. */
+  worlds?: ReadonlyArray<WorldInstance> | undefined;
+}
+
+/** Return value from a game setup function. */
+export interface GameCleanup {
+  dispose: () => void;
+}
+
+/** Context passed to setup() when launched from the editor's play mode. */
+export interface EditorPreview {
+  /** Path of the .vscn.json file the user has open (null if unsaved). */
+  scenePath: string | null;
+  /** The editor's in-memory scene document, including unsaved edits. */
+  sceneData: SceneFile;
+  /** Editor viewport camera transform — use this as the initial game camera viewpoint. */
+  viewportCamera?: {
+    position: [number, number, number];
+    quaternion: [number, number, number, number];
+  };
+  /**
+   * Which bundled example the static/browser build's project picker wants to
+   * run (docs/EXAMPLES-AS-PROJECTS-DESIGN.md §4 — Adjudication H). Only
+   * meaningful to `packages/editor/src/browser-play-entry.ts`'s dispatch over
+   * the generated `SETUP_BY_EXAMPLE_ID` table; every other `GameSetupFn`
+   * consumer ignores it. Undefined ⇒ the generic scene-loader fallback
+   * (today's only reachable behavior — no caller sets this yet, since the
+   * picker itself is a later wave).
+   */
+  exampleId?: string | undefined;
+  /**
+   * Asset prefix for the static/browser build's GENERIC scene-loader fallback,
+   * set INSTEAD of `exampleId` when the editor has a non-default scene of a
+   * bundled example open (hosted `?project=<id>&scene=<project-relative>` —
+   * Track H): the open scene plays via `sceneData`, but its relative asset
+   * refs still live under the example's staged `/examples/<id>/` public root.
+   * Ignored whenever `exampleId` is set; undefined ⇒ root prefix `/`.
+   */
+  assetPrefix?: string | undefined;
+}
+
+/** A game setup function: receives engine context, returns cleanup.
+ *
+ * This is the MOUNT body of the FIRST-PARTY implementer. The host no longer
+ * depends on it — the host depends on `GameAdapter` (`@engine/adapter`), and
+ * `GameSetupFn` is wrapped into a `VgaiSceneGameAdapter` via `fromSetup`. See
+ * docs/ADAPTER-ARCHITECTURE.md. (The former `GameAdapter` `{ setup, components }`
+ * interface lived here; it is superseded by the real adapter interfaces in
+ * `@engine/adapter`.) */
+export type GameSetupFn = (ctx: GameContext, editor?: EditorPreview) => Promise<GameCleanup>;

package/src/scene/asset-loaders.ts

@@ -0,0 +1,195 @@
+/**
+ * Canonical GLTF / texture / animgraph load + cache layer (A2).
+ *
+ * ONE place that owns the URL-keyed caches and the clone-safety contract, shared
+ * by BOTH the engine runtime (scene-loader, create-runtime) AND the editor
+ * (entity-factory, scene-sync). Previously this logic was duplicated across six
+ * sites with three separate GLTF caches and four GLTFLoader instances, so fixes
+ * (DRACO wiring, the `__sharedGeometry` clone-safety tag, skybox handling) did
+ * not propagate. Everything funnels through the shared loaders in `../loader`
+ * (`gltfLoader` is DRACO-wired — CB2 — and `textureLoader` shares the engine
+ * LoadingManager / asset-prefix rewrite).
+ *
+ * Cache lifetime / P1.8: these caches are intentionally module-level and persist
+ * ACROSS hot-reloads / scene switches (they are NOT cleared on every scene load).
+ * This is deliberate: (1) it makes repeated Play→Stop→Play cheap, and (2) it
+ * underpins the `__sharedGeometry` contract from P0.2 — GLTF clones share the
+ * cached source geometry, so clearing mid-session would orphan live clones. The
+ * caches are keyed by URL, so loading the SAME asset N times is bounded (one
+ * entry per distinct URL, not per load). They are released only on full runtime
+ * teardown via {@link clearAssetCaches}.
+ */
+
+import * as THREE from 'three';
+import * as SkeletonUtils from 'three/addons/utils/SkeletonUtils.js';
+import type { AnimGraphFile } from '../animation/anim-graph-types';
+import { AnimGraphFileSchema } from '../animation/schema';
+import { gltfLoader, resolveUrl, textureLoader } from '../loader';
+import { SceneParseError } from './parse';
+import { setUserData } from './user-data';
+
+const textureCache = new Map<string, THREE.Texture>();
+const gltfCache = new Map<
+  string,
+  Promise<{ scene: THREE.Group; animations: THREE.AnimationClip[] }>
+>();
+const animGraphCache = new Map<string, Promise<AnimGraphFile>>();
+
+/** Load (and cache) a texture via the shared, prefix-aware TextureLoader. */
+export function loadTexture(url: string): THREE.Texture {
+  const cached = textureCache.get(url);
+  if (cached) return cached;
+  const tex = textureLoader.load(url);
+  textureCache.set(url, tex);
+  return tex;
+}
+
+/**
+ * Load a GLTF/GLB and return a fresh, disposal-safe clone (+ the source's
+ * animation clips). DRACO decoding is handled by the shared `gltfLoader`.
+ *
+ * Clone-safety contract (P0.2 — load-bearing, tested):
+ * `SkeletonUtils.clone` shares geometry AND materials with the cached source.
+ * We give each clone its OWN materials (so scene cleanup can dispose them
+ * without corrupting the cache) and tag every mesh `userData.__sharedGeometry`
+ * so cleanup (engine create-runtime fullCleanup + editor scene-sync
+ * disposeObject3D) skips disposing the shared geometry buffers.
+ */
+export function loadGLTF(
+  url: string,
+): Promise<{ scene: THREE.Group; animations: THREE.AnimationClip[] }> {
+  let cached = gltfCache.get(url);
+  if (!cached) {
+    cached = new Promise((resolve, reject) => {
+      gltfLoader.load(
+        url,
+        (gltf) => resolve({ scene: gltf.scene, animations: gltf.animations }),
+        undefined,
+        (err) => reject(err),
+      );
+    });
+    gltfCache.set(url, cached);
+  }
+  return cached.then((entry) => {
+    const scene = SkeletonUtils.clone(entry.scene) as THREE.Group;
+    scene.traverse((child) => {
+      if (child instanceof THREE.Mesh) {
+        child.material = Array.isArray(child.material)
+          ? child.material.map((m) => m.clone())
+          : child.material.clone();
+        setUserData(child, '__sharedGeometry', true);
+      }
+    });
+    return { scene, animations: entry.animations };
+  });
+}
+
+/**
+ * Resolve a single named node inside an already-loaded glTF scene graph (F4,
+ * docs/VSCN-STRUCTURAL-GAPS-DESIGN.md `mesh.node`). Pure and headlessly
+ * testable — no fetch, no cache lookups; callers pass the `scene` they already
+ * got from {@link loadGLTF}.
+ *
+ * The returned node is the SAME object (and shares the SAME geometry) as
+ * found in `scene` — nothing is cloned or copied out. `scene` is already a
+ * fresh `SkeletonUtils.clone()` per {@link loadGLTF}'s clone-safety contract,
+ * so mutating/detaching the returned node is safe.
+ *
+ * Atomic-subtree guard: a `SkinnedMesh` cannot be lifted out of its armature
+ * (its skeleton/bind matrices reference sibling bone nodes elsewhere in the
+ * hierarchy), so resolving a node that IS a SkinnedMesh, or that CONTAINS one,
+ * throws a loud `SceneParseError` instead of silently producing broken skinning.
+ */
+export function resolveGltfNode(
+  scene: THREE.Object3D,
+  nodeName: string,
+  src: string,
+): THREE.Object3D {
+  const node = scene.getObjectByName(nodeName);
+  if (!node) {
+    throw new SceneParseError(
+      [
+        {
+          code: 'custom',
+          path: ['mesh', 'node'],
+          message: `glTF "${src}" has no node named "${nodeName}" (getObjectByName found nothing)`,
+        },
+      ],
+      src,
+    );
+  }
+
+  const isSkinned = (o: THREE.Object3D) => (o as THREE.SkinnedMesh).isSkinnedMesh;
+  let containsSkinned = isSkinned(node);
+  if (!containsSkinned) {
+    node.traverse((child) => {
+      if (isSkinned(child)) containsSkinned = true;
+    });
+  }
+  if (containsSkinned) {
+    throw new SceneParseError(
+      [
+        {
+          code: 'custom',
+          path: ['mesh', 'node'],
+          message:
+            `glTF "${src}" node "${nodeName}" is (or contains) a SkinnedMesh — a skinned mesh ` +
+            'cannot be lifted out of its armature (atomic-subtree rule). Reference the whole ' +
+            'file instead of a `node`, or bake/export a non-skinned sub-asset.',
+        },
+      ],
+      src,
+    );
+  }
+
+  return node;
+}
+
+/**
+ * Fetch (and cache) an animgraph JSON file via the shared prefix-aware fetch.
+ * Validated via `AnimGraphFileSchema` (T4.6) — a malformed `.animgraph.json`
+ * throws a `SceneParseError` naming the file, not a deep TypeError once the
+ * bad data reaches `AnimGraph`/`LayerRuntime`.
+ */
+export function loadAnimGraphData(src: string): Promise<AnimGraphFile> {
+  let cached = animGraphCache.get(src);
+  if (!cached) {
+    cached = fetch(resolveUrl(src))
+      .then((r) => {
+        if (!r.ok) throw new Error(`Failed to load animgraph: ${src}`);
+        return r.json();
+      })
+      .then((json) => {
+        const result = AnimGraphFileSchema.safeParse(json);
+        if (!result.success) throw new SceneParseError(result.error.issues, src);
+        return result.data;
+      });
+    animGraphCache.set(src, cached);
+  }
+  return cached;
+}
+
+/**
+ * Clear the module-level GLTF / texture / animgraph caches. Call on full runtime
+ * teardown (create-runtime fullCleanup / hot-reload) to release cached GPU
+ * resources and avoid leaking across editor Play sessions. See the lifetime note
+ * at the top of this file for why these are NOT cleared per scene load.
+ *
+ * NOTE: the IBL/skybox env-map cache lives in scene-loader (it needs a
+ * WebGLRenderer for PMREM); scene-loader's `clearAssetCaches` wraps this and
+ * also clears that env cache.
+ */
+export function clearAssetCaches(): void {
+  textureCache.clear();
+  gltfCache.clear();
+  animGraphCache.clear();
+}
+
+/**
+ * Test-only: current sizes of the module-level caches. Used by the P1.8 headless
+ * test to assert caches stay bounded (one entry per distinct asset URL) across
+ * repeated loads of the same scene, rather than growing per load.
+ */
+export function assetCacheSizes(): { textures: number; gltf: number; animGraphs: number } {
+  return { textures: textureCache.size, gltf: gltfCache.size, animGraphs: animGraphCache.size };
+}

package/src/scene/asset-paths.ts

@@ -0,0 +1,123 @@
+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.animation?.animGraph) paths.add(e.animation.animGraph);
+    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.animation?.animGraph === oldPath) e.animation.animGraph = 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;
+}

package/src/scene/asset-registry.ts

@@ -0,0 +1,67 @@
+/**
+ * Central asset registry — stores per-asset metadata (import corrections, etc.).
+ *
+ * Loaded once via fetch(), cached in memory. Both the runtime scene loader
+ * and editor entity factory import from this module.
+ */
+
+import { resolveUrl } from '../loader';
+
+export interface ImportCorrection {
+  /** Uniform scale factor applied to the GLTF clone before entity transform. */
+  scale?: number;
+  /** Euler rotation in degrees [x, y, z] applied to the GLTF clone before entity transform. */
+  rotation?: [number, number, number];
+}
+
+export interface AssetMeta {
+  importCorrection?: ImportCorrection;
+}
+
+type AssetRegistry = Record<string, AssetMeta>;
+
+let registryCache: AssetRegistry | null = null;
+let registryPromise: Promise<AssetRegistry> | null = null;
+
+/** Normalize asset path for registry lookup (strip leading slash). */
+function normalize(path: string): string {
+  return path.startsWith('/') ? path.slice(1) : path;
+}
+
+/**
+ * Fetch and cache the asset registry. Safe to call multiple times —
+ * returns the cached result after the first successful load.
+ */
+export function loadRegistry(): Promise<AssetRegistry> {
+  if (registryCache) return Promise.resolve(registryCache);
+  if (registryPromise) return registryPromise;
+
+  registryPromise = fetch(resolveUrl('asset-registry.json'))
+    .then((res) => {
+      if (!res.ok) return {};
+      return res.json() as Promise<AssetRegistry>;
+    })
+    .catch(() => ({}) as AssetRegistry)
+    .then((data) => {
+      registryCache = data;
+      return data;
+    });
+
+  return registryPromise;
+}
+
+/** Get metadata for an asset path, or undefined if not in the registry. */
+export function getAssetMeta(path: string): AssetMeta | undefined {
+  if (!registryCache) return undefined;
+  // Try exact match first, then normalized
+  return registryCache[path] ?? registryCache[normalize(path)];
+}
+
+/**
+ * Update the in-memory cache directly (used by the editor after saving
+ * import settings, to avoid a re-fetch).
+ */
+export function setRegistryCache(data: AssetRegistry): void {
+  registryCache = data;
+  registryPromise = null;
+}