Skip to content

The VS Code of video editing, built for agents.

TypeScript

Refactor migration documentation for bitecs to koota transition

konstantin-paulusab54dd937e7a
diff --git a/packages/runtime/MIGRATION.md b/packages/runtime/MIGRATION.md
index ae0a458c..6c363699 100644
--- a/packages/runtime/MIGRATION.md
+++ b/packages/runtime/MIGRATION.md
@@ -1,188 +1,103 @@
# 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.
+Working doc for moving the editor engine from bitecs (`apps/web/src/components/engine/`) into this headless runtime package, and for tracking how far `apps/web` has gotten consuming it. Kept short on purpose: the code carries the "how", this carries what a fresh session cannot read off it.
-## 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.
+## Ground rules
-## Deliberate semantic changes vs bitecs
+- `@diffusionstudio/runtime` holds everything that runs without a DOM and without solid-js (the CLI/node capture path consumes it). Browser-only systems (input, keyboard, camera, HUD, dom sync, timeline UI), persistence, history and Solid reactivity stay in `apps/web`; Solid bindings live in `packages/koota-solid`.
+- Persistence to IndexedDB is **not** required for now. `EntityRecord` (`src/world/serialize.ts`) is an in-memory snapshot format for copy/paste, duplicate and split-on-overlap only, free to change.
+- Breaking API/type changes inside the codebase are fine.
+- Comments: lean, only constraints the code can't show. No em dashes in prose. Tabs, MPL header on ported files.
-- 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, change and remove (removal re-derives from the traits left, so an unset prop falls back to its default; see the AppearanceSettings slice).
-- 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.
+## Runtime package
-## koota facts learned (0.6.6)
+Fully ported. Layout: `src/traits/*` (~85 components split by concern), `src/world/` (create-world, `store`, serialize, observers), `src/queries/`, `src/systems/` (playback → motion → transform → render, sequenced by `runSystems`), `src/actions/`, `src/media/`, `src/math/`, `src/fonts/`, `src/utils/`. Encoders live in their own package, `@diffusionstudio/encoder`.
-- **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.
+Call-outs that outlive the port:
-## App integration progress (apps/web)
+- Use `store(world, trait)` (`src/world/store.ts`) in systems, never bare `getStore`: koota registers stores on first add/query, so `getStore` throws on a fresh world.
+- Renames: the `ScaleMode` enum is `ScaleModeType` (the trait took the name); `Computed.delay` is `Computed.origin`; predicates lost the world param (`isScene(entity)`); `TimelineNode.eid` is `entity: Entity`; media handle traits carry a `Handle` suffix so trait and class can share an export surface.
+- Nothing in the runtime may import the encoder (cycle). The encoder's tsconfig must mirror this one (`DOM.Iterable`, `@webgpu/types`, `@types/audioworklet`), since exports point at TS sources and consumers compile them.
+- DOM access is lazy everywhere; nothing touches DOM at import time.
+- Verification so far: `npx tsc --noEmit` in the package plus a throwaway `smoke-test.tmp.ts` run with `npm exec --yes tsx@latest`, deleted afterwards. No test infra in the package yet.
-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.
-
- **`<group>` and `<sequence>` are hosted.** A group is `Group` + `Position` and no `Size` (its box is the union of its children, resolved by `computeGroupBounds`; `resizeEntity` already drops `Size` on groups, so an authored `width`/`height` is a no-op). A sequence is just `Sequential`: the runtime's onAdd observer adds `Group` and strips the spatial traits, and the document refuses to write `x`/`y`/`offsetX`/`offsetY`/`rotation` on a `Sequential` entity afterwards, since the observer only strips once. Both take `name`, `selected`, the four time props, and `fill`; everything else falls through to the generic prop handling. Note the transform system computes a group's bounds from its children's local matrices as of the previous pass, so a freshly mounted group is one tick behind (same as bitecs; `groupSelection` refreshes children explicitly).
+## Stage model
- **Duplicate (cmd+d).** `DocumentEditor.duplicate(entities)` copies the tops of the selected subtrees: the reconciler's `authoredTree(world, entity)` reads each back as JSX vocabulary (tag, props, text, authored children; runtime sub-entities are left out and come back with the recipe) and `renderAuthored(tree)` rebuilds host nodes from it inside `insertElement`'s thunk, so a copy is a first-class insert (pending sources, nested inserts naming their pending parent, `before` set) with the same props and parent as its source, anchored at the source's next sibling so it draws on top. A source inside a sequence would collide with itself, so the copy goes to the nearest non-`Sequential` ancestor, right after the sequence it left (a sequence has no spatial identity or time of its own, so the same props put it in the same place). `selected`/`active` are not copied; the selection moves to the copies. `duplicateSelection` in `input/shortcuts.ts` binds it to mod+d. **Copy/paste (mod+c / mod+v)** reuse the same pieces: `editor.copy(entities)` keeps the spelled trees plus the stamp of the parent they came from in an editor-held clipboard (in-app only, no system clipboard: the shortcut system runs per frame, outside any user-gesture handler), and `editor.paste(parent, anchor?)` inserts them there, moving the selection to the copies. `pasteSelection` picks the target: a selected scene/group pastes inside it (appended, on top), a selected leaf pastes on top of it in its parent, no selection pastes into the active scene. Pasting into the sequence the trees were copied out of (by stamp) escapes to that sequence's parent, right after it, as duplicate does; a different sequence takes the paste as is.
+Every world spawns one `Stage` entity; all rendered entities descend from it. "Top-level" means "direct child of the stage", never "has no parent".
- **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.
+- `world.get(Root)` is it, `isStage()` tests it, `getParentNode()` returns null when the parent is the stage (use it wherever top-level matters), `getParentEntity()` returns the raw parent including the stage.
+- `ChildOf` is `{ exclusive: true, autoDestroy: 'orphan' }`, so destroying the stage tears down the document; clearing a project is destroy + respawn.
+- The stage id is per-session: `serializeEntity` omits `ChildOf` to the stage and `cloneFromRecords` attaches parentless records to the target world's stage. `appendChild` asserts top-level and relies on exclusive re-targeting; `removeChild` re-parents to the stage rather than dropping `ChildOf`.
- **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.
+## Authored time model
- **`<stroke>` and `<shadow>` are hosted** (`StrokeProps`/`ShadowProps` in `@diffusionstudio/jsx`, `stroke`/`shadow` in `IntrinsicElements` and `COMPOSITION_TAGS`, `Stroke`/`Shadow` components in the reconciler), as sub-entity children of any geometry (`<rect>`, `<text>`, `<video>`, `<image>`; a `<text>` takes them next to its text nodes, alongside paints), stacking in document order. A stroke is `Stroke` + `Paint(SOLID)` + `Color` + `StrokeStyle`: `color`/`opacity` are its paint, `width` (the line width, since a stroke has no box: `setProperty('width')` branches on `Stroke` instead of resizing), `join` (`miter`/`round`/`bevel`), `cap` (`butt`/`round`/`square`) and `miterLimit` fill `StrokeStyle`, an unset one falling back to the trait's default. A shadow is `Shadow` + `Color`, with `opacity`, `blur` (new in `PatchProps`, writes the `Blur` trait), `offsetX`/`offsetY` (the same `Offset` trait a node's render offset uses). Two runtime changes came with it: **`StrokeStyle` moved from the stroked node onto the stroke sub-entity**, so each stroke has its own width/join/cap (`Computed.strokeWidth` and the `stroke.width` keyframe target are per stroke; `utils/stroke.ts` has `applyStrokeStyle`, which the render system and the text renderer call per stroke, and `findWidestStroke`, whose silhouette a stroked text's shadow takes), and `Cache.fills` excludes `Stroke` entities, since a stroke's `Paint` is what its outline is drawn with, not a fill of its parent (bitecs collected them into both). Not built yet: gradient strokes in JSX (`<stroke>` is solid only; the runtime still renders a stroke entity carrying a gradient `Paint` with `ColorStop` children).
+`Delay`/`Trim` became four one-value traits in the JSX's vocabulary, all frames: `Start`, `End` (parent-relative placement) and `SourceIn`, `SourceOut` (the slice of the node's own source that plays). One trait per value because a clip rarely says more than one of these, and absence is the usual answer.
- **`<effect>` is hosted** (`EffectProps` in `@diffusionstudio/jsx`, `effect` in `IntrinsicElements` and `COMPOSITION_TAGS`, `Effect` component in the reconciler): one element for every filter effect, `<effect type="blur" value={8} />`, a sub-entity child of any node (`<group>` included: the filter applies to the group's rendered pixels as a whole), stacking in document order like the CSS filter list `buildEffects` turns them into. `type` (`blur`/`brightness`/`contrast`/`grayscale`/`hueRotate`/`invert`/`saturate`/`sepia`, new in `PatchProps` as `EffectType`) maps onto the runtime's `EffectType` enum minus `DROP_SHADOW`, which is `<shadow>`'s; `value` (new in `PatchProps`, animatable: the `effect.value` keyframe target) is px for a blur, degrees for a hue rotation, 0-1 otherwise, and both are required, since the trait's zero value is meaningless for most types (a brightness of 0 is black). The recipe is the bare `Effect` trait, created as a blur of 0 (a no-op) until `type`/`value` arrive; an unknown `type` falls back to that too. Per-type tags (`<blur>`, `<sepia>`, ...) were considered and rejected: `blur` is already the name of a prop, and one tag with a `type` keeps the effect list a list.
+- Defaults (`resolveDuration`): absent Start/SourceIn are 0; an absent bound means the whole source, or 16s (`DEFAULT_DURATION_FRAMES`) without one. Scenes and groups without an End fit their children.
+- **Every bound caps, shortest wins**: nothing silently overrides anything, and caps are read at resolve time, so no value is rewritten behind the user's back (`clampTrimToAssetDuration` is gone: a shorter asset shortens the clip, swapping back restores the reach).
+- `trimEntityIn/Out(world, entity, frame)` move an in/out point at a scene frame. `trimEntityIn` pins the implied End first so a head trim doesn't drag the tail; `trimEntityOut` writes SourceOut only when one is already authored.
+- The five timing traits share one observer loop, propagating through the subtree. Removal passes the departing trait as `ignore`, because koota fires onRemove *before* clearing it.
- **`<keyframeTrack>` and `<keyframe>` are hosted** (`KeyframeTrackProps`/`KeyframeProps` and `AnimatableProperty` in `@diffusionstudio/jsx`, both tags in `IntrinsicElements` and `COMPOSITION_TAGS`, `KeyframeTrack`/`Keyframe` components in the reconciler): the addressable form of an `Animatable` prop's keyframe list, so an editor moving a keyframe has an element (and id) to write it to. `<keyframeTrack property="x">` sits under the element whose prop it drives (any node, paint, color stop, stroke, shadow or effect: the runtime's `KeyframeTrack` is `ChildOf` its target) and holds `<keyframe time value easing />` children in any order (`Cache.keyframes` sorts by frame). `property` is the prop's JSX name and resolves through `TRACK_PROPERTIES` to the runtime's `PropertyPath` (`x` -> `position.x`, `cornerRadius` -> `vertexRadius`, `offset` -> `stop.offset`, `value` -> `effect.value`, ...); `width` under a `Stroke` is `stroke.width`, so the path is (re)resolved on insertion, since Solid sets props before the track has a parent (`resolveTrackProperty`). `time` is node-local and goes through `parseTime` + `secondsToFrames` like the timing props; `value` is a number, or a CSS color on a color track (`parseColor`); `easing` maps the named presets to the descriptors the runtime's `resolveEasing` and the interpolation inspector speak (`easeIn` -> `cubicBezier(0.42,0,1,1)`, `gentle` -> `spring(0.5,628)`, ..., `linear` -> `""`; descriptors pass through with whitespace dropped). `PatchProps` gained `property`, `time`, `easing`, and `value` widened to `Animatable<number> | string` (`EffectProps` narrows it back). One runtime fix came with it (`actions/cache.ts`): `rebuildCaches` re-aggregates a node's `Cache.keyframeTracks` not only when a track is attached but also when a non-node sub-entity carrying tracks is (`carriesKeyframeTrack`), because JSX builds bottom-up: a paint's tracks are attached to the paint before the paint meets its rect, and the old (bitecs) code only ever saw tracks attached to already-placed targets. Not decided yet: whether the inline `Animatable<T>` keyframe arrays stay (the host does not expand them; a static value is what `setProperty` handles) or the tags become the only spelling.
+## Decisions the code doesn't show
- **`<animation>` is hosted** (`AnimationProps` in `@diffusionstudio/jsx`, `animation` in `IntrinsicElements` and `COMPOSITION_TAGS`, `Animation` component in the reconciler): the element form of one `animations` entry, `<animation type="fade" phase="out" duration={1} delay="15f" />`, a sub-entity child of a node (`Animation` trait, `ChildOf` its target; `Cache.animations` already collects it, the motion system already plays it). `type` reuses the `AnimationType` names (`fade`/`gain`/`grow`/`shrink`/`blur`/`slideLeft`/.../`scramble`, mapped onto the runtime enum), `phase` is `in`/`out`, `duration`/`delay` are `Time` and go to frames like the timing props (defaults 1s / 0, restored when the prop is unset). `PatchProps.type` widened to `EffectType | AnimationType` (`EffectProps`/`AnimationProps` narrow it), and gained `phase`, `duration`, `delay`. `RuntimeDocument.toFrames` now centralises the seconds-to-project-frames conversion the timing props, keyframes and animations share. As with `Animatable`, the `animations?: AnimationSpec[]` list prop is left in the types but not expanded by the host; the tags are what the document builds.
+- **No history layer.** Actions write directly; the app groups undo steps by observing koota events. No `Deleted` tombstone either: `deleteEntity` is `entity.destroy()` and the subtree cascades. Entity ids are not stable across delete/undo, so key external refs by `Key`.
+- **Keyframe auto-sync deliberately stayed out of observers**: koota change events don't say which field changed, so syncing every field would mint spurious keyframes. Editing surfaces call `syncKeyframeTrack` for the property they changed (`resizeEntity` already does for width/height).
+- Actions are plain world-first functions, not koota `createActions`; the bound-record pattern only obscured that they call each other.
+- Motion has no iteration order and no top-level exclusion, so keyframed scenes promoted to top level now play instead of silently freezing. Strip tracks in the promotion action if freezing is wanted.
+- `TextStyle` defaults are all-undefined: a range override carries only its set fields (sparse slot = inherit). Node-level fallbacks (16px/Inter/400/leading 1) live in the text renderer's accessors.
+- `HitRegions` entries are callback-less; the app's input system drains the list each frame and attaches handlers. Headless worlds push nothing, so it can't grow unbounded.
+- The app's history layer must treat `Transition` onRemove during a tick as system-driven, not undoable.
+- Still app-side from the old `api/observers.ts`: persistence scheduling, timeline index rebuilds, `syncInteractiveState`, Selected waveform show/hide, ClipHeight/Expanded, ExportSettings defaults, drag-origin traits.
- **`PatchProps` and `PATCH_PROP_KEYS` are gone.** They were the property table of the old `dapi node patch` command (any subset of props per patch entry, allowlisted at runtime); with the source as the document nothing patches by prop name (edits go through `editProperty`/`insertElement` and the desktop writer), and `PATCH_PROP_KEYS` had no consumer left. `packages/jsx/src/types.ts` now defines small internal prop groups (`IdentityProps`, `PositionProps`, `OffsetProps`, `SizeProps`, `TransformProps`, `TimingProps`, `SequenceItemProps`, `FillProps`, `MediaProps`, `FitProps`, `AudioTrackProps`, `OpacityProps`, `ColorProps`, `CommonProps`, `TrackChildren`) that the element prop types compose, and props one element owns (`type`, `value`, `property`, `time`, `easing`, `phase`, `duration`, `delay`, `join`, `cap`, `miterLimit`, `blur`, the text style, the caption props, `wgsl`/`uniforms`) live on that element's type, so the shared-name unions the table forced (`type?: EffectType | AnimationType`, `value?: Animatable<number> | string`) are gone. Gone with it: the inline `Animatable<T>`/`Keyframe<T>` keyframe arrays and the `animations?: AnimationSpec[]` list (`<keyframeTrack>`/`<animation>` are the only spelling; every prop is a plain value), and `packages/reconciler/src/patch.ts`. `reference/jsx/{keyframes,animations}.md` were rewritten for the tags and the `Animatable`/`animations` rows dropped from `elements.md`/`audio.md`/`captions.md`/`html.md`/`paints.md`; the rest of `reference/jsx` stays stale as noted below.
+## koota gotchas (0.6.6)
- **Static props the runtime already played but the host dropped, plus `<shaderPaint>`/`<surfacePaint>`/`<surface>`.** `cornerRadius` (`CornerRadius`; the `vertexRadius` keyframe path was already mapped, so a keyframed radius worked while a static one was ignored), `transition` on sequence items (`Transition` on the outgoing clip: `{}` is dissolve/1s, a partial value merges, `null`/unset removes; playback still drops it when the parent is not `Sequential`), and four new props: `scale` (`UniformScale`, wins over per-axis while present, as the motion system already resolves it), `scaleX`/`scaleY` (`Scale`), `blendMode` (`BlendMode`, camelCase composite operations, `sourceOver` removes the trait), `hidden` (`Hidden`), `playbackRate` (`PlaybackRate`, 0/unset removes). `scale`/`scaleX`/`scaleY` joined `AnimatableProperty` (motion paths `scale`/`scale.x`/`scale.y` existed). Types: `CompositeProps` (`blendMode`, `hidden`) is in `CommonProps` and in the new `PaintProps` (`OpacityProps` + composite) that all paints and `<stroke>` use; `<shadow>` takes `hidden` only. `<shaderPaint>` is `Paint(SHADER)` + `Shader` (`wgsl` -> `code`, `uniforms` copied); the host resolves lazily from `Shader.code` as before. `<surfacePaint>` is `Paint(SURFACE)`; `<surface>` a rect with an intrinsic (unauthored) surface paint child. Refs are plain Solid refs everywhere: `RuntimeDocument` implements no `applyRef`, so the renderer's `use` falls through to Solid's default and both forms (`ref={fn}`, `ref={variable}`) receive the `HostNode` synchronously. `<surface>` is a rect whose surface is its intrinsic paint, like `<video>`'s media (`Paint(SURFACE)` + `SurfaceHostHandle` on the geometry itself, no child paint; `renderIntrinsicFill` gained the SURFACE branch), `<surfacePaint>` the sub-entity form. Both nodes are `SurfaceNode` (`{ entity, canvas }`, `canvas` a getter over the entity's `SurfaceHostHandle`, typed for authors as `SurfaceHandle` in `@diffusionstudio/jsx`); the `SurfaceHost` is allocated with the element (`attachSurfaceHost`, skipped without a DOM) and sized by `syncSurfaceSize` when a paint meets its holder and whenever the holder's `width`/`height` props are set. `SurfaceHost.setSize` became a no-op for an unchanged size, since assigning a canvas dimension clears the bitmap even at the same value and user code (three.js `setSize`) may already have applied it. Because Solid applies refs before props on the spread path, the canvas seen *inside* the ref callback is not yet box-sized; it is by the time the render returns, and drawing happens in tickers/effects anyway. An earlier draft deferred a canvas-valued ref through `onMount`; dropped for the uniform, synchronous behaviour. A duplicated `<surface>` is a static empty one (its ref is not a `PropValue`), matching the old docs.
+- **Local patch, do not lose:** `patches/koota+0.6.6.patch`, applied by the root `postinstall`. `Or(...)` was evaluated per 32-trait bitmask generation and required a match in every one, 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 it.
+- `Not(...)` takes plain traits only; relation pairs (`Not(ChildOf('*'))`) throw at runtime. Maintain a tag via observers if an indexed exclusion is needed.
+- No hierarchy-ordered queries (no bitecs `Hierarchy(ChildOf)`). Transform does its own parent-first DFS, and that ordering is load-bearing there.
+- Object/array trait fields need callback initializers (`colors: () => []`); AoS traits are `trait(() => instance)` and accept instances or null through plain `set`.
+- Max 16 live worlds; `world.destroy()` in test loops and throwaway offline worlds. Stores are indexed by `entity.id()`; `world.id()` is a world slot, not an entity. World traits sit on a hidden internal entity that is not public API.
+- `set` throws if the trait is missing and merges partials; `add` is idempotent and never resets values, hence add-then-set everywhere. On an exclusive relation, `add` re-targets in place.
+- Events: 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 the `exclude`/`ignore` params in `rebuildCaches` and the timing observers). onAdd fires after initial values are applied and may set traits. onChange fires even when the value is unchanged.
- **Text is fully hosted: the remaining `TextStyle` fields and `<textRange>`.** `TextProps` gained `letterSpacing` (px, `TextStyle.letterSpacing`), `textCase` (`original`/`upper`/`lower`, the new `TextCase` type in `@diffusionstudio/jsx`, mapped onto the runtime enum; the glyphs are cased when drawn, `Chars` stays as written), `leading` (line height as a multiple of the natural line height, `TextStyle.leading`; non-positive/unset removes it), `textBaseline="alphabetic"` (`TextBaseline.ALPHABETIC`, which `shapeTokens` already laid out) and `fontStyle="oblique"` (was mapped, not typed). The font fields (`fontFamily`/`fontSize`/`fontWeight`/`fontStyle`/`letterSpacing`/`textCase`) moved into a shared `FontProps` group because `<textRange>` takes the same ones. `<textRange start end>` (`TextRangeProps`, `textRange` in `IntrinsicElements` and `COMPOSITION_TAGS`, `TextRange` component in the reconciler) is the element form of the runtime's `TextRange` sub-entity — a style override over a run of the parent `<text>`'s glyphs, addressed by character index into the text as written (`end` unset is `null`, to the end), stacking in document order with later ones winning where they overlap, exactly what the caption presets build by hand. Its recipe is `TextRange` + a sparse `TextStyle` (an unset field inherits the text's, which is how `utils/text.ts`'s per-range accessors already read it), plus `Color` when `color` is set, and it takes paint, `<stroke>`, `<shadow>` and `<keyframeTrack>` (a `color` track) children, whose caches `rebuildCaches` already builds per parent. `setProperty('start'|'end')` branches on `TextRange` first, since on every other element those names are timing props. One runtime change: `renderTokens` resolved the intrinsic glyph fill once per text (`entity.has(Color)`), so a range could recolor glyphs only through a solid paint child; it now resolves it per word through `getIntrinsicColor`, the last range in the word's ranges carrying `Color` winning over the text's (via `Computed.color`, so a keyframed range color animates), which is what makes `<textRange color>` a plain prop. Layout props (`textAlign`, `textBaseline`, `leading`) stay per text: the shaper reads them from the node only. Not exposed: the motion system's `chars` keyframe path (a `Keyframe.value` is a number, so nothing meaningful can be authored on it) and `Opacity` on a range (nothing reads it; a range's translucency is its paints').
+## apps/web integration
- **`mask` is a `<rect>` prop** (`RectProps.mask?: boolean` in `@diffusionstudio/jsx`; no new tag). In the engine a mask is nothing but a geometry with the `IsMask` tag, `ChildOf` the node it clips: `rebuildCaches` files it under `Cache.masks` instead of `Cache.children`, `renderNode` skips drawing it and uses `drawRectPath` of it as a `clip()` (several intersect), hit-testing and the timeline index treat it apart, and the transform, visibility and motion systems see an ordinary geometry — so a keyframed mask `width` is a wipe with nothing new. The prop mirrors that one to one: `setProperty('mask')` adds/removes `IsMask` on the rect's entity, and every other prop is the rect's (`fill`/`opacity`/`blendMode`/paint children are accepted by the type but do nothing on a mask, as they do nothing in the engine). A tag (`<mask>`) was tried first and dropped: the recipe was `<rect>` minus a default paint, and a tag would have made "make this rect a mask" a retag instead of a prop flip. Host behaviour: a `<rect mask>` with no `width`/`height` is 500×500 instead of the rect's 100×100 (`setProperty('mask')` resizes only the dimensions not yet authored, so prop order does not matter); sizing to the parent, which the old editor's "Add mask" did, was tried and dropped for a plain default. Runtime changes: `recomputeEntityTimeRange` gives a mask with no `End`/`SourceOut` of its own its parent's `Computed.end` instead of the sourceless 16 s default (a mask silently letting go at 16 s on a 30 s clip is a surprise nobody authored; `Ignorable` gained `IsMask` so a removal can recompute as if the tag were gone), `bubbleTimeRangeUp` re-propagates into a fitted container's masks after recomputing it (they are not in `Cache.children`, so they would otherwise keep the stale end), the transform system's group-bounds union skips `IsMask` children (a mask clips a group's box, it does not extend it), and `world/observers.ts` watches `IsMask` add/remove on an attached geometry — `refileMask` (new in `actions/cache.ts`) moves it between the parent's `children` and `masks` by hand, since koota fires onRemove with the tag still on and the queries cannot be trusted, then the time range is re-derived and bubbled — so `mask` toggles live like any other prop. Not exposed: `hidden` on a mask does not switch it off (`renderNode` skips masks by role before it looks at `Hidden`, and `computed.visibility` is timing only); text-shaped masks are not a runtime feature either (`drawRectPath` is the only mask path).
+Depends on `@diffusionstudio/runtime` + `@diffusionstudio/koota-solid`, migrating slice by slice. The bitecs engine in `apps/web/src/components/engine/` is still fully intact and untouched; both providers are mounted side by side in `pages/home.tsx`, keyed on `projectId`.
- **Inspector shell is on the koota world.** `useSelection()` (`apps/web/src/engine/hooks/use-selection.ts`) reads `Selected` via `useQuery` and splits it into `nodes` (Geometry/Group/AdjustmentLayer), `keyframes`, and `first`; selection is written through `useEditor().select/...` only. `sidebar-right/inspector/inspector.tsx` classifies the target with the runtime predicates (`isScene`, `isMask`, ..., `ToolType.SCENE` from `useTool()`) and mounts only the panels already migrated (`InspectorHeader`, `BackgroundSettings`); the rest of the panels are listed in a comment in their previous order and return one at a time, each following `background.tsx`'s pattern (`useTrait` to read, `editor.editProperty` to write).
+Done:
- **AssetInfoPanel is on the koota world.** Asset selection became an app-side world trait, `AssetSelection` (`engine/traits.ts`, `{ id }`, attached by `Engine`), read and written through `useAssetSelection()` (`engine/hooks/use-asset-selection.ts`: `id`, `asset` resolved against the library's reactive list so a removed asset drops out by itself, `select`). The assets panel uses it instead of its local signal, the inspector classifies `asset` from it (after keyframes, before nodes, as before), and a click on empty canvas clears it in `input/interactions.ts` next to `clearSelection`. The panel reads `@diffusionstudio/assets` records (`assetName`, `stat.size/mtime` for size and "Modified", `generation.id` for the supabase prompt/model rows, plus a "Source" row since files are linked, not copied) and previews via `getAssetFile` + the library's `cache.peaks` (shared with the asset bar); SEQUENCE previews by its first frame. "Insert at playhead"/"Replace source" are `insertAssetAtPlayhead`/`replaceAssetSource` in `engine/asset-actions.ts`, shared with the asset item's context menu; a relink mints a new id, so the panel re-selects the returned asset.
+| Slice | Where |
+|---|---|
+| Engine shell (canvas mount/resize/DPR, AudioContext, tick + `frame` signal) | `engine/create-engine.ts`, `engine/context.tsx` |
+| Projects on disk (desktop): folder with an `index.tsx` exporting `<stage>` | `apps/web/src/projects/`, `apps/desktop/src/projects.ts` |
+| Editing commands, reported as source-vocabulary edits for write-back | `engine/editor.ts` (`DocumentEditor`, `useEditor()`) |
+| Keyframes as edits (`writeKeyframe`/`toggleKeyframe`/`syncKeyframe`/`removeKeyframeTrack`) | `engine/keyframes.tsx`, `components/ui/keyframe.tsx` |
+| Hooks | `engine/hooks/` (`useSelection`, `useAssetSelection`, `useDerived`, `useTool`, `useEditor`) plus koota-solid's `useTrait`/`useHas`/`useQuery`/`useWorld` |
+| Draw tools + toolbar (armed tool is the `Tool` world trait) | `components/canvas/draw-overlay.tsx` |
+| Input, HUD, camera, alignment | `engine/input/`, `engine/hud/`, `engine/align.ts` |
+| Project config (per-scene export settings in package.json) | `engine/project-config.ts` |
+| Panels: header, background, scene template, asset info, time, appearance, alignment, export, layout | `components/sidebar-right/inspector/` |
- **TimeSettings is on the koota world**, and with it the first pieces every timing surface will share. Reads: the resolved bounds are `Computed.start/end`, which the systems write without events, so `useTrait` cannot follow them; `useDerived(read, equals?)` (`engine/hooks/use-derived.ts`) samples `read` once per engine tick against `Engine.frame`, a plain Solid signal the loop bumps after `runSystems` (one signal for every caller, no koota subscription per hook), and notifies only when the sample changes. Use it for any Computed read in UI (Transform/Layout will). Writes stay `editor.editProperty`; `DocumentEditor` keeps to primitives, and what a property means is the panel's business. `time.tsx` has the helpers: `editTime(world, editor, entity, 'start'|'end'|'sourceIn'|'sourceOut', frames | null)` converts project frames to the seconds the file spells (`framesToSeconds`; the desktop writer rounds to 2 decimals, exact up to 100 fps), `null` unsets (`false` is the PropValue the writer removes an attribute for, and the document drops the trait for it), and a `start`/`sourceIn` of 0 is unset too since absence reads as 0; `trimIn/trimOut(world, editor, entity, sceneFrame)` are the runtime's `trimEntityIn/Out` as edits (pin End when absent, then Start + SourceIn computed before either is written, since the Start write moves the origin; SourceOut follows only when authored). When the timeline needs the same, lift them into a shared module then. The panel: Length and In/Out go through `trimOut`/`trimIn`; Speed is `playbackRate` (1 unsets; the start stays put on its own because the rate only scales the source window around it, so the bitecs Delay fixup is gone); "Trim content" on a scene/group is `hasEnd` (a container authoring an End spans it instead of fitting its children), toggled on via `trimIn(entity, Computed.start)`, which writes Start = SourceIn = the first child's offset so the children stay where they are, and off via `editTime('end', null)`; the sequence Frame Rate row is `setSequenceFrameRate` in `engine/asset-actions.ts` (`library.update` in place, then `reactToAssetChange` for every AssetId holder; no End clamp, caps resolve at read time). Runtime fix that came with it: `pinEndToCurrentBounds` pins `Computed.end - origin` instead of `Start + duration`, which was wrong for a container fitting children that start after 0. Not carried over: the bitecs `resolveSequentialOverlaps` call after each timing edit (the runtime's version writes traits without reporting; it needs an editor-side port before the app can call it), and `history.transaction` labels (no undo layer).
+Hosted JSX surface is `COMPOSITION_TAGS` (`packages/jsx/src/source.ts`): the structural tags, the media tags, `<captions>`, the paint family, `<stroke>`, `<shadow>`, `<effect>`, `<animation>`, `<keyframeTrack>`/`<keyframe>`, `<html>`/`<surface>`. `mask` is a `<rect>` prop, not a tag.
- **AppearanceSettings is on the koota world, and with it keyframes as edits.** Opacity, blending, visibility and corner radii are the props `opacity`, `blendMode` (`sourceOver` is unset, spelled `false` like every default), `hidden`, `cornerRadius` and four new `<rect>` props `cornerRadiusTopLeft`/`TopRight`/`BottomRight`/`BottomLeft` (`@diffusionstudio/jsx`, also in `AnimatableProperty`; `TRACK_PROPERTIES` maps them to the `mixedVertexRadius.*` paths). The document derives `MixedCornerRadius` from the five radius props as authored (`syncCornerRadii`, recomputed whole on each so Solid's prop order does not matter): present while any corner has a radius of its own, a corner without one taking `cornerRadius`, gone when none has, which is the render system's "mixed wins while present" with a fallback. The panel's uniform/separate switch drops the other mode's props and tracks. Hovering a blend mode previews through the trait alone (`entity.set(BlendMode)`, restored on close), only a pick is an edit. Reads are Computed via `useDerived` (the shown, possibly animated, value), `useTrait(BlendMode)`, `useHas(Hidden)`. Two changes underneath: (1) `toNumber` in the document treats a boolean as no value instead of 0/1, so `editProperty(entity, 'opacity', false)` unsets the prop (the writer already spelled `false` as the attribute's absence; before, it would have written opacity 0 to the canvas). (2) **Trait removal now resets Computed**: the mirror observers in `world/observers.ts` run `resetAnimatedValues(world, entity, trait)` onRemove (all but `Size`), and `resetAnimatedValues` reads a trait's store only while the entity has it (else the default), with an `ignore` param because koota fires onRemove before clearing the trait and leaves store slots as they were. Before this an unset `opacity` held its last value on the canvas until remount, which no reactive prop or editor unset could live with; "does not reset, same as bitecs" held only while traits were never removed.
+Conventions worth repeating when migrating the next panel:
- **Keyframes as edits** live in `apps/web/src/engine/keyframes.tsx`, the runtime's `toggleKeyframeTrack`/`syncKeyframeTrack`/`removeKeyframeTrack` in the JSX's vocabulary: properties are `AnimatableProperty` names (what `<keyframeTrack property>` takes; the reconciler exports `trackPropertyPath(holder, name)` to resolve them, and `BLEND_MODES`), and every change goes through the editor. `writeKeyframe(world, editor, target, property, value?)` edits the `value` of the keyframe at the node's current local frame or inserts `<Keyframe time value />` (time as seconds, like the timing props) into the track, or the whole `<KeyframeTrack property><Keyframe/></KeyframeTrack>` when there is none; `value` defaults to the shown (Computed) value, colors as hex. `toggleKeyframe` adds or removes the keyframe at the current frame, removing the track with its last keyframe (`editor.remove`). `syncKeyframe(world, editor, target, property, value)` is what an editing surface calls after writing a prop that has a track, since the motion system would overwrite the edit on the next tick (the observers slice dropped auto-sync on purpose); the appearance panel does so for opacity and the radii. `removeKeyframeTrack` removes the track element. `components/ui/keyframe.tsx` is the koota `Keyframe` diamond (`target: Entity`, `property: AnimatableProperty`; track/active state sampled per tick with `useDerived`, shown only for an element with a `Source`); the bitecs one moved to `components/ui/keyframe-bitecs.tsx` and the unmigrated panels import it from there until they move. Not built: the timeline's keyframe layer and InterpolationSettings (keyframe `easing` edits) are still on the bitecs world.
+- Reads of `Computed` (anything the systems write without events) go through `useDerived`, which samples once per engine tick; `useTrait`/`useHas` cannot follow them.
+- Writes go through `editor.editProperty` in JSX vocabulary. `false` is the value the writer removes an attribute for, so a default is unset rather than written.
+- `syncKeyframe` after a prop write keeps an existing track in step, since the motion system would otherwise overwrite the edit next tick. **Exception:** `width`/`height` sync *before* the write, because the document's handler is `resizeEntity`, which syncs the track itself and would mint an unsourced keyframe first. The canvas resize in `engine/input/interactions.ts` has the same gap, unfixed.
+- State with no JSX spelling (`KeepAspectRatio`, `ClipsContent`, `Skew`) is written to the trait alone and does not survive a recompile. Giving any of them a prop is a separate decision; a lock snapshot would then have to come from the authored size, not from whatever `Size` holds at mount.
+- Panels still on bitecs import the diamond from `components/ui/keyframe-bitecs.tsx` until they move.
- **LayoutPanel is on the koota world.** Size reads are `Computed.width/height` via `useDerived`; writes are the `width`/`height` props through `editor.editProperty`, each preceded by `syncKeyframe` rather than followed by it: the document's `width`/`height` handler is `resizeEntity`, which calls the runtime's `syncKeyframeTrack` itself and would otherwise mint an unsourced keyframe on an existing track before the editor gets to write one (the later `writeKeyframe` then finds that entity in `Cache.keyframes` and edits a value the file never hears of). The canvas resize in `input/interactions.ts` writes `width`/`height` without any sync and has the same gap; fix it the same way when it grows keyframe support. The aspect lock (`KeepAspectRatio`) and "Clip content" (`ClipsContent`) have no JSX spelling, so the panel writes the traits alone and they last until the project is rendered again, like `Skew` on the canvas; because the lock is trait-only, the panel couples the axes itself and writes both props, so the file says what the canvas shows and the runtime's own enforcement underneath is a no-op. A size chosen outright (a scene preset, the orientation swap) re-pins the lock to it instead of letting the old ratio squash it, which the bitecs panel did. Not carried over: nothing else; if the lock or clipping should survive a recompile, they want props on `<scene>`/`<rect>` (order-sensitive at mount if the snapshot is taken on set, so snapshot from the authored `width`/`height` then), which is a separate decision.
+Still on bitecs: transform, caption-settings, text, fills, strokes, shadows, effects, animations, transition, masks, audio, interpolation panels; the timeline's keyframe layer; the whole timeline UI.
- **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.
+**Left stale on purpose** (deferred to a docs/examples pass): the eight `examples/*.tsx` still open with `<rect scene="...">` and no `<stage>`, so `tsc -p examples --noEmit` fails on them, and `reference/jsx/*` still describes the pre-`<stage>` model and `key` as the `syncTo` target. `reference/jsx` is stale as a whole; patching rows piecemeal would hide that.
-## Remaining work (suggested order)
+## Remaining work
-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`).
+1. **apps/web**: remaining panels and the timeline UI, app-side world traits (store, timelineIndex signal), history via koota events, re-adding the editing-surface `syncKeyframeTrack` calls the observers slice dropped. `utils/captions.ts` stays app-side, rewired to `@diffusionstudio/encoder`. Once real content loads into the koota world, delete the hidden bitecs canvas and `engine/components`, `engine/api` progressively.
+2. **CLI**: point node capture at the runtime + encoder packages, importing `MAX_FRAMES_PER_SHEET` from the encoder instead of redefining it in `cli-channels.ts`.
-## Layout reminders
+## Package reminders
-- Package exports: root `.` plus `./traits`, `./systems`, `./media`, `./capture` (see package.json). Everything currently also re-exported from root `src/index.ts`.
+- Exports: root `.` plus `./traits`, `./systems`, `./media`; everything is also re-exported from `src/index.ts`. The `./capture` entry in package.json is dangling (`src/capture/` no longer exists) and wants deleting.
- 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.
+- Deps: koota (patched), mediabunny, animejs, colord, `@diffusionstudio/assets` (the asset model moved out into its own package; sqids went with the id allocator). Dev: `@webgpu/types`.