@vgai/engine 0.5.0 → 0.5.1

package/dist/runtime/types.d.ts

@@ -1,253 +0,0 @@
-import type RAPIER from '@dimforge/rapier3d-compat';
-import type { EffectComposer } from 'postprocessing';
-import type * as THREE from 'three';
-import type { z } from 'zod';
-import type { SystemAdapters } from '../adapter/system-adapter';
-import type { AssetCache } from '../assets';
-import type { SeededRandom } from '../core/seeded-random';
-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';
-/**
- * The minimal structural shape `ctx.debug.attachRoom` needs from a joined
- * Colyseus room (Task 2.2, `docs/SYNTHETIC-PLAYER-SPEC.md` §3.1's "Multiplayer
- * locus" note): just enough to send the reserved `__vgai:debugCommand`
- * message and listen for its `__vgai:debugCommandResult` reply. Structural,
- * not a Colyseus type import — the same seam-boundary style every other
- * `DebugCtxSurface` member uses (no wrapper around Colyseus itself, D2).
- * `onMessage`'s return type is `unknown` because Colyseus's own return shape
- * (void in some client versions, an unsubscribe function in others) isn't
- * load-bearing here: the registry calls it defensively (invokes it on detach
- * only if it's actually a function).
- */
-export interface DebugRoomHandle {
-    send(type: string, message?: unknown): void;
-    onMessage(type: string, cb: (message: unknown) => void): unknown;
-}
-/**
- * Infers a `registerCommand`/`registerReactCommand`/`useDebugCommand`
- * handler's parameter tuple from its declared Zod `args` tuple (dry-run
- * finding, `docs/ACCEPTANCE-DRIVER-BUILD-PLAN.md` Wave 6 ledger —
- * "`registerCommand` fn typing forces `unknown[]` casts"): a real
- * `z.ZodTuple` infers its element types (`z.tuple([z.number(), z.string()])`
- * → `(n: number, s: string) => ...`), while omitting `args` (the generic's
- * `undefined` default) resolves to the original permissive
- * `(...args: unknown[]) => ...` shape every command had before this generic
- * existed. That permissive fallback is deliberate, not just a placeholder —
- * it keeps every existing no-schema registration (including ones whose
- * handler reads positional args the runtime never validates, since
- * `invoke()` only parses `args` against a schema when one is declared)
- * compiling byte-for-byte unchanged.
- */
-export type DebugCommandArgs<T extends z.ZodTuple | undefined = undefined> = T extends z.ZodTuple ? z.infer<T> : unknown[];
-/**
- * The authoring half of the debug/synthetic-player seam
- * (`docs/SYNTHETIC-PLAYER-SPEC.md` §3.1) — the read/actuate half is
- * `SystemAdapters.DebugAdapter` (`adapter/system-adapter.ts`). Callable from
- * any GameComponent's `init` (one file per new provider/command), or from a
- * react world's `useDebugProvider`/`useDebugCommand`/`useDebugEmit` hooks. Every registration
- * feeds the ONE game-scoped registry (`runtime/debug-registry.ts`) — never a
- * per-world accumulator.
- */
-export interface DebugCtxSurface {
-    /** Register (or replace) a named, JSON-serializable state read. Duplicate
-     *  names from the SAME world replace + warn once; the SAME name from a
-     *  DIFFERENT world throws (`DebugError` code `DEBUG_NAME_COLLISION`). */
-    registerStateProvider(name: string, fn: () => unknown, opts?: {
-        tier?: 'observable' | 'assisted';
-    }): void;
-    /** Register (or replace) an invokable command. `locus` is REQUIRED once the
-     *  project declares a Colyseus room (`DebugRegistry.setRoomDeclared`) — a
-     *  fixture must say whether it mutates authoritative (server) or predicted
-     *  (client) state.
-     *
-     *  Generic over the declared `args` Zod tuple ({@link DebugCommandArgs}) so
-     *  `fn`'s parameters INFER from it: `registerCommand('setHp', { args:
-     *  z.tuple([z.number()]) }, (hp) => ...)` types `hp` as `number` with no
-     *  cast. Leaving `args` off keeps `fn` typed `(...args: unknown[]) => ...`,
-     *  same as before this generic existed. */
-    registerCommand<T extends z.ZodTuple | undefined = undefined>(name: string, spec: {
-        description?: string;
-        args?: T;
-        locus?: 'client' | 'server';
-    }, fn: (...args: DebugCommandArgs<T>) => unknown | Promise<unknown>): void;
-    /** Push a tick-stamped event onto the debug event ring (spec §3.3) — the
-     *  engine stamps `tick`/`simT` at emission, not at read time. */
-    emit(event: string, detail?: unknown): void;
-    /**
-     * Task 2.2 — server-locus command routing (client leg). Call once your
-     * game code has joined its Colyseus room, so `locus: 'server'` commands
-     * have somewhere to send `__vgai:debugCommand`. Returns a detach function
-     * (call on room leave/dispose) — game-scoped, last-attached room wins.
-     */
-    attachRoom(room: DebugRoomHandle): () => void;
-}
-/**
- * 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 {
-    /** 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;
-    /** 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>;
-    /** 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;
-    /** 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/audio 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/audio) 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;
-    /** The debug/synthetic-player authoring surface (`docs/SYNTHETIC-PLAYER-SPEC.md`
-     *  §3.1) — see {@link DebugCtxSurface}. Optional, same absence precedent as
-     *  `registerSystemAdapter`: present on every first-party mount, absent only
-     *  in bare test harnesses that build a hand-rolled `ctx`. */
-    debug?: DebugCtxSurface;
-    /**
-     * D15 (T-D15.1, `docs/D15-DETERMINISM-DESIGN.md` §2.a) — the game-scoped,
-     * named-stream seeded PRNG. `ctx.random()` draws from the `'gameplay'`
-     * stream; `ctx.random.stream('vfx')` (or any other name) draws from an
-     * INDEPENDENT stream, so a cosmetic/VFX draw can never shift the gameplay
-     * draw sequence. Use this instead of raw `Math.random()` for anything a
-     * project wants to keep reproducible; `ctx.random` itself always exists
-     * and is always internally consistent (same seed ⇒ same sequence) whether
-     * or not the project's manifest declares `determinism.seededRandom` — that
-     * flag only gates the BOOT-TIME seeding from
-     * `manifest.determinism.defaultSeed`/`?vgai-seed=`, the burn-down lint
-     * scan, and the dev-mode `Math.random` phase trap (three separate
-     * enforcers, `test/gameplay-rng-ban.test.ts` + `runtime/gameplay-rng-trap.ts`),
-     * never `ctx.random`'s mere presence. Same absence precedent as `debug`
-     * above: present on every first-party mount, optional only for bare test
-     * harnesses that build a hand-rolled `ctx`. `reseed(seed)` (future draws
-     * only) is `play.seed.set`'s eventual target (T-D15.6, not yet wired).
-     */
-    random?: SeededRandom;
-    /** 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.roots` — the live, declaration-ordered world registry.
-     *  Same optionality/absence rule as `game` above. */
-    roots?: 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>;
-//# sourceMappingURL=types.d.ts.map

