Skip to content

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.md
index 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 throwawa
Every 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 reminders
diff --git a/packages/runtime/src/world/serialize.ts b/packages/runtime/src/world/serialize.ts
index 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;