The VS Code of video editing, built for agents.
TypeScript
Remove MIGRATION.md file as it is no longer needed for tracking the migration status from bitecs to koota. This cleanup aligns with the ongoing refactoring efforts to streamline the codebase and improve documentation clarity.
konstantin-paulus16a0f6b28022
diff --git a/packages/runtime/MIGRATION.md b/packages/runtime/MIGRATION.mddeleted file mode 100644index fc19afab..00000000--- a/packages/runtime/MIGRATION.md+++ /dev/null@@ -1,156 +0,0 @@-# bitecs → koota migration status--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`.-- `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--| Slice | Where | Notes |-|---|---|---|-| Traits (all ~85 components) | `src/traits/*` | Split by concern: node, transform, style, text, timing, audio, motion, derived, media, interaction, relations, world |-| Constants/enums | `src/constants.ts` | `ScaleMode` enum renamed `ScaleModeType` (collides with the ScaleMode trait; matches Geometry/GeometryType pattern) |-| World singletons | `src/traits/world.ts` | The bitecs `createWorld({...})` context bag became world traits: Project, Mode, Camera, Background, Time (was timestamp), FrameRate, RenderSurface (canvas+ctx+resolution), AudioEngine (injected, no ctor arg), Fonts, Mounts, FramePromises (was world.promises), Stage |-| `createRuntimeWorld(projectId)` | `src/world/create-world.ts` | Side-effect free except spawning the stage. No AudioContext/window access |-| Stage model | everywhere | See below, this replaced "parentless = top-level" |-| 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)`). `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(world.get(Root))`. Headless world without canvas skips culling instead of crashing |-| Motion system | `src/systems/motion.ts` | resetAnimatedValues + getPropertyPaths (property table) + sampleTrack + applyAnimation. animejs dep. See semantic notes |-| Moved verbatim | `src/math/*`, `src/utils/{text-motion,live-mounts}.ts`, `src/fonts/types.ts` | All dependency-free |-| Time utils | `src/utils/time.ts` | snap/frames helpers, `getTimelineOrigin`/`getSourceFrameAt`/`getSourceWindow` (entity-based), `findGeometryAsset`, `findAssetDuration` (Assets + FrameRate world traits). `src/utils/assert.ts` added (was `@/utils`) |-| Asset/folder model | `src/assets/types.ts`, world traits `Assets`/`Folders`/`AssetIds` | Structural types (no zod); `AssetFileHandle = { getFile() }` so node/Electron handles satisfy it. sqids dep for id allocation |-| Actions: entities, hierarchy | `src/actions/{entities,hierarchy}.ts` | See semantic notes. `createEntity` spawns Computed (with non-default width/height/end/duration/strokeWidth) + Cache + ChildOf(document) |-| Actions: cache + timing upkeep | `src/actions/{cache,timing}.ts` | Split of `api/utils.ts`: rebuildCaches/aggregateKeyframeTracks/findClosestParentGeometry; resolveDuration/recomputeEntityTimeRange, propagate/bubble, pinEndToCurrentBounds, trimEntityIn/Out, reactTo* hooks |-| Actions: resize, keyframe, overlap | `src/actions/{resize,keyframe,overlap}.ts` | Constraint seeding = ConstraintCache trait presence (was undefined store slots). Overlap uses cloneSubtree + trimEntityIn/Out |-| Actions: group, frame, clipboard | `src/actions/{group,frame,clipboard}.ts` | frame.ts also hosts `switchActiveScene` (was api/base.ts): sets the ActiveScene world trait, nothing else |-| Actions: assets, folders (model) | `src/actions/{assets,folders}.ts` | allocateId/raiseIdCounter, appendAssets/upsertAsset/removeAssets, getAssetFile/Blob, insertAssetInTimeline; folder tree ops return changed records for app persistence |-| Observers (runtime half) | `src/world/observers.ts` | koota subscriptions wiring cache upkeep, Computed mirrors, and time-range reactions; auto-registered by `createRuntimeWorld` (returns a disposer). See semantic notes |-| Media: decoders + audio bus | `src/media/*` | frame-cache, keyframe-index, time-stretcher, surface, html, audio-peaks moved verbatim; image, video, sequence, audio, shader with entity-based resolvers; audio-bus koota-ported; dispose walkers in `src/media/dispose.ts` and wired as observers |-| Media: caption family | `src/media/caption/*` | types, subtitles, utils (incl. `setChars`), position, seven presets, resolver. See semantic notes on sparse TextStyle |-| Text rendering | `src/utils/text.ts` (full port) | tokenize/shape/render joined the Token seed; reads RenderSurface.ctx + Camera; no-ops without a surface. Gradient construction split into `src/systems/gradients.ts` (render system reuses it) |-| Fonts | `src/fonts/{fixtures,utils}.ts` | WebFonts fixtures verbatim; `loadWebFont` uses the Fonts world trait, resolves the FontFaceSet via globalThis (worker-capable), guards on missing FontFace (headless), and drops db persistence (app wraps it). `getLocalFonts` + `restoreFonts` stay app-side |-| Support utils | `src/utils/{color,async}.ts`, `clamp` in math | parseColor/colorToHex/rgbToColor (colord dep), AsyncMutex/attempt |-| Playback system | `src/systems/playback.ts`, `src/utils/transition.ts` | Playhead advance, visibility/local-time recursion, decoder forwarding, transitions, solo muting, live mounts step; `resolveAudioBus` exported from here. See semantic notes |-| Render system | `src/systems/render.ts`, `HitRegions` world trait | Full traversal port: paints (solid/gradient/media/waveform/shader/html/surface), shadows/strokes/effects, masks, ClipsContent, transitions, Generating pulse. No-op without a RenderSurface. See semantic notes |-| System schedule | `src/systems/schedule.ts` | `runSystems(world)`: playback → motion → transform → render, shared by the realtime tick and the capture loop |-| Encoders | `packages/encoder` (`@diffusionstudio/encoder`) | `engine/encode/*` extracted into its OWN package, not `src/capture/`: createEncoder + createImageEncoder as pure consumers of the runtime's public API. See semantic notes |-| Timecode helpers | `src/utils/time.ts` | `formatTimecode`/`formatTimestamp` (from `utils/transcode.ts`; the image encoder stamps captures with them) |-| Audio sync | `src/media/audio-sync.ts` | Moved near-verbatim (FFT cross-correlation over RMS envelopes; pure math + mediabunny) |-| Transcode + previews | `src/media/transcode.ts` | transcodeForTranscription/ForAnalysis, filmstripAsset, waveformAsset, stampTimestampLabel. Preview canvases became OffscreenCanvas + convertToBlob (worker-capable) instead of document.createElement + toDataURL |-| Contact sheets | `packages/encoder/src/contact-sheet.ts` | Sheets compose image-encoder captures, so they live in the encoder package. It now OWNS `MAX_FRAMES_PER_SHEET` (was `@diffusionstudio/cli/channels`; the CLI imports it from here once rewired). composeSheet is async (OffscreenCanvas) |-| Interaction reads | `src/queries/interaction.ts` | `entityWorldMat`/`entityLocalMat`/`entityQuad`/`entityAnchor`/`entityOffset` (device pixels, from the SoA stores), `isPointerInEntity`, `getSelectionMask`/`getMaskSelection` (was `utils/interaction.ts` + `utils/coordinates.ts`). `entityWorldMat` of the stage (a top-level node's `getParentEntity`, where bitecs had null) is the view matrix, so parent-space math for roots works unchanged |-| Interactive upkeep | `src/actions/interactive.ts` | `syncInteractiveState` (was `api/utils.ts`; roots = `ChildOf(stage)`, diffed against the current tags so it fires no redundant events), `enterEntity` (double-click drill-down), `findChildAt` |-| Seeds (types only, rest follows) | `src/utils/text.ts` (Token/Line/TokenOptions), `src/capture/format.ts` (ContainerFormat) | The remaining engine files merge into these on their slice |--Verification style used so far: `npx tsc --noEmit` in the package, plus throwaway `smoke-test.tmp.ts` in the package root run with `npm exec --yes tsx@latest -- smoke-test.tmp.ts`, deleted afterwards (no test infra in the package yet). koota caps live worlds at 16; call `world.destroy()` in test loops.--## Stage model--Every world spawns one entity tagged `Stage` (`createRuntimeWorld`). All rendered entities are its descendants; "top-level" means "direct child of the stage", never "has no parent".--- `world.get(Root)` returns it; `isStage(entity)` tests for it; `getParentNode(entity)` returns the parent or null when the parent is the stage (use wherever top-level matters); `getParentEntity` returns the raw parent including the stage.-- Clone contract: the stage id is per-session, so `serializeEntity` omits `ChildOf` when the parent is the stage, and `cloneFromRecords` attaches parentless records to the target world's stage.-- `cloneSubtree` still keeps an outside-the-subtree parent (records with `ChildOf` are not rehomed).-- `ChildOf = relation({ exclusive: true, autoDestroy: 'orphan' })`, so `world.get(Root).destroy()` tears down the whole document; clearing a project = destroy + respawn the stage.-- Actions honor this: `createEntity` spawns as a stage child; `appendChild` asserts `getParentNode(entity) === null` ("already has a parent" = has a non-stage parent) and relies on exclusive re-targeting; `removeChild` re-parents to the stage instead of dropping ChildOf. `cloneFromRecords` attaches parentless records to the stage, so paste/duplicate roots land there too.--## Authored time model--`Delay` and `Trim` were replaced by four one-value traits carrying the vocabulary the JSX authors in, all frames: `Start`, `End`, `SourceIn`, `SourceOut`. Start/End place the node on its parent's timeline (parent-relative), SourceIn/SourceOut pick the slice of its own source that plays there. `PlaybackRate` is unchanged and stays authored.--One trait per value rather than one trait with four fields, because a clip rarely says more than one of these things: they are separate answers to separate questions, and absence is the answer most nodes give. A razor cut authors an `End` and nothing else; a clip dropped at the playhead authors a `Start` and nothing else.--- **Defaults** (`resolveDuration` in `actions/timing.ts`): absent Start is 0, absent SourceIn is 0, and an absent bound means the node runs for its whole source, or 16s (`DEFAULT_DURATION_FRAMES`) when it has no source. Scenes and groups without an End still fit their children.-- **Every bound caps, so the shortest wins.** With more than one present, none silently overrides another: an End that reaches past the source runs out of frames, a SourceOut past the asset does too, and the asset length caps both. Source-side spans divide by the rate to become timeline frames. The asset length only participates when there is an asset: a shape or a text has nothing to run out of, so its 16s is a default rather than a cap.-- Because the caps are read at resolve time, nothing rewrites authored values behind the user's back. `clampTrimToAssetDuration` is gone: swapping in a shorter asset shortens the clip on its own, and swapping a longer one back in gives the authored bounds their reach again.-- `Computed.delay` was renamed `Computed.origin` (the scene frame carrying source frame 0, which is what the field always held) and `Computed.playbackRate` joined it as a mirror, so the per-frame path reads the rate from the same record as the bounds it scales. `Computed.start/end` land on whole frames; `origin` keeps its fraction so audio scheduled against it doesn't inherit a half-frame of slip.-- Editing helpers replaced the old frame-math ones: `trimEntityIn/Out(world, entity, frame)` move an in/out point at a scene frame (`computeTrimStart/End` only produced the local frame and left callers to write the trait). `trimEntityIn` pins the implied End first, so trimming the head no longer drags the tail along, and writes SourceIn since a head trim is what defines one. `trimEntityOut` writes SourceOut only when the node already carries one, keeping the common case down to a single trait. Overlap resolution (trim/split on drop) is the only runtime caller so far.-- The five traits share one observer loop (add/change/remove all propagate through the subtree, since a child is placed against its parent's origin). Removal passes the trait being removed down to `recomputeEntityTimeRange` as `ignore`, because koota fires onRemove *before* it clears the trait: without that, `entity.remove(End)` would compute against the End that is going away. Same koota quirk `rebuildCaches`'s `exclude` param exists for.--## Deliberate semantic changes vs bitecs--- Single-value components became `{ value }` traits (Rotation, Name, Volume, Geometry, Paint, ...). `Playback.playing/loop` and `AudioPlayback.wasPlaying` are booleans on the trait, mapped to/from 0/1 at the serialize boundary.-- `Caption.colors` and `Shader.uniforms` are copied on restore (fixed latent aliasing between clones from shared records).-- Restoring `Size` no longer calls `resizeEntity`; it is a plain set (resize side effects belong to actions).-- Motion has no iteration ordering (bitecs used `Hierarchy(ChildOf)`, but the loop only writes the entity's own Computed and its sub-entity cluster, so order cannot matter). Also no top-level exclusion: anything carrying animation data animates. Under bitecs, keyframed scenes promoted to top level silently froze; now they play. If freezing is wanted, strip tracks in the promotion action.-- There is no Deleted tombstone: `deleteEntity` is `entity.destroy()`; ChildOf is autoDestroy 'orphan' so the subtree cascades. Undo re-creates entities from history (entity ids are not stable across delete/undo — key external refs by `Key`).-- Actions are plain world-first functions (matching queries/systems), not koota `createActions`: they return entities/records and call each other freely, which the bound-record pattern only obscures. No history layer: bitecs `world.history.push/transaction` wrappers are gone; actions write directly and the app groups undo steps by observing koota events. Selection-scoped actions (group, frame, reorderSelection, clipboard) still key off the runtime-defined `Selected` trait.-- appendChild/removeChild dropped their bitecs side calls: `persistEntity`, `syncInteractiveState`, `rebuildTimelineIndex` (app-side via observers/signals) and `disconnectAudioBus` (media slice; decoder/bus disposal hooks return with it). `unpersistEntity` and the dispose* helpers from `api/utils.ts` were likewise not ported yet.-- Observers: the runtime half of `api/observers.ts` became koota subscriptions in `world/observers.ts` (`observeWorld`, auto-registered by `createRuntimeWorld`). appendChild/removeChild are assert + re-target only; cache/size/constraint/time-range fixups ride the ChildOf add/remove events, so `cloneFromRecords`/restore prime Cache, Computed, and time ranges through the same path as actions. `rebuildCaches`/`aggregateKeyframeTracks` take an `exclude` param because koota fires relation remove events while the departing child is still in the old parent's queries.-- Observer-driven behavior faithful to bitecs: Sequential onAdd group-ifies and strips spatial traits; Group/Scene/Audio onAdd and Paint/AssetId onChange run the timing recomputes; Start/End/SourceIn/SourceOut/PlaybackRate add/change/remove propagate them through the subtree; Keyframe/ItemIndex onChange resort caches; ChildOf onRemove rebuilds caches (+ `reactToChildDetached`, skipped when the parent is already destroyed). Authored→Computed mirrors register on add and change; trait removal does not reset Computed (same as bitecs).-- Not faithful on purpose: keyframe auto-sync on authored edits did not move into observers. koota change events don't say which field changed, and syncing every field of a trait would mint spurious keyframes on untouched properties. Editing surfaces call `syncKeyframeTrack` for the property they changed (resizeEntity already does for width/height).-- Size propagation is a Size observer now (`propagateSize` on add/change): bitecs restored sizes through `resizeEntity`, koota deserialization is a plain set. `resizeEntity` no longer calls propagateSize itself.-- Still app-side from `api/observers.ts`: persistence scheduling, timeline index rebuilds, `syncInteractiveState`, Selected waveform show/hide, ClipHeight/Expanded, ExportSettings defaults, drag-origin traits.-- Media handle traits renamed with a `Handle` suffix (`VideoDecoderHandle`, `AudioBusHandle`, ...) and typed to the concrete classes via type-only imports, so the trait and the class it stores (`AudioDecoder`, `HtmlHost`, ...) share one export surface without colliding. Resolvers are entity-based (`resolveVideoDecoder(world, entity)`), read Assets/Mode world traits, and store instances with add+set on the handle trait.-- Dispose hooks are observers now: every `*Handle` trait disposes its value onRemove (destroy removes all traits, so deletion is covered without a subtree walk), Culled onAdd disposes decoders, ChildOf add/remove disconnects audio buses, and `reactToAssetChange`'s Caption branch drops the caption decoder. `src/media/dispose.ts` keeps only `disposeDecoders`/`disconnectAudioBus` for the still-alive cases.-- TextStyle became all-undefined defaults: a range override carries ONLY its explicitly set fields (sparse store slot = inherit from the node), which is what the bitecs set-observer's TextRange special case enforced. Node-level fallbacks (16px/Inter/400/leading 1) live in the text renderer's accessors, restoring the bitecs `?? 1` leading semantics the earlier trait defaults had drifted from.-- Caption presets write playhead-driven text via `setChars` (raw store write, no change events) so per-frame caption content never reaches app persistence, same as the bitecs raw array writes. Preset fills/ranges go through createEntity/appendChild, so caches prime via the observers.-- DOM caveats, all lazy (nothing touches DOM at import time): HtmlHost/SurfaceHost create elements at construction (html-in-canvas is Chromium-flag-only anyway), ShaderHost needs WebGPU, `loadWebFont` no-ops without FontFace. tsconfig gained `DOM.Iterable` + `@webgpu/types`.-- `SequenceDecoder` iterates the structural `AssetDirectoryHandle` (entries with `getFile`) instead of concrete FileSystemFileHandle, so node hosts can feed frame directories.-- Playback: the bitecs top-level query `Not(ChildOf('*'))` became `ChildOf(document)`. Playhead advance, auto-stop, and visibility/localTime writes stay raw store writes (no change events, same as bitecs), and `AudioPlayback` is lazily added to playback roots on first tick. `resolveAudioBus` returns null when the world has no AudioEngine context (headless-without-audio; `AudioDecoder.playTo(null, ...)` already no-ops), and the context/offset reads guard the same way. The transition-cleanup `removeComponent(..., false)` became a plain `entity.remove(Transition)`; the app's history layer must treat Transition onRemove during a tick as system-driven, not undoable.-- Render: `world.hitRegions` became the `HitRegions` world trait. The render system pushes CALLBACK-LESS entries ({ kind: 'entity', id } for Interactive entities, { kind: 'hud', id: 'canvas', quad } for the stage in realtime); the bitecs handleGeometryInteraction/handleCanvasInteraction bindings are the app's: its input system clears the list each frame, pushes HUD controls with handlers attached, and maps callback-less targets to its default handlers. In headless worlds nothing pushes (Interactive is app-added, the canvas region is realtime-only), so the list cannot grow unbounded without an input system draining it.-- Render's top-level query `Not(ChildOf('*'))` became `ChildOf(document)`, like playback's. `getScaledImageProps` reads the ScaleMode trait against the ScaleModeType enum. `drawRectPath`, `renderFills`, and `renderNode` stay exported (HUD and thumbnail code consume them app-side).-- Encoders live in `@diffusionstudio/encoder` (deps: runtime, mediabunny, koota), which imports ONLY the runtime's public API — the boundary that motivated the extraction. `ContainerFormat` stays in the runtime (`src/capture/format.ts`) because the ExportSettings trait persists it; the encoder re-exports the type. Nothing inside the runtime may import the encoder (cycle), so encoder-driven utilities like `utils/captions.ts` stay app-side or move into the encoder package.-- Encoder API changes vs `engine/encode`: `config.scene`/`config.entity` are Entities; `realizeMounts` is injected via config (mount realization needs the host app's module loader + @diffusionstudio/jsx); the hardcoded "Made with Diffusion v..." metadata tag became `config.comment`; the bitecs `Hierarchy(ChildOf)` two-pass rescale walks became `recomputeAllTimeRanges` (exported) over `propagateTimeRangeDown` from the document's top-level nodes; and both encoders now dispose decoders and `world.destroy()` their throwaway offline worlds in `render()`'s finally (koota caps live worlds at 16 — bitecs could just drop them). Offline-world wiring is world traits (`Mode`/`Assets` shared by reference/`Fonts` copied/`RenderSurface`/`AudioEngine`/`FrameRate`/`FramePromises`) instead of the context bag; playhead/Playback/AudioPlayback writes stay raw store writes, matching the systems.-- The encoder package's tsconfig must mirror the runtime's (`DOM.Iterable`, `@webgpu/types`, plus `@types/audioworklet`): runtime exports point at TS sources, so consumers compile them with their own compiler settings.-- The active scene is the `Active` tag trait on the entity (`traits/interaction.ts`), not a world trait: `getActiveEntity(world)` / `setActive(world, entity | null)` in `actions/frame.ts` (was `ActiveScene` + `switchActiveScene`). Timeline buffer clearing and index rebuild stay app-side. `frameSelection` calls it once (bitecs called it redundantly inside and outside the transaction).-- `insertAssetInTimeline` returns the created entity or null when no scene is active (no toast). Folder ops are sync and return the changed records (`deleteFolder` returns removed folder/asset ids) so the app can persist; `moveAssetsToFolder` updates records in place instead of re-fronting them like `saveAsset` did. Panel navigation state (current folder) stays app-side.-- Decoder/host handle traits (`src/traits/media.ts`) are AoS traits typed as opaque `object` until the decoders move in; `entity.get(VideoDecoder)` returns the instance directly.--## koota facts learned (0.6.6)--- **Local patch (do not lose):** `patches/koota+0.6.6.patch`, applied by the root `postinstall` (`patch-package`). Fixes `checkQuery`/`checkQueryTracking`: `Or(...)` was evaluated per trait bitmask generation (32 traits each) and required a match in every generation, so Or queries created after the Or'd traits straddle a generation boundary silently returned empty. On a koota bump, retest (register 40 dummy traits, then create a fresh Or query) before dropping the patch.-- `Not(...)` accepts plain traits only. Relation pairs, wildcard or concrete (`Not(ChildOf('*'))`, `Not(ChildOf(doc))`), throw at runtime. If an indexed exclusion is ever needed, maintain a tag via `onAdd/onRemove(ChildOf(target))` observers.-- No hierarchy-ordered queries (bitecs `Hierarchy(ChildOf)` has no equivalent). Transform does its own parent-first DFS from the document; that ordering is load-bearing there (world matrices, cull inheritance).-- Trait schemas allow primitives/null/undefined; object or array fields need callback initializers (`colors: () => [] as number[]`). AoS traits: `trait(() => instance)`.-- World traits are backed by a hidden internal world entity (`world[$internal].worldEntity`, IsExcluded). Do not build on it; it is not public API. `world.id()` is a world slot index, not an entity.-- Max 16 live worlds. Entity numbers encode worldId+generation; stores are indexed by `entity.id()`.-- Entities read back from store arrays / trait fields keep their methods (they are numbers; koota patches the prototype).-- `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.-- **Projects on disk (desktop only)**: `apps/web/src/projects/` loads real content into the koota world. A project is a folder under a user-picked root (persisted in `dspro.ui.projects.root`) holding an `index.tsx` whose default export renders `<stage>`; the electron main process (`apps/desktop/src/projects.ts`) scans the root, scaffolds new folders (`index.tsx`, `package.json`, `tsconfig.json`, generated `jsx.d.ts`), bundles with esbuild + babel-preset-solid (universal, moduleName `@diffusionstudio/jsx`) and watches for changes. The new `@diffusionstudio/reconciler` package (`packages/reconciler`, modeled on ds-next's `src/reconciler/`) evaluates the CJS bundle against the app's solid-js and `@diffusionstudio/jsx`, and its `RuntimeDocument` implements `ProjectDocument` over the world (`mount(code, world)` wraps both): `<stage>` = the infinite canvas, i.e. the Stage entity itself (`background` sets the Background world trait; no size, no camera fitting), `<scene>` = a top-level clipped, playable frame (the `frameSelection` recipe: RECT geometry + `Scene`/`ClipsContent`/`Playback`, minus the solid fill child, since `fill` is the entity's own trait), `<rect>` = a RECT entity (x/y/width/height; `fill` is the entity's own `Color` trait — an intrinsic solid fill rendered first, beneath any Paint children — so a filled rect needs no sub-entities). `start`/`end`/`sourceIn`/`sourceOut` are the authored time traits of the same name: `parseTime` turns seconds, `"30f"`, and clock strings into seconds, and the host converts to project frames against the `FrameRate` trait (so `"30f"` is one second of the canonical 30fps unit, 60 frames in a 60fps project). Absence is meaningful on all four, so an unset or unparsable prop removes its trait instead of writing a zero, which is also what a reactive prop going undefined does. Host nodes wrap entities in objects because Solid's universal renderer treats numbers as text. `useProject(name)` (`apps/web/src/projects/use-project.ts`, called from `pages/editor.tsx`) compiles → renders → re-renders on disk changes. Routes: `/` is the full-screen dashboard (`pages/home.tsx`, no longer a dialog), `/projects/*name` is the editor with the project folder `name` loaded (`useProjectId()` reads it from the route); the old default project id is gone, so there is no editor without a project. Only those three tags so far, handling `name`, `x`/`y`, `width`/`height`, `fill`, `background`, `camera`, and the four time props; no write-back from canvas edits to source yet (`editProperty`/`reportEdit` exist and the sink is wired, but nothing on the canvas calls them; an editor moving a clip converts frames back to seconds itself with `framesToSeconds`).-- **The `<scene>` slice.** The `scene="id"` prop that promoted a `<rect>` is gone (dropped from `PatchProps`, `CommonProps`, and the `PATCH_PROP_KEYS` allowlist): it existed to give a mount root an identity across partial mounts, and with `<stage>` standing for the whole document and `id`/`SOURCE_ATTR` carrying identity, nothing was left for it to do. What the tag added beyond the entity recipe:- - **`x`/`y` on a scene are authored.** The old reference model made canvas placement an editor concern with no JSX spelling. That cannot hold once the source is the document: a scene dragged on the canvas has nowhere to be written back to. Same reasoning as `<stage camera>`.- - **`insertNode` re-parents.** It previously only rewrote `ItemIndex`, so every element landed under the stage regardless of nesting. Harmless while `<stage>`/`<rect>` were the whole vocabulary; fatal for a frame that has to contain its children. A move between two non-stage parents goes back through the stage, because `appendChild` asserts top-level.- - **Ordering compares entities, not handles.** `children()` mints a fresh `{ entity }` per lookup, so the old `siblings.indexOf(node)` in `insertNode`/`getNextSibling` never matched: anchors were ignored (every insert appended) and `getNextSibling` always returned the first child. Only reachable through `<Show>`/`<For>` reordering, which nothing exercised yet.- - **`ActiveScene`**: the first scene a render produces claims it if no live scene holds it; `removeNode` clears it when the holder goes. The timeline has to point somewhere, and which scene is being worked on afterwards is the editor's state, not the document's.- - Nested `<scene>` throws (the runtime forbids it); `name` joined the handled props.-- **The `key` prop went with it**, for the same reason: it was a within-render label letting elements point at each other (`syncTo` named a clip's `key`), which is the job `id` already does, and unlike `key` an id survives an edit that renumbers the file. So `syncTo` now names an `id`. Dropped from `PatchProps`, `CommonProps`, and `PATCH_PROP_KEYS`. The runtime's `Key` trait is untouched and unrelated: it is the ECS-side stable identity that clone/paste external refs key off (entity ids do not survive delete/undo), and nothing on the JSX path ever wrote it.-- **Element insertion (write-back of new elements).** Editing commands live app-side in `DocumentEditor` (`apps/web/src/engine/editor.ts`, one per world via `getDocumentEditor(world)`, hook `useEditor()`; the reconciler exports `insert`/`withDocument` for it), not in `RuntimeDocument`, which stays a plain `ProjectDocument` host: `onEdit`, `editProperty`, `reportEdit`, `insertElement`, `restamp`, `discardPending`. `editor.insertElement(parent, () => <Rect x={10} width={200} height={300} />, anchor?)` renders the thunk through Solid's universal `insert` under `withDocument` with a recording proxy of the document (same host, every `createElement` stamped pending and `setProperty` noted; the document never learns it was watched), so it goes through the document's own `createElement`/`setProperty`/`insertNode` and is a first-class node on the canvas at once, no remount. The app's JSX compiles for the DOM, so lowercase `<rect>` is unusable there; the PascalCase components (`Rect`, `Scene`, ... now exported from the reconciler index) compile identically in both modes and are the spelling to use. `createElement` lowercases the first letter, so both spellings reach the same recipe. While the thunk renders, every element created is stamped with a pending source (`pending#n`, colon-free so `parseSource` rejects it as an address) and its tag + literal props recorded; afterwards one `InsertEdit` per element is reported in creation order (`EntityEdit` is now `PropEdit | InsertEdit`, discriminated by `kind`), a nested `<Scene><Rect/></Scene>` naming its parent by pending source, and `before` set to the next pre-existing sibling. Returns the top-level entities created. The desktop `applyEdits` grew a matching `SourceInsert` (`SourceEdit = SourceSet | SourceInsert`): it appends `<tag {...props} id="…" />` under the parent (or in front of `before`, which must be a direct child) as text edits at positions ts-morph supplies (`getIndentationText`/`getChildIndentationText`/`isFirstNodeOnLine`, with `manipulationSettings.indentationText` matched to the file first since ts-morph does not detect it; it has no insert-child or open-self-closing operation short of re-printing the body), props via the same `setProp`/`addAttribute` path as prop edits, allocates the id on the spot, and answers with `ids[pending] = real`. A pending parent earlier in the same batch resolves through that map, so a rect drawn into a just-drawn scene lands in one write. The `EditWriter` class (`apps/web/src/projects/edits.ts`) sends inserts first, folds prop edits into a not-yet-flushed insert, holds back edits (and child inserts) addressed through an in-flight pending name until the answer arrives, then re-keys them and re-stamps entities via `DocumentEditor.restamp`; an insert the file would not take (`skipped`) is undone on the canvas via `DocumentEditor.discardPending`. `<text>` is hosted too: the recipe is TEXT geometry + `Chars` + `TextStyle` and no `Size` (a text without one sizes itself to its glyphs, which is what a click-inserted text wants); `color` writes the entity's `Color` (the intrinsic fill the text renderer already draws glyphs with, so no paint child), and `fontSize`/`fontFamily`/`fontWeight`/`fontStyle`/`textAlign`/`textBaseline` write `TextStyle` (an unset or invalid value clears the field to `undefined`, i.e. the renderer's default). Text content travels as Solid text nodes, and the runtime has no node for those, so a plain `TextNode` object (`{ text, parent }`, `HostNode = SceneNode | TextNode`, `isSceneNode` narrows) stands in for the DOM text node the way the original bitecs host's `{ kind: "text" }` did: held by identity (Solid compares handles with `===` and calls `replaceText(getFirstChild(parent))`), kept per text entity in an ordered list, and the list's join is the entity's `Chars`, so `<Text>Hello {name()}</Text>` reconciles through `replaceText`/`insertNode`/`removeNode` on the text nodes alone. Text under anything but a text entity throws, as does an entity under a text. `insertElement`'s recording proxy passes text nodes through untouched (only `SceneNode`s are stamped/recorded). Not built yet: the DrawOverlay port itself.-- **Draw tools (`components/canvas/draw-overlay.tsx`) and Toolbar are on the koota world.** The armed tool is the `Tool` world trait (`traits/interaction.ts`, attached by `createRuntimeWorld`; read with the app's `useTool()`, written with `world.set(Tool, { value })`). Toolbar and the sidebar ToolMenu write it; the bitecs keyboard system's V/H/F/R/T shortcuts still target the old world and stay dead for the new tools until it migrates. Drawing goes through `DocumentEditor.insertElement` with the reconciler's `Scene`/`Rect`/`Text` components (`fill`/`color` instead of a `SolidPaint` child), so a drawn element is written to the source like any authored one; a draw with no mounted project is a no-op. `InsertEdit`/`SourceInsert` gained `text` for a text element's literal content (`Chars` after render), which the desktop writer emits as `<text id="…">Hello</text>` (bare when JSX reads it back verbatim, `{"…"}` otherwise). Runtime gained `findSceneAt`/`worldToLocal` (`queries/hit-test.ts`), reading `LocalTransform` from the store like `getEntityBounds`. Not carried over: `world.history.transaction` — there is no undo layer yet.-- **Selection is a document property.** `selected?: boolean` joined `PatchProps` (picked into `CommonProps` and `SceneProps`, listed in `PATCH_PROP_KEYS`), for the same reason `<stage camera>` and `<scene x y>` exist: the source is the document, so a click on the canvas has nowhere else to be written to, and it means the selection survives the unmount/remount every recompile does. `RuntimeDocument.setProperty('selected')` adds the runtime's `Selected` trait for `true` and removes it for anything else (a bare attribute, a reactive prop going undefined; the stage is never selectable). The editor direction is `DocumentEditor.select(entities, { extend? })` / `deselect` / `clearSelection` (`apps/web/src/engine/editor.ts`): they write the trait and report a `selected` prop edit per entity that changed, `false` for the ones deselected. Selection surfaces go through these rather than touching `Selected` directly (DrawOverlay and SceneInitOverlay do), so nothing else has to know it is a source prop; not an observer on the trait, because a mount adding `Selected` from the file, or an unmount destroying selected entities, must not report as edits. The desktop `setProp` writes `false` as the attribute's absence (`attribute.remove()`), so deselection never leaves `selected={false}` behind, and the same now holds for any boolean prop (`muted`). Not carried over: the bitecs `selectStage/Parent/ChildEntities` helpers and the input system's click/marquee selection, which are still on the old world.-- **The active entity is a document property too.** `active?: boolean` in `PatchProps` (picked into `SceneProps` only for now; the scene restriction is a single assertion in `setActive` and goes when it goes), listed in `PATCH_PROP_KEYS`. The `ActiveScene` world trait is gone; `Active` is a tag on the entity, so it dies with the entity (no clearing in `removeNode`) and comes back from `<scene active>` on remount. Two invariants live in `world/observers.ts`, so they hold whichever path adds the tag: `onAdd(Active)` strips it from every other holder (last wins), and `onAdd(ChildOf('*'))` strips it when the new parent is not the stage (root only). The ChildOf half is what catches a nested `<rect active>` from a file, because Solid sets props before insertion while the entity is still a stage child; the cost is that such a rect first steals the tag and then loses it, so a file saying `active` on a scene and on something nested inside it ends with nothing active until the mount fallback below. `DocumentEditor.activate(entity | null)` is the editor route (trait via `setActive`, `active: false` reported for the one it left, `true` for the new one); overlays use it, the encoder calls `setActive` directly (headless, nothing to report), `useActiveScene()` reads `useQuery(Active)[0]`. `pages/editor.tsx` activates the first root scene through the editor after a mount that produced no active entity, so a project without one gets it written into the file and it sticks. A file naming two active scenes keeps both until the next `activate` cleans up; the document does not report edits.-- **Left stale on purpose** (deferred to a docs/examples pass): all eight `examples/*.tsx` still open with `<rect scene="...">` and no `<stage>`, so `tsc -p examples --noEmit` fails on them; `reference/jsx/{scene,roots}.md` still describes the pre-`<stage>` model where a mount grafts roots into an existing document; and `reference/jsx/{audio-sync,video,audio,elements}.md` still document `key` as the `syncTo` target. Deliberately not half-migrated: `reference/jsx` is stale as a whole, and patching the `key` rows alone would hide that.--## Remaining work (suggested order)--1. **App rewrite** (`apps/web`): app-side world traits (store, timelineIndex signal; input/HUD are done), 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-adding the editing-surface `syncKeyframeTrack` calls the observers slice dropped, 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--- Package exports: root `.` plus `./traits`, `./systems`, `./media`, `./capture` (see package.json). Everything currently also re-exported from root `src/index.ts`.-- tsconfig sets `erasableSyntaxOnly: false` (enums with reverse lookups, same as apps/web).-- Deps: koota (patched), mediabunny, animejs, sqids (asset/folder id allocation), colord (parseColor). Dev: @webgpu/types (shader host).-- AoS handle traits accept class instances and null through plain `entity.set(trait, value)`; `getStore` returns the value array.