package/dist/runtime/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":"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"}

package/dist/runtime/types.js

@@ -1 +0,0 @@
-export {};

package/dist/scene/asset-loaders.d.ts

@@ -1,79 +0,0 @@
-/**
- * Canonical GLTF / texture load + cache layer (A2). (Formerly also hosted the
- * `.animgraph.json` loader — removed by E5; see
- * packages/engine/src/animation/xstate-animation-binding.ts.)
- *
- * 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';
-/** Load (and cache) a texture via the shared, prefix-aware TextureLoader. */
-export declare function loadTexture(url: string): THREE.Texture;
-/**
- * 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 declare function loadGLTF(url: string): Promise<{
-    scene: THREE.Group;
-    animations: THREE.AnimationClip[];
-}>;
-/**
- * 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 declare function resolveGltfNode(scene: THREE.Object3D, nodeName: string, src: string): THREE.Object3D;
-/**
- * Clear the module-level GLTF / texture 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 declare function clearAssetCaches(): void;
-/**
- * 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 declare function assetCacheSizes(): {
-    textures: number;
-    gltf: number;
-};
-//# sourceMappingURL=asset-loaders.d.ts.map

package/dist/scene/asset-loaders.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"asset-loaders.d.ts","sourceRoot":"","sources":["../../src/scene/asset-loaders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAY/B,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,OAAO,CAMtD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CACtB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;IAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC;IAAC,UAAU,EAAE,KAAK,CAAC,aAAa,EAAE,CAAA;CAAE,CAAC,CAyBpE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,KAAK,CAAC,QAAQ,EACrB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,GACV,KAAK,CAAC,QAAQ,CAuChB;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAGvC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAEpE"}

package/dist/scene/asset-loaders.js

@@ -1,141 +0,0 @@
-/**
- * Canonical GLTF / texture load + cache layer (A2). (Formerly also hosted the
- * `.animgraph.json` loader — removed by E5; see
- * packages/engine/src/animation/xstate-animation-binding.ts.)
- *
- * 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 { gltfLoader, textureLoader } from '../loader';
-import { SceneParseError } from './parse';
-import { setUserData } from './user-data';
-const textureCache = new Map();
-const gltfCache = new Map();
-/** Load (and cache) a texture via the shared, prefix-aware TextureLoader. */
-export function loadTexture(url) {
-    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) {
-    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);
-        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, nodeName, src) {
-    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) => o.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;
-}
-/**
- * Clear the module-level GLTF / texture 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() {
-    textureCache.clear();
-    gltfCache.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() {
-    return { textures: textureCache.size, gltf: gltfCache.size };
-}

package/dist/scene/asset-paths.d.ts

@@ -1,11 +0,0 @@
-import type { SceneEntity, SceneEnvironment, SceneFile } from './scene-types';
-/**
- * Collect all external asset paths referenced by a scene's entities and environment.
- */
-export declare function collectAssetPaths(entities: SceneEntity[], environment?: SceneEnvironment): Set<string>;
-/**
- * Deep-clone a scene document and replace all occurrences of oldPath with newPath
- * in asset reference fields. Returns the new document.
- */
-export declare function applyAssetRename(doc: SceneFile, oldPath: string, newPath: string): SceneFile;
-//# sourceMappingURL=asset-paths.d.ts.map

