@vgai/engine 0.2.0 → 0.3.0

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

@@ -0,0 +1,79 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,141 @@
+/**
+ * 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

@@ -0,0 +1,11 @@
+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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,108 @@
+/**
+ * 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;
+}

package/dist/scene/asset-ref-check.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Shared asset-reference integrity check (B6 follow-up to B2 item #20,
+ * docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §8 B6).
+ *
+ * RELOCATED HERE (from `packages/vgai-cli/src/apply-diff.ts`, where it was
+ * originally built as `dereferenceNewAssetRefs`) so it can be shared by BOTH
+ * `vgai apply-diff` (the file-mode CLI verb) and the SDK's
+ * `project.scene.apply` operation (`packages/vgai-sdk/src/project/scene-operations.ts`)
+ * WITHOUT the SDK importing from the CLI — that would invert the intended
+ * dependency direction (CLI -> SDK -> engine, §3.4). The engine's scene layer
+ * is the correct shared home: both the CLI and the SDK already depend
+ * directly on `@vgai/engine/scene/*` for scene parsing/patching, so this
+ * module sits alongside `parse.ts`/`scene-apply.ts` as one more piece of
+ * scene-layer machinery neither caller re-implements.
+ *
+ * WHAT THIS CATCHES that schema validation alone does not: the Zod scene
+ * schema only checks that e.g. `materialRef` is a STRING — never that the
+ * string points at anything real. A diff introducing
+ * `materialRef: "materials/typo.mat.json"` (nonexistent, or present but
+ * malformed) passes ordinary scene/patch validation and would be written;
+ * the failure would otherwise only surface later, at runtime asset fetch.
+ * `dereferenceNewAssetRefs` closes that gap by re-resolving every asset
+ * reference the diff INTRODUCED (present in `result`, absent from
+ * `inputScene` — deliberately not pre-existing refs, so a scene with
+ * unrelated prior breakage can still receive an unrelated repair;
+ * `validate-scenes` remains the whole-project content gate) against disk,
+ * refusing the write if anything is missing or fails its own schema.
+ *
+ * Reference kinds and their treatment (unchanged from the original CLI-only
+ * implementation):
+ *   - Zod-validated (JSON formats with engine Zod schemas): `materialRef`
+ *     (.mat.json -> parseMaterialFile), `prefab` in its file-path form
+ *     (.prefab.json -> parsePrefabFile). Prefabs are validated ONE level
+ *     deep — the referenced prefab file itself must exist and parse; assets
+ *     IT references are that file's own concern. (`animation.animGraph` ->
+ *     AnimGraphFileSchema was removed by E5 — AnimGraph no longer exists.)
+ *   - Existence-checked only (binary formats with no Zod schema to parse
+ *     them through): gltf `mesh.src`, every material texture-map path
+ *     (including the nested clearcoat/transmission/sheen/iridescence groups),
+ *     `particles.material.map`, `audio.src`, `environment.skybox`.
+ *   - `.inputmap.json` is structurally out of scope: no `.vscn.json`/
+ *     `.prefab.json` field references an input map.
+ */
+import type { SceneFile } from './scene-types';
+/** One asset reference found in a scene document: where it is + what it points at. */
+export interface AssetRef {
+    /** The authored path string (web-root-relative, optionally /-prefixed). */
+    path: string;
+    /** Human-readable field location for error messages, e.g. `entity "crate" field materialRef`. */
+    field: string;
+    kind: 'material' | 'prefab' | 'binary';
+}
+/**
+ * One asset reference that failed to dereference. `reason` is a one-line-or-
+ * more human-readable explanation (schema-validation failures may be
+ * multi-line); `field`/`path` mirror `AssetRef` and `diskPath` is the
+ * resolved absolute path that was checked, so every caller (CLI text report,
+ * SDK structured error data) can build its own presentation from the same
+ * facts without re-deriving them.
+ */
+export interface AssetRefError {
+    field: string;
+    path: string;
+    diskPath: string;
+    reason: string;
+}
+/** Collect every asset reference in a scene document (entities walked recursively + environment), labeled for error messages. */
+export declare function collectAssetRefs(doc: SceneFile): AssetRef[];
+/**
+ * Resolve the asset root the scene's references are relative to. Asset paths
+ * are web-root-relative (the runtime fetches them from the served `public/`
+ * directory), and scene files conventionally live INSIDE `public/`
+ * (`public/scenes/*.vscn.json`) — so the nearest ancestor directory literally
+ * named `public` is the root. Fallback for scenes not under a `public/`
+ * ancestor: the scene's own directory.
+ */
+export declare function findAssetRoot(scenePath: string): string;
+/**
+ * Dereference every asset reference `result` introduces relative to
+ * `inputScene` (present in the result, absent from the input) against disk,
+ * relative to `scenePath`'s asset root (see `findAssetRoot`). Returns
+ * structured errors (empty = every new reference resolved and validated) —
+ * never throws; callers decide how to present/escalate a non-empty result
+ * (the CLI folds these into one `ApplyDiffCliError` message, the SDK raises
+ * a declared `ASSET_REF_INVALID` `OperationError`).
+ */
+export declare function dereferenceNewAssetRefs(inputScene: SceneFile, result: SceneFile, scenePath: string): AssetRefError[];
+//# sourceMappingURL=asset-ref-check.d.ts.map

