Skip to content

The VS Code of video editing, built for agents.

TypeScript

Add support for `<group>` and `<sequence>` entities in RuntimeDocument

konstantin-paulus03d8e692445e
diff --git a/packages/reconciler/src/document.ts b/packages/reconciler/src/document.ts
index 17184963..91303df7 100644
--- a/packages/reconciler/src/document.ts
+++ b/packages/reconciler/src/document.ts
@@ -32,6 +32,8 @@ import {
resizeEntity,
secondsToFrames,
getEntityChildren,
+ Group,
+ Sequential,
Stage,
Root,
Rotation,
@@ -226,6 +228,21 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
resizeEntity(this.world, entity, { width: 1920, height: 1080 });
break;
}
+ case 'group': {
+ // No Size: a group's box is the union of its children's.
+ entity = createEntity(this.world);
+ entity.add(Group);
+ entity.add(Position);
+ entity.set(Position, { x: 0, y: 0 });
+ break;
+ }
+ case 'sequence': {
+ // Sequential's observer adds Group and keeps spatial traits off:
+ // a sequence sits at its parent's origin and mirrors its frame.
+ entity = createEntity(this.world);
+ entity.add(Sequential);
+ break;
+ }
case 'rect': {
entity = createEntity(this.world);
entity.add(Geometry);
@@ -247,7 +264,9 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
break;
}
default:
- throw new Error(`<${tag}> is not supported yet (only <stage>, <scene>, <rect> and <text>).`);
+ throw new Error(
+ `<${tag}> is not supported yet (only <stage>, <scene>, <group>, <sequence>, <rect> and <text>).`,
+ );
}
if (entity !== this.stage.entity) {
@@ -336,17 +355,20 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
}
case 'x':
case 'y': {
+ if (entity.has(Sequential)) return;
entity.add(Position);
entity.set(Position, { [name]: toNumber(value) ?? 0 });
return;
}
case 'offsetX':
case 'offsetY': {
+ if (entity.has(Sequential)) return;
entity.add(Offset);
entity.set(Offset, { [name === 'offsetX' ? 'x' : 'y']: toNumber(value) ?? 0 });
return;
}
case 'rotation': {
+ if (entity.has(Sequential)) return;
entity.add(Rotation);
entity.set(Rotation, { value: toNumber(value) ?? 0 });
return;
diff --git a/packages/runtime/MIGRATION.md b/packages/runtime/MIGRATION.md
index fc19afab..6fbd48ca 100644
--- a/packages/runtime/MIGRATION.md
+++ b/packages/runtime/MIGRATION.md
@@ -137,6 +137,8 @@ apps/web now depends on `@diffusionstudio/runtime` and `@diffusionstudio/koota-s
**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).
+
**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.