package/dist/scene/asset-paths.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"asset-paths.d.ts","sourceRoot":"","sources":["../../src/scene/asset-paths.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAuD9E;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,WAAW,EAAE,EACvB,WAAW,CAAC,EAAE,gBAAgB,GAC7B,GAAG,CAAC,MAAM,CAAC,CAsBb;AAuBD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAU5F"}

package/dist/scene/asset-paths.js

@@ -1,108 +0,0 @@
-/**
- * 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 = [
-    [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, fn) {
-    for (const [group, key] of MATERIAL_TEXTURE_FIELDS) {
-        const holder = group
-            ? material[group]
-            : material;
-        if (!holder || typeof holder !== 'object')
-            continue;
-        const value = holder[key];
-        if (typeof value === 'string')
-            fn(holder, key, value);
-    }
-}
-function isFilePrefab(value) {
-    return value.includes('/');
-}
-function walkEntities(entities, fn) {
-    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, environment) {
-    const paths = new Set();
-    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, oldPath, newPath) {
-    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, oldPath, newPath) {
-    const cloned = JSON.parse(JSON.stringify(doc));
-    walkEntities(cloned.entities, (e) => renameInEntity(e, oldPath, newPath));
-    if (cloned.environment?.skybox === oldPath) {
-        cloned.environment.skybox = newPath;
-    }
-    return cloned;
-}