package/dist/scene/asset-ref-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-ref-check.d.ts","sourceRoot":"","sources":["../../src/scene/asset-ref-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAKH,OAAO,KAAK,EAAe,SAAS,EAAE,MAAM,eAAe,CAAC;AAE5D,sFAAsF;AACtF,MAAM,WAAW,QAAQ;IACvB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,iGAAiG;IACjG,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC;CACxC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AA4BD,iIAAiI;AACjI,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,SAAS,GAAG,QAAQ,EAAE,CA0D3D;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CASvD;AAOD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,SAAS,EACrB,MAAM,EAAE,SAAS,EACjB,SAAS,EAAE,MAAM,GAChB,aAAa,EAAE,CAkDjB"}

package/dist/scene/asset-ref-check.js

@@ -0,0 +1,214 @@
+/**
+ * Shared asset-reference integrity check (B6 follow-up to B2 item #20,
+ * docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §8 B6).
+ *
+ * RELOCATED HERE (from `packages/vgai-cli/src/apply-diff.ts`, where it was
+ * originally built as `dereferenceNewAssetRefs`) so it can be shared by BOTH
+ * `vgai apply-diff` (the file-mode CLI verb) and the SDK's
+ * `project.scene.apply` operation (`packages/vgai-sdk/src/project/scene-operations.ts`)
+ * WITHOUT the SDK importing from the CLI — that would invert the intended
+ * dependency direction (CLI -> SDK -> engine, §3.4). The engine's scene layer
+ * is the correct shared home: both the CLI and the SDK already depend
+ * directly on `@vgai/engine/scene/*` for scene parsing/patching, so this
+ * module sits alongside `parse.ts`/`scene-apply.ts` as one more piece of
+ * scene-layer machinery neither caller re-implements.
+ *
+ * WHAT THIS CATCHES that schema validation alone does not: the Zod scene
+ * schema only checks that e.g. `materialRef` is a STRING — never that the
+ * string points at anything real. A diff introducing
+ * `materialRef: "materials/typo.mat.json"` (nonexistent, or present but
+ * malformed) passes ordinary scene/patch validation and would be written;
+ * the failure would otherwise only surface later, at runtime asset fetch.
+ * `dereferenceNewAssetRefs` closes that gap by re-resolving every asset
+ * reference the diff INTRODUCED (present in `result`, absent from
+ * `inputScene` — deliberately not pre-existing refs, so a scene with
+ * unrelated prior breakage can still receive an unrelated repair;
+ * `validate-scenes` remains the whole-project content gate) against disk,
+ * refusing the write if anything is missing or fails its own schema.
+ *
+ * Reference kinds and their treatment (unchanged from the original CLI-only
+ * implementation):
+ *   - Zod-validated (JSON formats with engine Zod schemas): `materialRef`
+ *     (.mat.json -> parseMaterialFile), `prefab` in its file-path form
+ *     (.prefab.json -> parsePrefabFile). Prefabs are validated ONE level
+ *     deep — the referenced prefab file itself must exist and parse; assets
+ *     IT references are that file's own concern. (`animation.animGraph` ->
+ *     AnimGraphFileSchema was removed by E5 — AnimGraph no longer exists.)
+ *   - Existence-checked only (binary formats with no Zod schema to parse
+ *     them through): gltf `mesh.src`, every material texture-map path
+ *     (including the nested clearcoat/transmission/sheen/iridescence groups),
+ *     `particles.material.map`, `audio.src`, `environment.skybox`.
+ *   - `.inputmap.json` is structurally out of scope: no `.vscn.json`/
+ *     `.prefab.json` field references an input map.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { parseMaterialFile, parsePrefabFile, SceneParseError } from './parse';
+/** Material texture-map fields that hold image paths — top-level and nested feature groups. */
+const MATERIAL_MAP_KEYS = [
+    'map',
+    'normalMap',
+    'emissiveMap',
+    'aoMap',
+    'roughnessMap',
+    'metalnessMap',
+    'displacementMap',
+];
+const MATERIAL_GROUP_MAP_KEYS = {
+    clearcoat: ['clearcoatMap', 'clearcoatRoughnessMap'],
+    transmission: ['transmissionMap'],
+    sheen: ['sheenColorMap', 'sheenRoughnessMap'],
+    iridescence: ['iridescenceMap', 'iridescenceThicknessMap'],
+};
+/** Same file-path-vs-registry-id heuristic as `asset-paths.ts`. */
+function isFilePrefab(value) {
+    return value.includes('/');
+}
+function entityLabel(e) {
+    return e.id ? `entity "${e.name}" (id ${e.id})` : `entity "${e.name}"`;
+}
+/** Collect every asset reference in a scene document (entities walked recursively + environment), labeled for error messages. */
+export function collectAssetRefs(doc) {
+    const refs = [];
+    function walk(entities) {
+        for (const e of entities) {
+            const label = entityLabel(e);
+            if (e.mesh?.type === 'gltf' && e.mesh.src) {
+                refs.push({ path: e.mesh.src, field: `${label} field mesh.src`, kind: 'binary' });
+            }
+            if (e.material) {
+                const mat = e.material;
+                for (const key of MATERIAL_MAP_KEYS) {
+                    const val = mat[key];
+                    if (typeof val === 'string') {
+                        refs.push({ path: val, field: `${label} field material.${key}`, kind: 'binary' });
+                    }
+                }
+                for (const [group, keys] of Object.entries(MATERIAL_GROUP_MAP_KEYS)) {
+                    const groupVal = mat[group];
+                    if (groupVal && typeof groupVal === 'object') {
+                        for (const key of keys) {
+                            const val = groupVal[key];
+                            if (typeof val === 'string') {
+                                refs.push({
+                                    path: val,
+                                    field: `${label} field material.${group}.${key}`,
+                                    kind: 'binary',
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+            if (e.materialRef) {
+                refs.push({ path: e.materialRef, field: `${label} field materialRef`, kind: 'material' });
+            }
+            if (e.particles?.material?.map) {
+                refs.push({
+                    path: e.particles.material.map,
+                    field: `${label} field particles.material.map`,
+                    kind: 'binary',
+                });
+            }
+            if (e.audio?.src) {
+                refs.push({ path: e.audio.src, field: `${label} field audio.src`, kind: 'binary' });
+            }
+            if (e.prefab && isFilePrefab(e.prefab)) {
+                refs.push({ path: e.prefab, field: `${label} field prefab`, kind: 'prefab' });
+            }
+            if (e.children)
+                walk(e.children);
+        }
+    }
+    walk(doc.entities);
+    if (doc.environment?.skybox) {
+        refs.push({ path: doc.environment.skybox, field: 'environment.skybox', kind: 'binary' });
+    }
+    return refs;
+}
+/**
+ * Resolve the asset root the scene's references are relative to. Asset paths
+ * are web-root-relative (the runtime fetches them from the served `public/`
+ * directory), and scene files conventionally live INSIDE `public/`
+ * (`public/scenes/*.vscn.json`) — so the nearest ancestor directory literally
+ * named `public` is the root. Fallback for scenes not under a `public/`
+ * ancestor: the scene's own directory.
+ */
+export function findAssetRoot(scenePath) {
+    const dir = resolve(dirname(scenePath));
+    let cursor = dir;
+    for (;;) {
+        if (basename(cursor) === 'public')
+            return cursor;
+        const parent = dirname(cursor);
+        if (parent === cursor)
+            return dir;
+        cursor = parent;
+    }
+}
+/** Format Zod/scene-parse issues as `path: message`, one per line. */
+function formatIssues(issues) {
+    return issues.map((i) => `  ${i.path.join('.')}: ${i.message}`).join('\n');
+}
+/**
+ * Dereference every asset reference `result` introduces relative to
+ * `inputScene` (present in the result, absent from the input) against disk,
+ * relative to `scenePath`'s asset root (see `findAssetRoot`). Returns
+ * structured errors (empty = every new reference resolved and validated) —
+ * never throws; callers decide how to present/escalate a non-empty result
+ * (the CLI folds these into one `ApplyDiffCliError` message, the SDK raises
+ * a declared `ASSET_REF_INVALID` `OperationError`).
+ */
+export function dereferenceNewAssetRefs(inputScene, result, scenePath) {
+    const preexisting = new Set(collectAssetRefs(inputScene).map((r) => r.path));
+    const newRefs = collectAssetRefs(result).filter((r) => !preexisting.has(r.path));
+    if (newRefs.length === 0)
+        return [];
+    const assetRoot = findAssetRoot(scenePath);
+    const errors = [];
+    for (const ref of newRefs) {
+        const diskPath = join(assetRoot, ref.path.replace(/^\//, ''));
+        if (!existsSync(diskPath)) {
+            errors.push({
+                field: ref.field,
+                path: ref.path,
+                diskPath,
+                reason: `file not found at ${diskPath} (resolved against ${assetRoot})`,
+            });
+            continue;
+        }
+        if (ref.kind === 'binary')
+            continue; // existence-only (see the exclusion note above)
+        let json;
+        try {
+            json = JSON.parse(readFileSync(diskPath, 'utf-8'));
+        }
+        catch (err) {
+            errors.push({
+                field: ref.field,
+                path: ref.path,
+                diskPath,
+                reason: `${diskPath} is not valid JSON: ${err instanceof Error ? err.message : err}`,
+            });
+            continue;
+        }
+        try {
+            if (ref.kind === 'material') {
+                parseMaterialFile(json, diskPath);
+            }
+            else {
+                parsePrefabFile(json, diskPath);
+            }
+        }
+        catch (err) {
+            const detail = err instanceof SceneParseError ? `\n${formatIssues(err.issues)}` : ` ${err}`;
+            errors.push({
+                field: ref.field,
+                path: ref.path,
+                diskPath,
+                reason: `${diskPath} fails schema validation:${detail}`,
+            });
+        }
+    }
+    return errors;
+}