The VS Code of video editing, built for agents.
TypeScript
Refactor scene activation management in the editor
konstantin-paulus8e4138a31daf
diff --git a/apps/web/src/components/canvas/draw-overlay.tsx b/apps/web/src/components/canvas/draw-overlay.tsxindex d3e74f0c..bee794f1 100644--- a/apps/web/src/components/canvas/draw-overlay.tsx+++ b/apps/web/src/components/canvas/draw-overlay.tsx@@ -13,7 +13,6 @@ import {screenToWorld,Source,store,- switchActiveScene,Tool,ToolType,worldToLocal,@@ -226,7 +225,7 @@ export function DrawOverlay() {if (entity) {if (tool === ToolType.SCENE) {- switchActiveScene(world, entity);+ editor.activate(entity);}editor.select(entity);diff --git a/apps/web/src/components/canvas/scene-init-overlay.tsx b/apps/web/src/components/canvas/scene-init-overlay.tsxindex 4ab11000..9cef2e83 100644--- a/apps/web/src/components/canvas/scene-init-overlay.tsx+++ b/apps/web/src/components/canvas/scene-init-overlay.tsx@@ -5,7 +5,7 @@import { createMemo, createSignal, For, Show } from "solid-js";import { useQuery, useTrait, useWorld } from "@diffusionstudio/koota-solid";import { Scene as SceneElement } from "@diffusionstudio/reconciler";-import { ChildOf, getCameraMatrix, getNextName, Root, setCamera, Source, switchActiveScene } from "@diffusionstudio/runtime";+import { ChildOf, getCameraMatrix, getNextName, Root, setCamera, Source } from "@diffusionstudio/runtime";import { Icon } from "@/components/ui/icon";import {DropdownMenu,@@ -112,7 +112,7 @@ export function SceneInitOverlay() {));if (!scene) return;- switchActiveScene(world, scene);+ editor.activate(scene);editor.select(scene);};diff --git a/apps/web/src/engine/editor.ts b/apps/web/src/engine/editor.tsindex a1831d7f..8639377d 100644--- a/apps/web/src/engine/editor.ts+++ b/apps/web/src/engine/editor.ts@@ -10,7 +10,7 @@* where the commands live.*/-import { Chars, getEntityChildren, getParentEntity, isText, Selected, Source, Stage } from '@diffusionstudio/runtime';+import { Chars, getActiveEntity, getEntityChildren, getParentEntity, isText, Selected, setActive, Source, Stage } from '@diffusionstudio/runtime';import { SOURCE_ATTR } from '@diffusionstudio/jsx';import { createRoot } from 'solid-js';@@ -162,6 +162,19 @@ export class DocumentEditor {this.select([]);}+ /**+ * Points the timeline at `entity` (or at nothing). Same route as+ * `select`: `setActive` enforces the runtime's rules and writes the trait,+ * and the file learns `active` moved, `false` for the one it left.+ */+ public activate(entity: Entity | null): void {+ const current = getActiveEntity(this.world);+ if (current === entity) return;+ setActive(this.world, entity);+ if (current?.isAlive()) this.reportEdit(current, 'active', false);+ if (entity) this.reportEdit(entity, 'active', true);+ }+private setSelected(entity: Entity, selected: boolean): void {if (!entity.isAlive() || entity.has(Stage) || entity.has(Selected) === selected) return;if (selected) entity.add(Selected);diff --git a/apps/web/src/engine/hooks/use-active-scene.ts b/apps/web/src/engine/hooks/use-active-scene.tsindex a405676d..dd497f1f 100644--- a/apps/web/src/engine/hooks/use-active-scene.ts+++ b/apps/web/src/engine/hooks/use-active-scene.ts@@ -2,14 +2,14 @@* License, v. 2.0. If a copy of the MPL was not distributed with this* file, You can obtain one at http://mozilla.org/MPL/2.0/. */-import { ActiveScene } from '@diffusionstudio/runtime';-import { useTrait, useWorld } from '@diffusionstudio/koota-solid';+import { Active } from '@diffusionstudio/runtime';+import { useQuery } from '@diffusionstudio/koota-solid';import type { Entity } from 'koota';import type { Accessor } from 'solid-js';-/** Reactive read of the world's ActiveScene trait. Write via world.set(ActiveScene, ...). */-export function useActiveScene(): Accessor<Entity | null | undefined> {- const activeScene = useTrait(useWorld(), ActiveScene);- return () => activeScene()?.entity;+/** Reactive read of the entity carrying Active. Write via `useEditor().activate(...)`. */+export function useActiveScene(): Accessor<Entity | null> {+ const active = useQuery(Active);+ return () => active()[0] ?? null;}diff --git a/apps/web/src/pages/editor.tsx b/apps/web/src/pages/editor.tsxindex 8e4579d4..680ae01c 100644--- a/apps/web/src/pages/editor.tsx+++ b/apps/web/src/pages/editor.tsx@@ -70,7 +70,8 @@ export function EditorPage() {// The rendered scene knows which element every entity came from, so// from here on an edit in the editor can find its way back.writer = createEditWriter(dir, world);- unlisten = getDocumentEditor(world).onEdit((edit) => writer?.push(edit));+ const editor = getDocumentEditor(world);+ unlisten = editor.onEdit((edit) => writer?.push(edit));} catch (error) {toast.error('Project failed to render', { description: (error as Error).message });}diff --git a/packages/encoder/src/encoder.ts b/packages/encoder/src/encoder.tsindex dea78314..4936af43 100644--- a/packages/encoder/src/encoder.ts+++ b/packages/encoder/src/encoder.ts@@ -10,7 +10,7 @@ import {} from 'mediabunny';import { Or } from 'koota';import {- createRuntimeWorld, switchActiveScene, serializeEntity, cloneFromRecords,+ createRuntimeWorld, setActive, serializeEntity, cloneFromRecords,getEntityTree, propagateTimeRangeDown, framesToSeconds,assert, store, disposeDecoders,playbackSystem, motionSystem, transformSystem, renderSystem,@@ -112,7 +112,7 @@ export async function createEncoder(sourceWorld: World, config: EncoderConfig) {recomputeAllTimeRanges(world);normalizeSceneTransform(world, scene.id());- switchActiveScene(world, scene);+ setActive(world, scene);const computed = store(world, Computed);const playback = store(world, Playback);diff --git a/packages/jsx/src/types.ts b/packages/jsx/src/types.tsindex d77582ed..288e9bd1 100644--- a/packages/jsx/src/types.ts+++ b/packages/jsx/src/types.ts@@ -127,6 +127,14 @@ export type PatchProps = {* selected; the editor writes the bare attribute and removes it again.*/selected?: boolean;+ /**+ * Whether this element is the one the playhead, timeline, and capture+ * operate on. Editor state carried by the source like `selected`, with two+ * rules the runtime holds: at most one element is active, and only a root+ * (a direct child of `<stage>`) can be; a nested `active` is dropped. When+ * a file names more than one, the last one rendered wins.+ */+ active?: boolean;/** Position relative to the parent, px. Defaults to 0. Animatable. */x?: Animatable<number>;y?: Animatable<number>;@@ -280,14 +288,15 @@ export type StageProps = {* `width`×`height` and owns the timeline they are placed on, so it takes no* timing of its own — nothing outside a scene has a clock to place it against.*- * `x`/`y` are where the frame sits on the infinite canvas, and `selected`- * whether the editor has it selected. Those are editor concerns rather than+ * `x`/`y` are where the frame sits on the infinite canvas, `selected` whether+ * the editor has it selected, and `active` whether the timeline is pointed at+ * it (scenes only, for now). Those are editor concerns rather than* part of the composition, but they live here for the same reason `<stage>`'s* `camera` does: the source is the document, so a scene dragged or clicked on* the canvas has nowhere else to be written back to.*/export type SceneProps = Required<Pick<PatchProps, "width" | "height">> &- Pick<PatchProps, "name" | "selected" | "x" | "y" | "fill"> & {+ Pick<PatchProps, "name" | "selected" | "active" | "x" | "y" | "fill"> & {children?: SolidJSX.Element;};diff --git a/packages/reconciler/src/document.ts b/packages/reconciler/src/document.tsindex e4e93aa9..687f8a4b 100644--- a/packages/reconciler/src/document.ts+++ b/packages/reconciler/src/document.ts@@ -4,7 +4,7 @@import {- ActiveScene,+ Active,appendChild,Background,Chars,@@ -39,7 +39,6 @@ import {SourceOut,setCameraMatrix,Start,- switchActiveScene,TextAlign,TextBaseline,TextStyle,@@ -223,6 +222,15 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {}return;}+ case 'active': {+ // Uniqueness and root-only are the runtime's observers' business.+ if (value === true && entity !== this.stage.entity) {+ entity.add(Active);+ } else {+ entity.remove(Active);+ }+ return;+ }case 'x':case 'y': {entity.add(Position);@@ -384,10 +392,6 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {node.entity.remove(Source);return;}- // The playhead cannot be left aimed at an entity that is going away.- if (this.world.get(ActiveScene)?.entity === node.entity) {- switchActiveScene(this.world, null);- }// Destroy cascades through the subtree; the text nodes held for it go too.for (const entity of getEntityTree(this.world, node.entity)) {const texts = this.texts.get(entity);diff --git a/packages/reconciler/src/patch.ts b/packages/reconciler/src/patch.tsindex ed526c8f..3a97656d 100644--- a/packages/reconciler/src/patch.ts+++ b/packages/reconciler/src/patch.ts@@ -13,6 +13,7 @@ import type { PatchProps } from '@diffusionstudio/jsx';export const PATCH_PROP_KEYS = Object.keys({name: true,selected: true,+ active: true,x: true,y: true,offsetX: true,diff --git a/packages/runtime/MIGRATION.md b/packages/runtime/MIGRATION.mdindex 9e8f6060..c46a1726 100644--- a/packages/runtime/MIGRATION.md+++ b/packages/runtime/MIGRATION.md@@ -15,7 +15,7 @@ Working doc for migrating the editor engine from bitecs (in `apps/web/src/compon|---|---|---|| 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, ActiveScene, Camera, Background, Time (was timestamp), FrameRate, RenderSurface (canvas+ctx+resolution), AudioEngine (injected, no ctor arg), Fonts, Mounts, FramePromises (was world.promises), Stage |+| 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 |@@ -98,7 +98,7 @@ One trait per value rather than one trait with four fields, because a clip rarel- 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.-- `switchActiveScene` only sets the ActiveScene world trait; timeline buffer clearing and index rebuild stay app-side. `frameSelection` calls it once (bitecs called it redundantly inside and outside the transaction).+- 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.@@ -137,6 +137,8 @@ apps/web now depends on `@diffusionstudio/runtime` and `@diffusionstudio/koota-s**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)diff --git a/packages/runtime/src/actions/assets.ts b/packages/runtime/src/actions/assets.tsindex 2967bdc0..e738bad8 100644--- a/packages/runtime/src/actions/assets.ts+++ b/packages/runtime/src/actions/assets.ts@@ -11,13 +11,14 @@ import Sqids from 'sqids';import { GeometryType, PaintType } from '../constants';import {Geometry, Paint, Audio, Caption, Hidden, Name, AssetId, Start, SourceIn,- SourceOut, KeepAspectRatio, Computed, Assets, AssetIds, ActiveScene,+ SourceOut, KeepAspectRatio, Computed, Assets, AssetIds,} from '../traits';import { store } from '../world/store';import { secondsToFrames } from '../utils/time';import { createEntity } from './entities';import { appendChild } from './hierarchy';import { resizeEntity } from './resize';+import { getActiveEntity } from './frame';import type { Entity, World } from 'koota';import type { Asset, Transcript } from '../assets/types';@@ -121,7 +122,7 @@ export async function insertAssetInTimeline(asset: Asset,mode: 'playhead' | 'start',): Promise<Entity | null> {- const scene = world.get(ActiveScene)?.entity ?? null;+ const scene = getActiveEntity(world);if (scene === null) return null;const start = mode === 'playhead' ? store(world, Computed).localTime[scene.id()] ?? 0 : 0;diff --git a/packages/runtime/src/actions/frame.ts b/packages/runtime/src/actions/frame.tsindex e57bc372..a1b67e83 100644--- a/packages/runtime/src/actions/frame.ts+++ b/packages/runtime/src/actions/frame.ts@@ -3,8 +3,8 @@* file, You can obtain one at http://mozilla.org/MPL/2.0/. */// Frame and scene actions (was api/frame.ts, plus switchActiveScene from-// api/base.ts). The app reacts to ActiveScene changes (clearing timeline-// buffers, rebuilding its index) through its own world-trait observer.+// api/base.ts). The app reacts to Active changes (clearing timeline buffers,+// rebuilding its index) through its own trait observer.import { Or } from 'koota';@@ -12,7 +12,7 @@ import { store } from '../world/store';import { GeometryType, PaintType } from '../constants';import {Geometry, Group, Scene, ClipsContent, Playback, Paint, Color, Selected,- Position, Name, LocalTransform, Computed, ActiveScene,+ Position, Name, LocalTransform, Computed, Active,} from '../traits';import { isScene } from '../queries/predicates';import { getNextName, getParentNode } from '../queries/hierarchy';@@ -25,15 +25,25 @@ import { resizeEntity } from './resize';import type { Entity, World } from 'koota';-/** Retarget the playhead/timeline scene (not undoable state). */-export function switchActiveScene(world: World, entity: Entity | null): void {- if (entity !== null) {- assert(isScene(entity), 'Entity is not a scene');- }+/** The entity carrying Active, or null. */+export function getActiveEntity(world: World): Entity | null {+ return world.queryFirst(Active) ?? null;+}- if (world.get(ActiveScene)?.entity === entity) return;+/**+ * Retarget the playhead/timeline entity (not undoable state). Uniqueness and+ * root-only are enforced by the Active observers; only the scene restriction+ * lives here, since it is the part that is going away.+ */+export function setActive(world: World, entity: Entity | null): void {+ if (entity === null) {+ getActiveEntity(world)?.remove(Active);+ return;+ }- world.set(ActiveScene, { entity });+ assert(isScene(entity), 'Entity is not a scene');+ assert(getParentNode(entity) === null, 'Only root entities can be active');+ entity.add(Active);}/**@@ -116,7 +126,7 @@ export function frameSelection(world: World): Entity | null {// Make the freshly created frame the active scene (mirrors the scene tool),// so the timeline retargets to it.- switchActiveScene(world, scene);+ setActive(world, scene);return scene;}diff --git a/packages/runtime/src/traits/interaction.ts b/packages/runtime/src/traits/interaction.tsindex 028cdcfb..e87bb952 100644--- a/packages/runtime/src/traits/interaction.ts+++ b/packages/runtime/src/traits/interaction.ts@@ -11,6 +11,8 @@ export const Tool = trait({ value: ToolType.MOVE });export const Selected = trait();+export const Active = trait();+export const Interactive = trait();export const Hovering = trait();diff --git a/packages/runtime/src/traits/world.ts b/packages/runtime/src/traits/world.tsindex f07f48e5..1bfedfd5 100644--- a/packages/runtime/src/traits/world.ts+++ b/packages/runtime/src/traits/world.ts@@ -41,9 +41,6 @@ export type RuntimeMode = 'realtime' | 'offline-video' | 'offline-audio';export const Mode = trait({ value: 'realtime' as RuntimeMode });-// Scene the playhead, timeline, and capture operate on (was selection.scene).-export const ActiveScene = trait({ entity: null as Entity | null });-// Frame clock (was timestamp).export const Time = trait({ now: 0, delta: 0 });diff --git a/packages/runtime/src/world/create-world.ts b/packages/runtime/src/world/create-world.tsindex 2286d4ff..59c49ff5 100644--- a/packages/runtime/src/world/create-world.ts+++ b/packages/runtime/src/world/create-world.ts@@ -10,7 +10,6 @@ import {Root,Project,Mode,- ActiveScene,Camera,Background,Time,@@ -37,7 +36,6 @@ export function createRuntimeWorld(projectId: string) {const world = createWorld(Project({ id: projectId }),Mode,- ActiveScene,Time,FrameRate,RenderSurface,diff --git a/packages/runtime/src/world/observers.ts b/packages/runtime/src/world/observers.tsindex 1e11f84d..dc24132a 100644--- a/packages/runtime/src/world/observers.ts+++ b/packages/runtime/src/world/observers.ts@@ -22,7 +22,7 @@ import {Start, End, SourceIn, SourceOut, PlaybackRate, Keyframe, ItemIndex,Position, Offset, Rotation, Scale, UniformScale, Skew, Anchor, Flip,Appearance, Color, Blur, Volume, Effect, CornerRadius, MixedCornerRadius,- ColorStop, StrokeStyle, Size, Computed,+ ColorStop, StrokeStyle, Size, Computed, Active, Stage,ImageDecoderHandle, VideoDecoderHandle, SequenceDecoderHandle,AudioDecoderHandle, CaptionDecoderHandle,HtmlHostHandle, SurfaceHostHandle, ShaderHostHandle, AudioBusHandle,@@ -105,6 +105,21 @@ export function observeWorld(world: World): () => void {entity.remove(Position, Offset, Rotation, Scale, Skew, Anchor, Flip);}));+ // One active entity per world, and only a root.+ subs.push(world.onAdd(Active, (entity) => {+ for (const other of [...world.query(Active)]) {+ if (other !== entity) {+ other.remove(Active);+ }+ }+ }));++ subs.push(world.onAdd(ChildOf('*'), (child, parent) => {+ if (child.has(Active) && !parent.has(Stage)) {+ child.remove(Active);+ }+ }));+// ── Time ranges ───────────────────────────────────────────const recomputeAndBubble = (entity: Entity) => {