@vgai/engine 0.5.0-canary.20260719.1 → 0.5.0

package/dist/scene/parse.js

@@ -0,0 +1,179 @@
+import { checkSceneVersionInRange } from './scene-version';
+import { InstancesFileSchema, MaterialFileSchema, PrefabFileSchema, SceneFileSchema, } from './schema';
+export class SceneParseError extends Error {
+    issues;
+    /** The offending file's path/URL, when the caller knows it (T4.6). */
+    filePath;
+    constructor(issues, filePath) {
+        const msg = issues.map((i) => `  ${i.path.join('.')}: ${i.message}`).join('\n');
+        const header = filePath ? `Scene validation failed (${filePath}):` : 'Scene validation failed:';
+        super(`${header}\n${msg}`);
+        this.name = 'SceneParseError';
+        this.issues = issues;
+        this.filePath = filePath;
+    }
+}
+// ---------------------------------------------------------------------------
+// D8 — removed-format migration guard: declarative property tracks
+// (`animation.tracks`) were deleted (spec §3.2/§10 D8; Theatre — `@theatre/core`
+// — is the sole authored continuous-animation source now). `SceneAnimationSchema`
+// no longer declares a `tracks` field at all (so the generated JSON schema stays
+// clean), which means Zod's default object mode would otherwise silently STRIP
+// an authored `animation.tracks` rather than reporting it — violating Global AC
+// §6 ("Removed formats fail with a concise migration/removal error rather than
+// being partially read"). This walks the RAW pre-Zod JSON (Zod would already
+// have stripped `tracks` by the time any schema-level check could see it) and
+// throws a `SceneParseError` before Zod ever parses the data. Matches on the
+// literal key `animation` (singular, an object) carrying a `tracks` property —
+// this is deliberately narrower than Scene UI's unrelated, RETAINED
+// `ui[].animations[].tracks` (plural `animations`), which this guard must not
+// trip on.
+// ---------------------------------------------------------------------------
+/** True when `value` is a plain object (not an array) carrying a `tracks` property — the shape
+ * `SceneAnimationSchema` used to declare before D8 deleted it. */
+function isRemovedTracksAnimation(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value) && 'tracks' in value;
+}
+function findRemovedPropertyTrackPathInArray(node, path) {
+    for (let i = 0; i < node.length; i++) {
+        const hit = findRemovedPropertyTrackPath(node[i], `${path}[${i}]`);
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+function findRemovedPropertyTrackPathInObject(obj, path) {
+    if (isRemovedTracksAnimation(obj['animation'])) {
+        return `${path ? `${path}.` : ''}animation.tracks`;
+    }
+    for (const [key, value] of Object.entries(obj)) {
+        const hit = findRemovedPropertyTrackPath(value, path ? `${path}.${key}` : key);
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+function findRemovedPropertyTrackPath(node, path) {
+    if (Array.isArray(node))
+        return findRemovedPropertyTrackPathInArray(node, path);
+    if (node && typeof node === 'object') {
+        return findRemovedPropertyTrackPathInObject(node, path);
+    }
+    return undefined;
+}
+function assertNoRemovedPropertyTracks(json, filePath) {
+    const hit = findRemovedPropertyTrackPath(json, '');
+    if (!hit)
+        return;
+    const issue = {
+        code: 'custom',
+        message: 'property tracks were removed; author continuous animation with Theatre (@theatre/core) ' +
+            'instead — see docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §3.2/§10 D8.',
+        path: hit.split('.'),
+    };
+    throw new SceneParseError([issue], filePath);
+}
+// ---------------------------------------------------------------------------
+// E5 — removed-format migration guard: the AnimGraph state-machine runtime,
+// `.animgraph.json` format, and `SceneAnimationSchema.animGraph` field were
+// deleted (spec §3.3/§11 E5; XState + native Three `AnimationMixer` — see
+// `xstate-animation-binding.ts` — replace it). `SceneAnimationSchema` no
+// longer declares an `animGraph` field at all (so it carries zero trace in
+// the generated JSON schema), which means Zod's default object mode would
+// otherwise silently STRIP an authored `animation.animGraph` rather than
+// reporting it — violating Global AC §6. Mirrors
+// `assertNoRemovedPropertyTracks` above exactly: walks the RAW pre-Zod JSON
+// and throws a `SceneParseError` before Zod ever parses the data.
+// ---------------------------------------------------------------------------
+/** True when `value` is a plain object (not an array) carrying an `animGraph` property — the
+ * shape `SceneAnimationSchema` used to declare before E5 deleted it. */
+function isRemovedAnimGraphAnimation(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value) && 'animGraph' in value;
+}
+function findRemovedAnimGraphPathInArray(node, path) {
+    for (let i = 0; i < node.length; i++) {
+        const hit = findRemovedAnimGraphPath(node[i], `${path}[${i}]`);
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+function findRemovedAnimGraphPathInObject(obj, path) {
+    if (isRemovedAnimGraphAnimation(obj['animation'])) {
+        return `${path ? `${path}.` : ''}animation.animGraph`;
+    }
+    for (const [key, value] of Object.entries(obj)) {
+        const hit = findRemovedAnimGraphPath(value, path ? `${path}.${key}` : key);
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+function findRemovedAnimGraphPath(node, path) {
+    if (Array.isArray(node))
+        return findRemovedAnimGraphPathInArray(node, path);
+    if (node && typeof node === 'object') {
+        return findRemovedAnimGraphPathInObject(node, path);
+    }
+    return undefined;
+}
+function assertNoRemovedAnimGraph(json, filePath) {
+    const hit = findRemovedAnimGraphPath(json, '');
+    if (!hit)
+        return;
+    const issue = {
+        code: 'custom',
+        message: 'AnimGraph was removed; drive character animation with an XState animation machine instead ' +
+            '— see docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §3.3/§5.6/§11 E5 and ' +
+            'packages/engine/src/animation/xstate-animation-binding.ts.',
+        path: hit.split('.'),
+    };
+    throw new SceneParseError([issue], filePath);
+}
+export function parseSceneFile(json, filePath) {
+    assertNoRemovedPropertyTracks(json, filePath);
+    assertNoRemovedAnimGraph(json, filePath);
+    const result = SceneFileSchema.safeParse(json);
+    if (!result.success) {
+        throw new SceneParseError(result.error.issues, filePath);
+    }
+    // Post-Zod-parse range check (T2.3/D3 §1.E) — the Zod shape stays a bare
+    // `z.number()`; this is where the file-format `version` axis is actually
+    // read/enforced.
+    checkSceneVersionInRange(result.data.version, 'scene');
+    return result.data;
+}
+export function parsePrefabFile(json, filePath) {
+    assertNoRemovedPropertyTracks(json, filePath);
+    assertNoRemovedAnimGraph(json, filePath);
+    const result = PrefabFileSchema.safeParse(json);
+    if (!result.success) {
+        throw new SceneParseError(result.error.issues, filePath);
+    }
+    checkSceneVersionInRange(result.data.version, 'prefab');
+    return result.data;
+}
+/**
+ * Parse a `.mat.json` shared material asset (T4.6). Unlike scene/prefab files,
+ * there is no version-range gate yet for this format — `MaterialFileSchema`'s
+ * `version` field is RESERVED (see `schema-consumption-map.ts`).
+ */
+export function parseMaterialFile(json, filePath) {
+    const result = MaterialFileSchema.safeParse(json);
+    if (!result.success) {
+        throw new SceneParseError(result.error.issues, filePath);
+    }
+    return result.data;
+}
+/**
+ * Parse a `.instances.json` instance-transform asset (F3,
+ * docs/VSCN-STRUCTURAL-GAPS-DESIGN.md). Mirrors `parseMaterialFile` exactly —
+ * no version-range gate (the format is a bare tuple array, no `version` field).
+ */
+export function parseInstancesFile(json, filePath) {
+    const result = InstancesFileSchema.safeParse(json);
+    if (!result.success) {
+        throw new SceneParseError(result.error.issues, filePath);
+    }
+    return result.data;
+}

package/dist/scene/particles-factory.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Converts SceneParticles JSON → three.quarks ParticleSystem.
+ *
+ * Shared between the editor entity-factory and the runtime scene-loader.
+ * The schema mirrors quarks' native JSON format, so most fields pass through
+ * directly to quarks' fromJSON or constructor methods.
+ */
+import * as THREE from 'three';
+import { type BatchedRenderer, ParticleSystem } from 'three.quarks';
+import type { SceneParticles } from './scene-types';
+export interface ParticleSystemResult {
+    /** The emitter Object3D (add to scene for transform) */
+    emitter: THREE.Object3D;
+    /** The ParticleSystem instance (register with BatchedRenderer) */
+    system: ParticleSystem;
+}
+/**
+ * Create a three.quarks ParticleSystem from SceneParticles JSON data.
+ */
+export declare function createParticleSystemFromData(data: SceneParticles): ParticleSystemResult;
+/**
+ * Register a particle system with a BatchedRenderer.
+ */
+export declare function registerParticleSystem(batchedRenderer: BatchedRenderer, system: ParticleSystem): void;
+/**
+ * Unregister a particle system from a BatchedRenderer.
+ */
+export declare function unregisterParticleSystem(batchedRenderer: BatchedRenderer, system: ParticleSystem): void;
+/**
+ * Default particle data for creating a new particle emitter via AddSectionMenu.
+ */
+export declare function defaultParticlesData(): SceneParticles;
+//# sourceMappingURL=particles-factory.d.ts.map

package/dist/scene/particles-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"particles-factory.d.ts","sourceRoot":"","sources":["../../src/scene/particles-factory.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AA6BH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,KAAK,eAAe,EAAE,cAAc,EAAc,MAAM,cAAc,CAAC;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AA+NpD,MAAM,WAAW,oBAAoB;IACnC,wDAAwD;IACxD,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC;IACxB,kEAAkE;IAClE,MAAM,EAAE,cAAc,CAAC;CACxB;AAED;;GAEG;AAEH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,cAAc,GAAG,oBAAoB,CAwDvF;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,eAAe,EAAE,eAAe,EAChC,MAAM,EAAE,cAAc,GACrB,IAAI,CAEN;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,eAAe,EAAE,eAAe,EAChC,MAAM,EAAE,cAAc,GACrB,IAAI,CAEN;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,cAAc,CA6BrD"}

package/dist/scene/particles-factory.js

@@ -0,0 +1,282 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: quarks' API uses untyped FunctionJSON internally; our Zod types are structurally compatible but TS can't unify them
+/**
+ * Converts SceneParticles JSON → three.quarks ParticleSystem.
+ *
+ * Shared between the editor entity-factory and the runtime scene-loader.
+ * The schema mirrors quarks' native JSON format, so most fields pass through
+ * directly to quarks' fromJSON or constructor methods.
+ */
+import { ApplyForce, ChangeEmitDirection, CircleEmitter, ColorGeneratorFromJSON, ColorOverLife, ConeEmitter, DonutEmitter, ForceOverLife, FrameOverLife, GravityForce, GridEmitter, HemisphereEmitter, LimitSpeedOverLife, Noise, OrbitOverLife, PointEmitter, Vector3 as QVector3, RectangleEmitter, RotationOverLife, SizeOverLife, SpeedOverLife, SphereEmitter, TurbulenceField, ValueGeneratorFromJSON, WidthOverLength, } from 'quarks.core';
+import * as THREE from 'three';
+import { ParticleSystem, RenderMode } from 'three.quarks';
+// --- Render mode mapping ---
+const RENDER_MODE_MAP = {
+    billboard: RenderMode.BillBoard,
+    stretchedBillboard: RenderMode.StretchedBillBoard,
+    mesh: RenderMode.Mesh,
+    trail: RenderMode.Trail,
+    horizontalBillboard: RenderMode.HorizontalBillBoard,
+    verticalBillboard: RenderMode.VerticalBillBoard,
+};
+// --- Texture loader (shared cache) ---
+import { textureLoader } from '../loader';
+const particleTexCache = new Map();
+function loadParticleTexture(url) {
+    const cached = particleTexCache.get(url);
+    if (cached)
+        return cached;
+    const tex = textureLoader.load(url);
+    particleTexCache.set(url, tex);
+    return tex;
+}
+// --- Helpers ---
+/** Strip keys with undefined values so exactOptionalPropertyTypes is satisfied. */
+function defined(obj) {
+    const result = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v !== undefined)
+            result[k] = v;
+    }
+    return result;
+}
+// --- Emitter shape ---
+function createEmitterShape(json) {
+    switch (json.type) {
+        case 'point':
+            return new PointEmitter();
+        case 'sphere':
+            return new SphereEmitter(defined({ radius: json.radius, arc: json.arc, thickness: json.thickness }));
+        case 'hemisphere':
+            return new HemisphereEmitter(defined({ radius: json.radius, arc: json.arc, thickness: json.thickness }));
+        case 'cone':
+            return new ConeEmitter(defined({
+                radius: json.radius,
+                arc: json.arc,
+                thickness: json.thickness,
+                angle: json.angle,
+            }));
+        case 'circle':
+            return new CircleEmitter(defined({ radius: json.radius, arc: json.arc, thickness: json.thickness }));
+        case 'donut':
+            return new DonutEmitter(defined({
+                radius: json.radius,
+                arc: json.arc,
+                thickness: json.thickness,
+                donutRadius: json.donutRadius,
+            }));
+        case 'rectangle':
+            return new RectangleEmitter(defined({ width: json.width, height: json.height, thickness: json.thickness }));
+        case 'grid':
+            return new GridEmitter(defined({ width: json.width, height: json.height, column: json.column, row: json.row }));
+    }
+}
+// --- Value / Color generators ---
+// Our Zod-inferred types are structurally identical to quarks' FunctionJSON
+// but TypeScript can't unify them, so we cast through the untyped bridge.
+function valueGen(json) {
+    return ValueGeneratorFromJSON(json);
+}
+function colorGen(json) {
+    return ColorGeneratorFromJSON(json);
+}
+// --- Behaviors ---
+function createBehavior(json) {
+    switch (json.type) {
+        case 'ApplyForce':
+            return new ApplyForce(new QVector3(json.direction[0], json.direction[1], json.direction[2]), valueGen(json.magnitude));
+        case 'ColorOverLife':
+            return new ColorOverLife(colorGen(json.color));
+        case 'SizeOverLife':
+            return new SizeOverLife(valueGen(json.size));
+        case 'SpeedOverLife':
+            return new SpeedOverLife(valueGen(json.speed));
+        case 'RotationOverLife':
+            return new RotationOverLife(valueGen(json.angularVelocity));
+        case 'ForceOverLife':
+            return new ForceOverLife(valueGen(json.x), valueGen(json.y), valueGen(json.z));
+        case 'OrbitOverLife':
+            return new OrbitOverLife(valueGen(json.orbitSpeed), json.axis ? new QVector3(json.axis[0], json.axis[1], json.axis[2]) : undefined);
+        case 'Noise':
+            return new Noise(valueGen(json.frequency), valueGen(json.power), json.positionAmount ? valueGen(json.positionAmount) : undefined, json.rotationAmount ? valueGen(json.rotationAmount) : undefined);
+        case 'TurbulenceField':
+            return new TurbulenceField(new QVector3(json.scale[0], json.scale[1], json.scale[2]), json.octaves, new QVector3(json.velocityMultiplier[0], json.velocityMultiplier[1], json.velocityMultiplier[2]), new QVector3(json.timeScale[0], json.timeScale[1], json.timeScale[2]));
+        case 'FrameOverLife':
+            return new FrameOverLife(valueGen(json.frame));
+        case 'LimitSpeedOverLife':
+            return new LimitSpeedOverLife(valueGen(json.speed), json.dampen);
+        case 'ChangeEmitDirection':
+            return new ChangeEmitDirection(valueGen(json.angle));
+        case 'GravityForce':
+            return new GravityForce(new QVector3(json.center[0], json.center[1], json.center[2]), json.magnitude);
+        case 'WidthOverLength':
+            return new WidthOverLength(valueGen(json.width));
+    }
+}
+// --- Material ---
+function createParticleMaterial(mat) {
+    const textures = {};
+    if (mat.map)
+        textures['map'] = loadParticleTexture(mat.map);
+    const blending = mat.blending === 'normal' ? THREE.NormalBlending : THREE.AdditiveBlending;
+    const transparent = mat.transparent !== false;
+    const depthWrite = mat.depthWrite ?? false;
+    const side = mat.side === 'back'
+        ? THREE.BackSide
+        : mat.side === 'double'
+            ? THREE.DoubleSide
+            : THREE.FrontSide;
+    if (mat.type === 'standard') {
+        return new THREE.MeshStandardMaterial({
+            color: mat.color ?? '#ffffff',
+            ...textures,
+            blending,
+            transparent,
+            depthWrite,
+            side,
+        });
+    }
+    return new THREE.MeshBasicMaterial({
+        color: mat.color ?? '#ffffff',
+        ...textures,
+        blending,
+        transparent,
+        depthWrite,
+        side,
+    });
+}
+// --- Default sprite texture (soft radial gradient) ---
+let _defaultSpriteTex = null;
+function getDefaultSpriteTex() {
+    if (_defaultSpriteTex)
+        return _defaultSpriteTex;
+    const canvas = document.createElement('canvas');
+    canvas.width = 16;
+    canvas.height = 16;
+    const c2d = canvas.getContext('2d');
+    const grad = c2d.createRadialGradient(8, 8, 0, 8, 8, 8);
+    grad.addColorStop(0, 'rgba(255,255,255,1)');
+    grad.addColorStop(1, 'rgba(255,255,255,0)');
+    c2d.fillStyle = grad;
+    c2d.fillRect(0, 0, 16, 16);
+    _defaultSpriteTex = new THREE.CanvasTexture(canvas);
+    return _defaultSpriteTex;
+}
+/**
+ * Create a three.quarks ParticleSystem from SceneParticles JSON data.
+ */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: straightforward field-by-field mapping
+export function createParticleSystemFromData(data) {
+    const material = createParticleMaterial(data.material);
+    // Apply default sprite if no texture specified
+    if (!data.material.map && 'map' in material) {
+        material.map = getDefaultSpriteTex();
+    }
+    // Build params, strip undefined keys for exactOptionalPropertyTypes compat
+    const params = { material };
+    if (data.autoDestroy != null)
+        params['autoDestroy'] = data.autoDestroy;
+    if (data.looping != null)
+        params['looping'] = data.looping;
+    if (data.prewarm != null)
+        params['prewarm'] = data.prewarm;
+    if (data.duration != null)
+        params['duration'] = data.duration;
+    if (data.shape)
+        params['shape'] = createEmitterShape(data.shape);
+    if (data.startLife)
+        params['startLife'] = valueGen(data.startLife);
+    if (data.startSpeed)
+        params['startSpeed'] = valueGen(data.startSpeed);
+    if (data.startSize)
+        params['startSize'] = valueGen(data.startSize);
+    if (data.startRotation)
+        params['startRotation'] = valueGen(data.startRotation);
+    if (data.startColor)
+        params['startColor'] = colorGen(data.startColor);
+    if (data.startTileIndex)
+        params['startTileIndex'] = valueGen(data.startTileIndex);
+    // Trail mode requires startLength inside rendererEmitterSettings, not as a top-level param
+    if (data.renderMode === 'trail' && data.startLength) {
+        params['rendererEmitterSettings'] = { startLength: valueGen(data.startLength) };
+    }
+    if (data.emissionOverTime)
+        params['emissionOverTime'] = valueGen(data.emissionOverTime);
+    if (data.emissionOverDistance)
+        params['emissionOverDistance'] = valueGen(data.emissionOverDistance);
+    if (data.emissionBursts) {
+        params['emissionBursts'] = data.emissionBursts.map((b) => ({
+            time: b.time,
+            count: valueGen(b.count),
+            cycle: b.cycle ?? 1,
+            interval: b.interval ?? 0,
+            probability: b.probability ?? 1,
+        }));
+    }
+    if (data.behaviors)
+        params['behaviors'] = data.behaviors.map(createBehavior);
+    if (data.renderMode != null)
+        params['renderMode'] = RENDER_MODE_MAP[data.renderMode];
+    if (data.worldSpace != null)
+        params['worldSpace'] = data.worldSpace;
+    if (data.renderOrder != null)
+        params['renderOrder'] = data.renderOrder;
+    if (data.uTileCount != null)
+        params['uTileCount'] = data.uTileCount;
+    if (data.vTileCount != null)
+        params['vTileCount'] = data.vTileCount;
+    if (data.blendTiles != null)
+        params['blendTiles'] = data.blendTiles;
+    if (data.softParticles != null)
+        params['softParticles'] = data.softParticles;
+    if (data.softFarFade != null)
+        params['softFarFade'] = data.softFarFade;
+    if (data.softNearFade != null)
+        params['softNearFade'] = data.softNearFade;
+    const ps = new ParticleSystem(params);
+    return { emitter: ps.emitter, system: ps };
+}
+/**
+ * Register a particle system with a BatchedRenderer.
+ */
+export function registerParticleSystem(batchedRenderer, system) {
+    batchedRenderer.addSystem(system);
+}
+/**
+ * Unregister a particle system from a BatchedRenderer.
+ */
+export function unregisterParticleSystem(batchedRenderer, system) {
+    batchedRenderer.deleteSystem(system);
+}
+/**
+ * Default particle data for creating a new particle emitter via AddSectionMenu.
+ */
+export function defaultParticlesData() {
+    return {
+        looping: true,
+        duration: 2,
+        shape: { type: 'cone', radius: 0.1, angle: 0.3 },
+        startLife: { type: 'IntervalValue', a: 0.5, b: 1.5 },
+        startSpeed: { type: 'IntervalValue', a: 1, b: 3 },
+        startSize: { type: 'IntervalValue', a: 0.05, b: 0.15 },
+        startColor: {
+            type: 'ConstantColor',
+            color: { r: 1, g: 0.8, b: 0.2, a: 1 },
+        },
+        emissionOverTime: { type: 'ConstantValue', value: 30 },
+        behaviors: [
+            {
+                type: 'SizeOverLife',
+                size: {
+                    type: 'PiecewiseBezier',
+                    functions: [{ function: { p0: 1, p1: 0.67, p2: 0.33, p3: 0 }, start: 0 }],
+                },
+            },
+        ],
+        material: {
+            type: 'basic',
+            blending: 'additive',
+            transparent: true,
+            depthWrite: false,
+        },
+    };
+}

package/dist/scene/scene-apply.d.ts

@@ -0,0 +1,109 @@
+/**
+ * `applyDiff` — the exact inverse of `diffScene` (T4.5, `vgai apply-diff`).
+ *
+ * `diffScene` (packages/editor/src/scene-diff.ts) computes a `SceneDiff` from
+ * two `SceneFile`s. This module does the other direction: given ONE
+ * `SceneFile` and a `SceneDiff`, produce the `SceneFile` the diff describes —
+ * a pure function, no editor/live-scene state involved.
+ *
+ * DEPENDENCY-DIRECTION NOTE (why this lives in the engine, not next to
+ * `diffScene`): the natural home for `applyDiff` is beside `diffScene` in
+ * `packages/editor/src/`. But the CLI (`packages/vgai-cli`) is the caller —
+ * `vgai apply-diff <scene> <patch>` — and `packages/vgai-cli/package.json`
+ * does not depend on `@vgai/editor` today (it depends on `@vgai/editor-sdk`,
+ * a thin RPC client for a *running* editor server, and `create-vgai-project`
+ * — neither pulls in editor source). Adding a cli→editor edge purely to reach
+ * one pure function would be a real, new dependency inversion (the T3.7 row
+ * for `deploy.ts` recorded the opposite call deliberately staying out for the
+ * same reason). `@vgai/engine`, by contrast, is already a dependency of
+ * `@vgai/editor` (one-directional: editor → engine) and is trivially addable
+ * to vgai-cli (mirroring `packages/editor/template/validate-scenes.ts`, which
+ * already imports `@vgai/engine/scene/parse` by its real published subpath).
+ * So: `DiffOp`/`SceneDiff` (the shared TYPES) and `applyDiff`/`SceneDiffSchema`
+ * (the new CODE) live in the engine; `scene-diff.ts` keeps its `diffScene`
+ * implementation where it is and re-exports the two type names, so no editor
+ * call site changes. Net edge added: vgai-cli → @vgai/engine (already the
+ * direction every other package depends on engine). Zero new editor edges.
+ *
+ * ROUND-TRIP LAW: for any two scenes A, B — `applyDiff(A, diffScene(A, B))`
+ * is deep-equal to B, WITH ONE NORMALIZATION: an entity whose `children`
+ * becomes empty is left with `children` omitted (not `children: []`) —
+ * matching the convention `cleanDocument`/`serializeScene`
+ * (packages/editor/src/scene-serializer.ts) already use for saved scene
+ * files. If B's own file happened to spell "no children" as a literal
+ * `children: []` rather than omitting the key, a byte-level diff would show
+ * that one field; every other field, and the full entity tree/order, matches
+ * exactly. This holds because `diffScene` emits an explicit `move` op for
+ * ANY entity whose absolute sibling index changes for ANY reason — not just
+ * reparenting, but also a sibling being added/removed/reordered earlier in
+ * the same array — so `applyDiff` never has to guess whether an untouched
+ * entity's position shifted; every position-relevant entity carries an
+ * explicit target index in the FINAL array.
+ *
+ * OP-ORDERING RULE (why applying `diff.ops` in array order would be wrong,
+ * and what this function does instead):
+ *
+ *   1. Detach every `move` target from wherever it currently sits — BEFORE
+ *      processing any `remove`. Proof this matters: consider "remove parent
+ *      with moved-out child" — parent P is deleted in the new doc, but one
+ *      of P's old children, C, survives (reparented elsewhere). `diffScene`
+ *      necessarily emits BOTH `{ remove: P }` and `{ move: C, parentId: ... }`
+ *      (C's parentId can't still be P, since P doesn't exist in the new doc,
+ *      so a parentId change — hence a move op — is guaranteed). If `remove P`
+ *      ran first, it would delete P's whole subtree, including C, before C's
+ *      `move` op ever got to detach it. Detaching every mover first means C
+ *      is already pulled out of P's subtree by the time `remove P` runs, so
+ *      only what's genuinely being deleted is deleted.
+ *   2. Process `remove` ops. A remove target that's already gone (not found)
+ *      is NOT an error IF it was swept away as a descendant of an earlier
+ *      remove in the SAME diff — `diffScene` lists every removed id
+ *      independently (both a removed parent AND its removed descendants each
+ *      get their own `remove` op, since `flattenEntities` flattens every
+ *      level regardless of ancestor state). A remove target not found and
+ *      not swept is a genuine error (bad id).
+ *   3. Build a complete id → node resolution map covering EVERY entity that
+ *      will exist in the output: the stationary survivors (walked fresh from
+ *      what's left of the tree), then a freshly-created node object for each
+ *      `add` (children stripped — see below), then the already-detached node
+ *      for each `move`. Because this map is built in full before any
+ *      placement happens, a node object exists (and is resolvable as a
+ *      parent) from the moment it's created, independent of whether it has
+ *      itself been spliced into ITS OWN parent's array yet. This is what
+ *      makes "add-under-added-parent" (a newly-added parent with newly-added
+ *      children in the same diff) work with no dependency/topological-sort
+ *      logic: a child's `add`/`move` op resolves its `parentId` against this
+ *      map regardless of which op appears first in `diff.ops`.
+ *   4. Placement: group `add` + `move` ops by target parentId, sort each
+ *      group ascending by `index`, then splice one at a time into the target
+ *      array in that order. Inserting in ascending order of FINAL target
+ *      index into an array that already holds every untouched sibling in
+ *      their final relative order (untouched siblings never move — any
+ *      absolute-index change gets its own `move` op, per the round-trip-law
+ *      note above) reconstructs the exact final array: by induction, every
+ *      element with a smaller final index than the one being inserted is
+ *      already in the array, so splicing at `index` places it correctly
+ *      relative to all of them, whether the array started empty (a brand
+ *      new parent) or partially populated (survivors of an existing parent).
+ *   5. `update` ops last (order relative to placement doesn't matter — they
+ *      mutate an object by reference, found via the same id map, regardless
+ *      of where in the tree that reference currently lives).
+ *
+ * Every thrown error is an `ApplyDiffError` naming the 0-based index into
+ * `diff.ops`, the op's `type`, and the entity id involved — enough for an
+ * agent to locate and fix the offending op from the message alone.
+ */
+import type { DiffOp, SceneDiff } from './scene-diff-types';
+import type { SceneFile } from './scene-types';
+export declare class ApplyDiffError extends Error {
+    readonly opIndex: number;
+    readonly opType: DiffOp['type'];
+    readonly entityId: string;
+    constructor(message: string, opIndex: number, opType: DiffOp['type'], entityId: string);
+}
+/**
+ * Apply a `SceneDiff` to a `SceneFile`, returning a NEW `SceneFile` (input is
+ * not mutated). See the module jsdoc above for the round-trip law and the
+ * op-ordering rule/proof.
+ */
+export declare function applyDiff(scene: SceneFile, diff: SceneDiff): SceneFile;
+//# sourceMappingURL=scene-apply.d.ts.map

package/dist/scene/scene-apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-apply.d.ts","sourceRoot":"","sources":["../../src/scene/scene-apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6FG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAe,SAAS,EAAE,MAAM,eAAe,CAAC;AAE5D,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,MAAM;CAOvF;AA8FD;;;;GAIG;AAEH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,GAAG,SAAS,CAoMtE"}