@vgai/engine 0.5.2 → 0.5.3

package/src/scene/scene-apply.ts

@@ -1,407 +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 { SceneEntity, SceneFile } from './scene-types';
-
-export class ApplyDiffError extends Error {
-  readonly opIndex: number;
-  readonly opType: DiffOp['type'];
-  readonly entityId: string;
-
-  constructor(message: string, opIndex: number, opType: DiffOp['type'], entityId: string) {
-    super(`op #${opIndex} (${opType}, id=${entityId}): ${message}`);
-    this.name = 'ApplyDiffError';
-    this.opIndex = opIndex;
-    this.opType = opType;
-    this.entityId = entityId;
-  }
-}
-
-function cloneEntity(e: SceneEntity): SceneEntity {
-  return JSON.parse(JSON.stringify(e)) as SceneEntity;
-}
-
-/** True iff at least one entity in the tree (at any depth) carries a persisted `id`. */
-function hasAnyPersistedId(entities: SceneEntity[]): boolean {
-  for (const e of entities) {
-    if (e.id) return true;
-    if (e.children && hasAnyPersistedId(e.children)) return true;
-  }
-  return false;
-}
-
-/**
- * The id-persistence trap, made honest.
- *
- * `id` is `z.string().optional()` in the entity schema ("auto-generated if
- * omitted"), and the ids an agent can actually DISCOVER — `vgai status`' —
- * are the RUNTIME uuids a live editor session assigns to id-less entities on
- * load (`editor-store.ts`'s `assignMissingIds`). `applyDiff` resolves ops
- * against the FILE. So for any scene authored the normal way (hand-written,
- * or scaffolded — none of which shipped with ids), the only ids on offer
- * could never resolve here, and the failure read `entity not found` — as if
- * the CALLER had typo'd the id. It is not a typo: NOTHING in that file could
- * ever have matched.
- *
- * The durable half of the fix makes ids real (the editor now persists
- * auto-assigned ids back to the scene file on load — see `loadDocument`), so
- * this message is the safety net for a file that has not been through that
- * path yet. It fires ONLY when the scene has zero persisted ids at all — a
- * genuine bad-id typo against an id-carrying scene still gets the plain,
- * unpadded message.
- */
-const NO_IDS_HINT =
-  ' — and this scene file has NO persisted entity ids AT ALL, so nothing in it could have ' +
-  'matched, whatever id the op named. This is almost certainly not a typo: `vgai status` ' +
-  'reports RUNTIME ids a live editor session assigns to id-less entities on load, and those ' +
-  'only exist in the FILE once the editor has written them back (it now does that ' +
-  'automatically, via autosave, shortly after the scene loads). Open this scene in the editor ' +
-  '(`vgai edit`), let it autosave, then re-read the ids with `vgai status` and retry. Do not ' +
-  'hand-write ids into the file.';
-
-/** Append the no-ids explanation to a not-found message when (and only when) the file has no ids. */
-function notFound(message: string, sceneHasIds: boolean): string {
-  return sceneHasIds ? message : message + NO_IDS_HINT;
-}
-
-/** Recursively search `list` (and descendants) for `id`; if found, splice it out (subtree intact) and return it. */
-function detachById(list: SceneEntity[], id: string): SceneEntity | undefined {
-  for (let i = 0; i < list.length; i++) {
-    const node = list[i]!;
-    if (node.id === id) {
-      list.splice(i, 1);
-      return node;
-    }
-    if (node.children) {
-      const found = detachById(node.children, id);
-      if (found) return found;
-    }
-  }
-  return undefined;
-}
-
-/** Collect the id of `node` and every descendant's id into `into`. */
-function collectIds(node: SceneEntity, into: Set<string>): void {
-  if (node.id) into.add(node.id);
-  if (node.children) {
-    for (const child of node.children) collectIds(child, into);
-  }
-}
-
-/** Delete `children` if it is now an empty array, to match the `cleanDocument`/`serializeScene` convention (see the round-trip-law note above). */
-function stripEmptyChildrenArrays(list: SceneEntity[]): void {
-  for (const node of list) {
-    if (node.children) {
-      if (node.children.length === 0) {
-        delete node.children;
-      } else {
-        stripEmptyChildrenArrays(node.children);
-      }
-    }
-  }
-}
-
-interface Placement {
-  index: number;
-  node: SceneEntity;
-  opIndex: number;
-  opType: 'add' | 'move';
-  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.
- */
-// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one cohesive apply-in-5-phases pipeline (detach movers, remove, index survivors, place adds+moves, update) — the phases share too much local state (working tree, id maps) to split without just passing that state through a longer parameter list.
-export function applyDiff(scene: SceneFile, diff: SceneDiff): SceneFile {
-  const working: SceneFile = JSON.parse(JSON.stringify(scene)) as SceneFile;
-  const ops = diff.ops;
-  // Captured from the INPUT scene, before any op mutates `working` — see
-  // `NO_IDS_HINT` above for what this distinguishes and why.
-  const sceneHasIds = hasAnyPersistedId(scene.entities);
-
-  // --- Metadata / environment (independent of entity ops) ---
-  if (diff.metaChanged && diff.newName !== undefined) {
-    working.name = diff.newName;
-  }
-  if (diff.environmentChanged) {
-    if (diff.newEnvironment) {
-      working.environment = diff.newEnvironment;
-    } else {
-      delete working.environment;
-    }
-  }
-
-  // --- Phase 1: detach every `move` target before any `remove` runs ---
-  //
-  // A move target isn't always reachable directly off `working.entities`: if
-  // its immediate (or more distant) ancestor ALSO has a `move` op that gets
-  // detached first, the target now hangs off that already-detached ancestor
-  // node, not off the main tree. `diffScene` always emits an ancestor's own
-  // move/update entry before its descendants' (`flattenEntities` sets a
-  // parent's map entry before recursing into children), so a single forward
-  // pass already covers every diffScene-computed diff — but this loop doesn't
-  // assume that ordering: it retries whatever hasn't been found yet against
-  // the growing set of already-detached movers' subtrees, to a fixed point,
-  // so `diff.ops` order genuinely does not matter (per SceneDiffSchema's
-  // `ops` doc).
-  const movedNodes = new Map<string, SceneEntity>();
-  function detachFromAnywhere(id: string): SceneEntity | undefined {
-    const direct = detachById(working.entities, id);
-    if (direct) return direct;
-    for (const mover of movedNodes.values()) {
-      if (mover.children) {
-        const found = detachById(mover.children, id);
-        if (found) return found;
-      }
-    }
-    return undefined;
-  }
-
-  const moveOpIndices = ops
-    .map((op, i) => ({ op, i }))
-    .filter((x): x is { op: Extract<DiffOp, { type: 'move' }>; i: number } => x.op.type === 'move');
-  const pendingMoves = new Set(moveOpIndices.map((x) => x.i));
-  let madeProgress = true;
-  while (pendingMoves.size > 0 && madeProgress) {
-    madeProgress = false;
-    for (const { op, i } of moveOpIndices) {
-      if (!pendingMoves.has(i)) continue;
-      const node = detachFromAnywhere(op.id);
-      if (node) {
-        movedNodes.set(op.id, node);
-        pendingMoves.delete(i);
-        madeProgress = true;
-      }
-    }
-  }
-  if (pendingMoves.size > 0) {
-    const i = [...pendingMoves][0]!;
-    const op = ops[i] as Extract<DiffOp, { type: 'move' }>;
-    throw new ApplyDiffError(
-      notFound('entity not found (nothing to move)', sceneHasIds),
-      i,
-      'move',
-      op.id,
-    );
-  }
-
-  // --- Phase 2: removes (a not-found target is fine if it was already swept
-  //     up as a descendant of an earlier remove, OR if it hangs off a node
-  //     that was itself moved in phase 1 — see `detachFromAnywhere` above) ---
-  const sweptIds = new Set<string>();
-  ops.forEach((op, i) => {
-    if (op.type !== 'remove') return;
-    const node = detachFromAnywhere(op.id);
-    if (node) {
-      collectIds(node, sweptIds);
-      return;
-    }
-    if (sweptIds.has(op.id)) return;
-    throw new ApplyDiffError(
-      notFound('entity not found (already removed via an ancestor, or an invalid id)', sceneHasIds),
-      i,
-      'remove',
-      op.id,
-    );
-  });
-
-  // --- Phase 3: build the complete id -> node resolution map ---
-  const byId = new Map<string, SceneEntity>();
-  const indexStationary = (list: SceneEntity[]): void => {
-    for (const node of list) {
-      if (node.id) byId.set(node.id, node);
-      if (node.children) indexStationary(node.children);
-    }
-  };
-  indexStationary(working.entities);
-
-  const addNodes = new Map<number, SceneEntity>(); // opIndex -> freshly created node
-  ops.forEach((op, i) => {
-    if (op.type !== 'add') return;
-    const entity = cloneEntity(op.entity);
-    delete entity.children; // children are position-managed by their own add/move ops
-    if (!entity.id) entity.id = crypto.randomUUID();
-    if (byId.has(entity.id)) {
-      throw new ApplyDiffError(
-        'duplicate id — an entity with this id already exists',
-        i,
-        'add',
-        entity.id,
-      );
-    }
-    byId.set(entity.id, entity);
-    addNodes.set(i, entity);
-  });
-
-  ops.forEach((op, i) => {
-    if (op.type !== 'move') return;
-    if (byId.has(op.id)) {
-      throw new ApplyDiffError('duplicate id — conflicts with an added entity', i, 'move', op.id);
-    }
-    byId.set(op.id, movedNodes.get(op.id)!);
-  });
-
-  // --- Phase 4: placement — group add+move ops by target parent, insert ascending by index ---
-  const groups = new Map<string | null, Placement[]>();
-  ops.forEach((op, i) => {
-    if (op.type === 'add') {
-      const node = addNodes.get(i)!;
-      const list = groups.get(op.parentId) ?? [];
-      list.push({ index: op.index, node, opIndex: i, opType: 'add', entityId: node.id! });
-      groups.set(op.parentId, list);
-    } else if (op.type === 'move') {
-      const node = movedNodes.get(op.id)!;
-      const list = groups.get(op.parentId) ?? [];
-      list.push({ index: op.index, node, opIndex: i, opType: 'move', entityId: op.id });
-      groups.set(op.parentId, list);
-    }
-  });
-
-  for (const [parentId, placements] of groups) {
-    let targetArray: SceneEntity[];
-    if (parentId === null) {
-      targetArray = working.entities;
-    } else {
-      const parentNode = byId.get(parentId);
-      if (!parentNode) {
-        const bad = placements[0]!;
-        throw new ApplyDiffError(
-          notFound(`parent entity "${parentId}" not found`, sceneHasIds),
-          bad.opIndex,
-          bad.opType,
-          bad.entityId,
-        );
-      }
-      parentNode.children ??= [];
-      targetArray = parentNode.children;
-    }
-
-    const sorted = [...placements].sort((a, b) => a.index - b.index);
-    for (const p of sorted) {
-      if (p.index < 0) {
-        throw new ApplyDiffError(
-          `negative target index (${p.index})`,
-          p.opIndex,
-          p.opType,
-          p.entityId,
-        );
-      }
-      const clamped = Math.min(p.index, targetArray.length);
-      targetArray.splice(clamped, 0, p.node);
-    }
-  }
-
-  // --- Phase 5: updates — full field replace (except id/children), deleting omitted fields ---
-  ops.forEach((op, i) => {
-    if (op.type !== 'update') return;
-    const node = byId.get(op.id);
-    if (!node) {
-      throw new ApplyDiffError(notFound('entity not found', sceneHasIds), i, 'update', op.id);
-    }
-    const { id: _id, children: _children, ...fields } = op.entity;
-    for (const key of Object.keys(node) as (keyof SceneEntity)[]) {
-      if (key === 'id' || key === 'children') continue;
-      if (!(key in fields)) delete node[key];
-    }
-    Object.assign(node, fields);
-  });
-
-  stripEmptyChildrenArrays(working.entities);
-  return working;
-}

package/src/scene/scene-diff-schema.ts

@@ -1,115 +0,0 @@
-/**
- * Zod schema for a `SceneDiff` JSON patch (T4.5 — `vgai apply-diff`).
- *
- * Validates the SHAPE of a hand-authored or `diffScene`-computed patch before
- * `applyDiff` (./scene-apply.ts) touches it. Not wired into
- * `scripts/generate-schema.ts` — that script's output feeds the *scene file*
- * JSON Schema (autocomplete/reference for `.vscn.json`/`.prefab.json`/
- * `vgai.game.json`), a different artifact from a diff/patch file. Adding a
- * 5th line there would be mechanically trivial, but a generated
- * `scene-diff.schema.json` has no current consumer (no editor autocomplete
- * targets *.json patch files) — left undone; revisit if one appears.
- *
- * `SceneEntitySchema` is reused as-is for `add`/`update` payloads even though
- * both operations ignore any `children` the payload carries (children are
- * position-managed exclusively by their own `add`/`move` ops — see
- * `applyDiff`'s jsdoc). Rejecting `children` at the schema level would need
- * an `.omit()` off a plain object schema, but `SceneEntitySchema` is a
- * `z.lazy()`-wrapped discriminated union (recursive type), so this schema
- * takes the more permissive-but-documented path: allow it through and let
- * `applyDiff` silently drop it, rather than add a second near-duplicate
- * entity schema just to forbid one field.
- */
-
-import { z } from 'zod';
-import { SceneEntitySchema } from './schema/entity';
-import { SceneEnvironmentSchema } from './schema/environment';
-
-const ParentIdSchema = z
-  .string()
-  .nullable()
-  .describe('Parent entity id, or null for a top-level (root) entity');
-
-const TargetIndexSchema = z
-  .number()
-  .int()
-  .describe(
-    'Target position among the (new) parent’s children, counted in the FINAL tree ' +
-      '(after every op in this diff has been applied) — not the position at the moment this ' +
-      'one op runs. Negative values are rejected; out-of-range values are clamped to the end.',
-  );
-
-export const DiffOpSchema = z.discriminatedUnion('type', [
-  z
-    .object({
-      type: z.literal('add').describe('Insert a new entity into the scene tree'),
-      entity: SceneEntitySchema.describe(
-        'The entity to insert. Any `children` on this payload are ignored — insert descendants ' +
-          'via their own `add` ops with `parentId` set to this entity’s `id`.',
-      ),
-      parentId: ParentIdSchema,
-      index: TargetIndexSchema,
-    })
-    .describe('Add operation'),
-  z
-    .object({
-      type: z.literal('remove').describe('Delete an entity, and its whole subtree, from the scene'),
-      id: z.string().describe('Id of the entity to remove'),
-    })
-    .describe('Remove operation'),
-  z
-    .object({
-      type: z
-        .literal('update')
-        .describe(
-          'Replace an entity’s fields (every field except `id` and `children`) with new values — ' +
-            'a full replace, not a merge: fields present on the live entity but absent from this ' +
-            'payload are deleted',
-        ),
-      id: z.string().describe('Id of the entity to update'),
-      entity: SceneEntitySchema.describe(
-        'The new field values. `id` and any `children` on this payload are ignored — repositioning ' +
-          'is exclusively a `move` op’s job.',
-      ),
-    })
-    .describe('Update operation'),
-  z
-    .object({
-      type: z.literal('move').describe('Reparent and/or reorder an existing entity'),
-      id: z.string().describe('Id of the entity to move'),
-      parentId: ParentIdSchema,
-      index: TargetIndexSchema,
-    })
-    .describe('Move operation'),
-]);
-
-export const SceneDiffSchema = z
-  .object({
-    ops: z
-      .array(DiffOpSchema)
-      .describe(
-        'add/remove/update/move operations. Order in this array does not matter for correctness — ' +
-          'applyDiff derives its own safe application order (moves are detached before removes run, ' +
-          'so a child moved out of a removed parent survives; adds/moves are placed by a fully ' +
-          'pre-resolved id map, so a newly-added parent is always resolvable for its newly-added ' +
-          'children regardless of array position).',
-      ),
-    environmentChanged: z.boolean().describe('Whether the scene-level `environment` block changed'),
-    newEnvironment: SceneEnvironmentSchema.optional().describe(
-      'New `environment` block. Applied only when `environmentChanged` is true; ignored otherwise. ' +
-        'Absent (with `environmentChanged: true`) clears the scene’s environment block.',
-    ),
-    metaChanged: z.boolean().describe('Whether scene metadata (currently just `name`) changed'),
-    newName: z
-      .string()
-      .optional()
-      .describe(
-        'New scene `name`. Applied only when `metaChanged` is true and this is present; ignored otherwise.',
-      ),
-  })
-  .describe(
-    'A scene-diff patch — the JSON format produced by `diffScene` (packages/editor/src/scene-diff.ts) ' +
-      'and consumed by `applyDiff` (./scene-apply.ts) / `vgai apply-diff`.',
-  );
-
-export type SceneDiffPatch = z.infer<typeof SceneDiffSchema>;

package/src/scene/scene-diff-types.ts

@@ -1,29 +0,0 @@
-/**
- * Scene diff types — shared shape for `DiffOp`/`SceneDiff`.
- *
- * Lives in the engine (not next to the compute function in
- * `packages/editor/src/scene-diff.ts`) so that `packages/vgai-cli` — which
- * does not depend on `@vgai/editor` — can validate/apply a diff without
- * introducing a new cli→editor dependency edge. See the dependency-direction
- * note in `./scene-apply.ts` for the full rationale (T4.5).
- *
- * `packages/editor/src/scene-diff.ts` (the ONLY place that computes a
- * `SceneDiff`, via `diffScene`) re-exports these two names so existing
- * editor imports are unaffected.
- */
-
-import type { SceneEntity, SceneEnvironment } from './scene-types';
-
-export type DiffOp =
-  | { type: 'add'; entity: SceneEntity; parentId: string | null; index: number }
-  | { type: 'remove'; id: string }
-  | { type: 'update'; id: string; entity: SceneEntity }
-  | { type: 'move'; id: string; parentId: string | null; index: number };
-
-export interface SceneDiff {
-  ops: DiffOp[];
-  environmentChanged: boolean;
-  newEnvironment?: SceneEnvironment | undefined;
-  metaChanged: boolean;
-  newName?: string | undefined;
-}