@vgai/engine 0.5.0 → 0.5.2

package/dist/scene/parse.js

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

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

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

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

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

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