The VS Code of video editing, built for agents.
TypeScript
Update migration documentation and entity serialization to clarify the distinction between in-memory snapshots and persisted formats. Adjusted `EntityRecord` description to reflect its role in cloning and entity management without backward compatibility constraints.
konstantin-paulus353dc76685c7
diff --git a/packages/runtime/MIGRATION.md b/packages/runtime/MIGRATION.mdindex 311bc030..679f9ee7 100644--- a/packages/runtime/MIGRATION.md+++ b/packages/runtime/MIGRATION.md@@ -1,12 +1,12 @@# bitecs → koota migration status-Working doc for migrating the editor engine from bitecs (in `apps/web/src/components/engine/`) into this headless runtime package. Written so a fresh session can continue without prior context.+Working doc for migrating the editor engine from bitecs (in `apps/web/src/components/engine/`) into this headless runtime package, and for tracking how far `apps/web` has gotten consuming it. Written so a fresh session can continue without prior context.## Goal and ground rules- `@diffusionstudio/runtime` holds everything that must run without a DOM and without solid-js (so the CLI/node capture path can consume it). Browser-only systems (input, keyboard, camera controller, HUD, dom sync, timeline canvas UI), persistence (`db/`, Dexie), history, and Solid reactivity stay in `apps/web`. Solid bindings live in `packages/koota-solid`.-- The persisted document format (`EntityRecord`, was `DBEntity`) is frozen: field names and value shapes must keep loading existing projects. Enums stay numbers, tags stay `{}`, `Hidden`/`ClipsContent` stay `true`, `Playback` persists only `loop` as 0/1, `KeyframeTrack` persists only `property`.-- Breaking API/type changes inside the codebase are fine (established convention); the storage format is not.+- `EntityRecord` (`src/world/serialize.ts`) is an in-memory clone/snapshot format for copy/paste, duplicate, and split-on-overlap — not a persisted format. Persistence to IndexedDB is not required for now and isn't built here; `EntityRecord`'s shape is free to change with no backward-compat constraint.+- Breaking API/type changes inside the codebase are fine (established convention).- Comments: lean, only constraints code can't show. No em dashes in prose. Tabs, MPL header on ported files.## Done@@ -18,7 +18,7 @@ Working doc for migrating the editor engine from bitecs (in `apps/web/src/compon| World singletons | `src/traits/world.ts` | The bitecs `createWorld({...})` context bag became world traits: Project, Mode, ActiveScene, Camera, Background, Time (was timestamp), FrameRate, RenderSurface (canvas+ctx+resolution), AudioEngine (injected, no ctor arg), Fonts, Mounts, FramePromises (was world.promises), DocumentRoot || `createRuntimeWorld(projectId)` | `src/world/create-world.ts` | Side-effect free except spawning the document root. No AudioContext/window access || Document root model | everywhere | See below, this replaced "parentless = top-level" |-| Serialization | `src/world/serialize.ts` | serializeEntity / deserializeEntity / cloneFromRecords / stripMountIdentity / cloneSubtree. No events layer; plain add+set. `defined()` strips undefined so partial records merge over trait defaults |+| Entity clone/snapshot | `src/world/serialize.ts` | serializeEntity / deserializeEntity / cloneFromRecords / stripMountIdentity / cloneSubtree. Backs copy/paste, duplicate, split-on-overlap, not persistence. No events layer; plain add+set. `defined()` strips undefined so partial records merge over trait defaults || Store access helper | `src/world/store.ts` | `store(world, trait)`: memoized lazy registration + `getStore`. koota registers stores on first add/query; bare `getStore` throws on a fresh world. Use this in all systems || Read queries | `src/queries/{predicates,hierarchy,timeline-index}.ts` | Predicates lost the world param (`isScene(entity)`). `getNextName` scans `world.query(Name)` incl. Deleted tombstones. `TimelineNode.eid` became `entity: Entity` || Transform system | `src/systems/transform.ts` | Store-indexed hot path (`store()` + `entity.id()`), no snapshots, no change events. Roots = `ChildOf(getDocument(world))`. Headless world without canvas skips culling instead of crashing |@@ -54,7 +54,7 @@ Verification style used so far: `npx tsc --noEmit` in the package, plus throwawaEvery world spawns one entity tagged `DocumentRoot` (`createRuntimeWorld`). All rendered entities are its descendants; "top-level" means "direct child of the document", never "has no parent".- `getDocument(world)` returns it; `getParentNode(entity)` returns the parent or null when the parent is the document (use wherever top-level matters); `getParentEntity` returns the raw parent including the document.-- Serialization contract: the document id is per-session, so `serializeEntity` omits `ChildOf` when the parent is the root, and `cloneFromRecords` attaches parentless records to the target world's document. Record shape on disk is unchanged.+- Clone contract: the document id is per-session, so `serializeEntity` omits `ChildOf` when the parent is the root, and `cloneFromRecords` attaches parentless records to the target world's document.- `cloneSubtree` still keeps an outside-the-subtree parent (records with `ChildOf` are not rehomed).- `ChildOf = relation({ exclusive: true, autoDestroy: 'orphan' })`, so `getDocument(world).destroy()` tears down the whole document; clearing a project = destroy + respawn root.- Actions honor this: `createEntity` spawns as a document child; `appendChild` asserts `getParentNode(entity) === null` ("already has a parent" = has a non-document parent) and relies on exclusive re-targeting; `removeChild` re-parents to the document instead of dropping ChildOf. `cloneFromRecords` attaches parentless records to the document, so paste/duplicate roots land there too.@@ -102,9 +102,17 @@ Every world spawns one entity tagged `DocumentRoot` (`createRuntimeWorld`). All- `entity.set(trait, data)` throws if the trait is missing; `entity.add` is idempotent and never resets existing values; `set` with a partial object merges over current values. Hence the add-then-set pattern everywhere in serialize and actions. On an exclusive relation, `add(ChildOf(newParent))` re-targets in place.- Events: `world.onAdd/onChange/onRemove(trait | ChildOf('*'), cb)` exist; relation callbacks get `(entity, target)`. Exclusive re-target fires remove(old) then add(new); a redundant same-pair add fires nothing; remove events fire while the departing child is still in the old target's queries (hence rebuildCaches' `exclude` param). onAdd fires after initial values are applied (`spawn(Trait({...}))` included) and handlers may set traits on the entity. onChange fires even when the written value is unchanged. Destroy cascades and `world.destroy()` fire remove events with still-usable entities.+## App integration progress (apps/web)++apps/web now depends on `@diffusionstudio/runtime` and `@diffusionstudio/koota-solid` (plus `koota` directly) and has started consuming them, in parallel with the still-fully-intact bitecs engine — nothing in `apps/web/src/components/engine/` has been touched or deleted.++- **Engine shell** (`apps/web/src/engine/`, not in this package — it's browser/DOM-coupled, which this package deliberately isn't): `Engine` (`create-engine.ts`) is a class wrapping `createRuntimeWorld` + `runSystems`; it owns canvas mount/resize/DPR, an AudioContext (created or injected, closed on `dispose()` only if it created it), and its own `requestAnimationFrame` loop (`start`/`stop`, plus a public `step(timestamp)` escape hatch for a future host to drive the tick itself and interleave app-side input/HUD systems around it). `context.tsx` (`EngineProvider`/`useEngineContext`) composes koota-solid's `WorldProvider` around `engine.world`, so trait state is read via `useTrait`/`useQuery` directly against the world, not funneled through a context bag. `canvas.tsx` (`EngineCanvas`) is the reusable mount/resize/start component. `hooks/` has a few illustrative per-trait wrappers so far: `useCamera`, `useActiveScene`, `useRunning`.+- **Wired into the live app**: `KootaEngineProvider` (the new `EngineProvider`, aliased) is mounted in `pages/home.tsx` at the same level and lifetime as the old bitecs `EngineProvider` (both keyed on `projectId`), so anything under `EditorPage` can reach the koota world as more gets migrated. In `components/canvas/canvas.tsx`, the koota `EngineCanvas` now occupies the visible `z-1` canvas slot. The old bitecs `<canvas id="engine-canvas">` stays mounted at the same DOM id (so its `EngineProvider`'s `init()` still finds it and keeps initializing, and everything still on `useEngine()`/`useECS()` — Toolbar, drag/drop, sidebars, timeline — keeps working) but is `opacity-0 pointer-events-none`: no longer visible or interactive. Drag/drop handlers moved from the canvas element to its wrapping div so `pointer-events-none` didn't silently kill them.+- The koota world mounted this way is currently empty — no scene-loading/restore wiring exists yet, so this proves the canvas/audio/tick-loop plumbing end to end, not real project content.+## Remaining work (suggested order)-1. **App rewrite** (`apps/web`): engine shell wires canvas/AudioContext/DPR into world traits, app-side world traits (input, HUD, selection tool, history, store, timelineIndex signal), history/persistence via koota events (including wrapping the folder/asset model ops with Dexie writes, font persistence around `loadWebFont` + `restoreFonts`/`getLocalFonts`, re-implementing `syncInteractiveState` over `ChildOf(document)` queries: `Not(ChildOf('*'))` throws in koota, and re-adding the editing-surface `syncKeyframeTrack` calls the observers slice dropped), Deleted-tombstone pruning + `unpersistEntity`, UI to `packages/koota-solid` hooks, timeline UI consumes new `TimelineNode.entity`. `utils/captions.ts` (trpc/upload/encoder-driven) stays app-side, rewired to `@diffusionstudio/encoder`. Delete `engine/components`, `engine/api` progressively.+1. **App rewrite** (`apps/web`): app-side world traits (input, HUD, selection tool, store, timelineIndex signal), history via koota events (undo/redo; persistence to IndexedDB is explicitly not required for now, see ground rules, so skip the Dexie-writes/font-persistence wrapping that would otherwise imply), re-implementing `syncInteractiveState` over `ChildOf(document)` queries (`Not(ChildOf('*'))` throws in koota), re-adding the editing-surface `syncKeyframeTrack` calls the observers slice dropped, Deleted-tombstone pruning, UI to `packages/koota-solid` hooks (only `useCamera`/`useActiveScene`/`useRunning` exist so far), timeline UI consumes new `TimelineNode.entity`. `utils/captions.ts` (trpc/upload/encoder-driven) stays app-side, rewired to `@diffusionstudio/encoder`. Once real content loads into the koota world, delete the now-hidden bitecs canvas and `engine/components`, `engine/api` progressively.2. **CLI**: point node capture at the runtime + encoder packages (incl. importing `MAX_FRAMES_PER_SHEET` from the encoder instead of defining it in `cli-channels.ts`).## Layout remindersdiff --git a/packages/runtime/src/world/serialize.ts b/packages/runtime/src/world/serialize.tsindex 2710206f..414140b5 100644--- a/packages/runtime/src/world/serialize.ts+++ b/packages/runtime/src/world/serialize.ts@@ -21,10 +21,11 @@ import { createEntity } from '../actions/entities';import type { Entity, World } from 'koota';/**- * Persisted document record for one entity. Field names and value shapes are- * the storage format: they must stay stable across the bitecs to koota- * migration so existing projects keep loading (enums stay numbers, Playback- * persists loop as 0/1, tags persist as {} and Hidden/ClipsContent as true).+ * Plain-object snapshot of one entity's traits. Used to clone entity+ * subtrees in-memory (copy/paste, duplicate, split-on-overlap) via+ * serialize -> deserialize onto fresh entities. Not a persisted format —+ * no storage or backward-compatibility guarantees; persistence is a+ * separate, not-yet-built app-side concern.*/export interface EntityRecord {id: string;