Skip to content

The VS Code of video editing, built for agents.

TypeScript

Refactor document structure to stage model

konstantin-paulusd4d3475cee76
diff --git a/packages/encoder/src/encoder.ts b/packages/encoder/src/encoder.ts
index f7b70a80..dea78314 100644
--- a/packages/encoder/src/encoder.ts
+++ b/packages/encoder/src/encoder.ts
@@ -506,8 +506,8 @@ export async function resolverSystem(world: World) {
* walk; koota has no hierarchy-ordered queries).
*/
export function recomputeAllTimeRanges(world: World): void {
- const document = world.get(Root)!;
- for (const node of world.query(Or(Geometry, Group), ChildOf(document))) {
+ const stage = world.get(Root)!;
+ for (const node of world.query(Or(Geometry, Group), ChildOf(stage))) {
propagateTimeRangeDown(world, node);
}
}
diff --git a/packages/reconciler/src/document.ts b/packages/reconciler/src/document.ts
index b0bac6bf..522b581b 100644
--- a/packages/reconciler/src/document.ts
+++ b/packages/reconciler/src/document.ts
@@ -26,7 +26,7 @@ import {
resizeEntity,
secondsToFrames,
getEntityChildren,
- DocumentRoot,
+ Stage,
Root,
Scene,
Source,
@@ -85,7 +85,7 @@ export interface EntityEdit {
}
export class RuntimeDocument implements ProjectDocument<SceneNode> {
- /** The mount root. Both it and the <stage> element stand for the document root entity. */
+ /** The mount root. Both it and the <stage> element stand for the Stage entity. */
public readonly stage: SceneNode;
private readonly world: World;
private sink?: (edit: EntityEdit) => void;
@@ -260,13 +260,13 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {
if (parent.entity === node.entity) return;
// Scenes own a timeline, so one inside another has no coherent reading.
- if (node.entity.has(Scene) && !parent.entity.has(DocumentRoot)) {
+ if (node.entity.has(Scene) && !parent.entity.has(Stage)) {
throw new Error('<scene> is only allowed as a direct child of <stage>.');
}
if (getParentEntity(node.entity) !== parent.entity) {
// appendChild only takes top-level entities, so a move between two
- // parents goes back through the document on the way.
+ // parents goes back through the stage on the way.
const current = getParentNode(node.entity);
if (current !== null) {
@@ -287,7 +287,7 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {
}
public removeNode(_parent: SceneNode, node: SceneNode): void {
- if (node.entity.has(DocumentRoot)) {
+ if (node.entity.has(Stage)) {
for (const child of this.children(node)) {
this.removeNode(node, child);
}
diff --git a/packages/runtime/MIGRATION.md b/packages/runtime/MIGRATION.md
index 2542e449..15e69d94 100644
--- a/packages/runtime/MIGRATION.md
+++ b/packages/runtime/MIGRATION.md
@@ -15,13 +15,13 @@ 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), DocumentRoot |
-| `createRuntimeWorld(projectId)` | `src/world/create-world.ts` | Side-effect free except spawning the document root. No AudioContext/window access |
-| Document root model | everywhere | See below, this replaced "parentless = top-level" |
+| 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 |
+| `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(getDocument(world))`. Headless world without canvas skips culling instead of crashing |
+| 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`) |
@@ -49,15 +49,15 @@ Working doc for migrating the editor engine from bitecs (in `apps/web/src/compon
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.
-## Document root model
+## Stage model
-Every world spawns one entity tagged `DocumentRoot` (`createRuntimeWorld`). All rendered entities are its descendants; "top-level" means "direct child of the document", never "has no parent".
+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".
-- `getDocument(world)` returns it; `getParentNode(entity)` returns the parent or null when the parent is the document (use wherever top-level matters); `getParentEntity` returns the raw parent including the document.
-- Clone contract: the document id is per-session, so `serializeEntity` omits `ChildOf` when the parent is the root, and `cloneFromRecords` attaches parentless records to the target world's document.
+- `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 `getDocument(world).destroy()` tears down the whole document; clearing a project = destroy + respawn root.
-- Actions honor this: `createEntity` spawns as a document child; `appendChild` asserts `getParentNode(entity) === null` ("already has a parent" = has a non-document parent) and relies on exclusive re-targeting; `removeChild` re-parents to the document instead of dropping ChildOf. `cloneFromRecords` attaches parentless records to the document, so paste/duplicate roots land there too.
+- `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
@@ -120,11 +120,11 @@ apps/web now depends on `@diffusionstudio/runtime` and `@diffusionstudio/koota-s
- **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 document root 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`).
+- **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 document root 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-root parents goes back through the document, because `appendChild` asserts top-level.
+ - **`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.
diff --git a/packages/runtime/src/actions/cache.ts b/packages/runtime/src/actions/cache.ts
index a347f545..910bac29 100644
--- a/packages/runtime/src/actions/cache.ts
+++ b/packages/runtime/src/actions/cache.ts
@@ -14,7 +14,7 @@ import {
Geometry, Group, AdjustmentLayer, IsMask, Paint, Stroke, Shadow, Effect,
TextRange, KeyframeTrack, Keyframe, Animation,
} from '../traits';
-import { isDocument } from '../queries/predicates';
+import { isStage } from '../queries/predicates';
import { getParentNode } from '../queries/hierarchy';
import { sortByFrame, sortByItemIndex } from '../utils/sort';
import { resetAnimatedValues } from '../systems/motion';
@@ -29,7 +29,7 @@ import type { Entity, World } from 'koota';
* parent's queries.
*/
export function rebuildCaches(world: World, entity: Entity, parent: Entity | null, exclude: Entity | null = null) {
- if (parent === null || isDocument(parent)) return;
+ if (parent === null || isStage(parent)) return;
if (!parent.has(Cache)) parent.add(Cache);
const cache = store(world, Cache);
diff --git a/packages/runtime/src/actions/entities.ts b/packages/runtime/src/actions/entities.ts
index 6cf1af49..d2de999f 100644
--- a/packages/runtime/src/actions/entities.ts
+++ b/packages/runtime/src/actions/entities.ts
@@ -13,7 +13,7 @@ import type { Entity, World } from 'koota';
/**
* Spawn an empty document entity. Computed/Cache are pre-attached (systems
* index into their stores unconditionally), and the entity starts as a child
- * of the document root, i.e. top-level, until appendChild re-parents it.
+ * of the stage, i.e. top-level, until appendChild re-parents it.
*/
export function createEntity(world: World): Entity {
return world.spawn(
diff --git a/packages/runtime/src/actions/hierarchy.ts b/packages/runtime/src/actions/hierarchy.ts
index 4e395b98..d16b4730 100644
--- a/packages/runtime/src/actions/hierarchy.ts
+++ b/packages/runtime/src/actions/hierarchy.ts
@@ -4,7 +4,7 @@
// Parenting and ordering actions (was api/hierarchy.ts). ChildOf is exclusive,
// so re-parenting is a single add; "no parent" does not exist under the
-// document root model: detached entities go back to being document children.
+// stage model: detached entities go back to being children of the stage.
// Cache/size/constraint/time-range fixups ride on the ChildOf events (see
// world/observers.ts), so these functions only validate and re-target.
@@ -30,7 +30,7 @@ export function appendChild(world: World, entity: Entity, parent: Entity): void
export function removeChild(world: World, entity: Entity, parent: Entity): void {
assert(getParentNode(entity) === parent, 'Entity is not a child of the specified parent');
- // Back to top-level: re-target to the document (never drop ChildOf).
+ // Back to top-level: re-target to the stage (never drop ChildOf).
entity.add(ChildOf(world.get(Root)!));
}
diff --git a/packages/runtime/src/queries/camera.ts b/packages/runtime/src/queries/camera.ts
index 2562851d..efb8e053 100644
--- a/packages/runtime/src/queries/camera.ts
+++ b/packages/runtime/src/queries/camera.ts
@@ -2,7 +2,7 @@
* 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/. */
-// Camera read path. The Camera trait on the document root is the viewport
+// Camera read path. The Camera trait on the stage is the viewport
// transform: it maps document space to canvas CSS pixels, and the render and
// transform systems scale it by RenderSurface.resolution to reach device
// pixels (getViewMatrix). Writes live in actions/camera.ts.
diff --git a/packages/runtime/src/queries/hierarchy.ts b/packages/runtime/src/queries/hierarchy.ts
index 438322ac..ed0b71ec 100644
--- a/packages/runtime/src/queries/hierarchy.ts
+++ b/packages/runtime/src/queries/hierarchy.ts
@@ -3,7 +3,7 @@
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
import { ChildOf, Computed, Name, Playback } from '../traits';
-import { isDocument, isScene } from './predicates';
+import { isStage, isScene } from './predicates';
// Direct module, not the utils barrel: utils/time reaches back into this file.
import { sortByItemIndex } from '../utils/sort';
@@ -19,13 +19,13 @@ export function getEntityChildren(world: World, parent: Entity): Entity[] {
}
/**
- * Parent node, or null when the parent is the document root (or missing).
+ * Parent node, or null when the parent is the stage (or missing).
* Use this wherever "top-level" matters; getParentEntity returns the raw
- * parent including the document.
+ * parent including the stage.
*/
export function getParentNode(entity: Entity | null | undefined): Entity | null {
const parent = getParentEntity(entity);
- if (parent === null || isDocument(parent)) return null;
+ if (parent === null || isStage(parent)) return null;
return parent;
}
diff --git a/packages/runtime/src/queries/predicates.ts b/packages/runtime/src/queries/predicates.ts
index c1ef94b4..e54860ef 100644
--- a/packages/runtime/src/queries/predicates.ts
+++ b/packages/runtime/src/queries/predicates.ts
@@ -4,14 +4,14 @@
import {
Scene, Group, Sequential, Audio, AdjustmentLayer, Caption, Geometry, IsMask,
- Paint, Cache, DocumentRoot,
+ Paint, Cache, Stage,
} from '../traits';
import { GeometryType, PaintType } from '../constants';
import type { Entity } from 'koota';
-export function isDocument(entity: Entity): boolean {
- return entity.has(DocumentRoot);
+export function isStage(entity: Entity): boolean {
+ return entity.has(Stage);
}
export function isScene(entity: Entity): boolean {
diff --git a/packages/runtime/src/systems/render.ts b/packages/runtime/src/systems/render.ts
index 4a631a9f..8d9f6c2a 100644
--- a/packages/runtime/src/systems/render.ts
+++ b/packages/runtime/src/systems/render.ts
@@ -859,8 +859,8 @@ export function renderSystem(world: World): void {
ctx.setTransform(view.a, view.b, view.c, view.d, view.e, view.f);
// Render top-level nodes.
- const document = world.get(Root)!;
- for (const entity of world.query(Or(Geometry, Group), ChildOf(document), Not(Culled))) {
+ const stage = world.get(Root)!;
+ for (const entity of world.query(Or(Geometry, Group), ChildOf(stage), Not(Culled))) {
renderNode(world, entity);
}
}
diff --git a/packages/runtime/src/traits/world.ts b/packages/runtime/src/traits/world.ts
index 21230eb1..f07f48e5 100644
--- a/packages/runtime/src/traits/world.ts
+++ b/packages/runtime/src/traits/world.ts
@@ -17,20 +17,15 @@ import type { Quad } from '../math/aabb';
export const Project = trait({ id: '' });
-// Tag on the single document root entity every runtime world owns. All
-// rendered entities are its descendants (ChildOf), so "top-level" means
-// "direct child of the document", never "has no parent". Destroying it
-// cascades through the whole document tree. Document-level state (Camera,
-// Background) lives on this entity, not on the world; read it via
-// getDocument(world).
-export const DocumentRoot = trait();
-
-// World-level pointer to the root entity
+// Tag on the single stage entity every runtime world owns.
+export const Stage = trait();
+
+// World-level pointer to the stage entity
export const Root = trait(() => null as Entity | null);
/**
* 2D affine camera transform in CSS pixel space (before DPR scaling), on the
- * document root. The render system multiplies this by RenderSurface.resolution
+ * stage. The render system multiplies this by RenderSurface.resolution
* to derive the canvas transform.
*/
export const Camera = trait({ a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 });
@@ -39,7 +34,7 @@ export type Camera2D = { a: number; b: number; c: number; d: number; e: number;
export const DEFAULT_BACKGROUND = 0x161616;
-// Stage background color, on the document root.
+// Stage background color, on the stage entity.
export const Background = trait({ value: DEFAULT_BACKGROUND });
export type RuntimeMode = 'realtime' | 'offline-video' | 'offline-audio';
diff --git a/packages/runtime/src/world/create-world.ts b/packages/runtime/src/world/create-world.ts
index 5bf0df71..1a262179 100644
--- a/packages/runtime/src/world/create-world.ts
+++ b/packages/runtime/src/world/create-world.ts
@@ -6,7 +6,7 @@ import { createWorld } from 'koota';
import { observeWorld } from './observers';
import {
- DocumentRoot,
+ Stage,
Root,
Project,
Mode,
@@ -51,8 +51,7 @@ export function createRuntimeWorld(projectId: string) {
Root,
);
- // The document root all rendered entities hang off (see DocumentRoot);
- world.set(Root, world.spawn(DocumentRoot, Camera, Background));
+ world.set(Root, world.spawn(Stage, Camera, Background));
// Cache upkeep, Computed mirrors, and time-range reactions.
observeWorld(world);
diff --git a/packages/runtime/src/world/serialize.ts b/packages/runtime/src/world/serialize.ts
index 16d926ac..9cf0a483 100644
--- a/packages/runtime/src/world/serialize.ts
+++ b/packages/runtime/src/world/serialize.ts
@@ -15,7 +15,7 @@ import {
Start, End, SourceIn, SourceOut, PlaybackRate,
Playback, Sequential, Transition, ClipHeight, Expanded,
Volume, Muted,
- KeyframeTrack, Keyframe, Animation, DocumentRoot,
+ KeyframeTrack, Keyframe, Animation, Stage,
} from '../traits';
import { createEntity } from '../actions/entities';
@@ -231,7 +231,7 @@ export function serializeEntity(entity: Entity): EntityRecord {
record.Expanded = {};
}
const parent = entity.targetFor(ChildOf);
- if (parent !== undefined && !parent.has(DocumentRoot)) {
+ if (parent !== undefined && !parent.has(Stage)) {
record.ChildOf = parent;
}
if (entity.has(IsMask)) {
diff --git a/reference/jsx/paints.md b/reference/jsx/paints.md
index ab20f970..1fc15093 100644
--- a/reference/jsx/paints.md
+++ b/reference/jsx/paints.md
@@ -23,6 +23,6 @@ Paint elements are valid inside any filled visual element (`<rect>`, `<text>`, `
| [`<surfacePaint>`](./surface-paint.md) | `opacity`, `ref` (**required**) | A canvas your `ref` callback draws into (any context type), sampled into the parent's box every frame. `<surface>` is shorthand for a `<rect>` carrying one. |
| [`<shaderPaint>`](./shader-paint.md) | `opacity`, `wgsl` (**required**), `uniforms` | A WGSL fragment shader applied to the video/image paint directly below it (that media renders only through the shader's output), or run procedurally when there is none. |
-Colors accept any CSS color; alpha is ignored (use `opacity`). `color`, `opacity`, and `offset` are animatable (see [keyframes.md](./keyframes.md)), so gradients can animate. Paints have no spatial or timing props and cannot be document roots.
+Colors accept any CSS color; alpha is ignored (use `opacity`). `color`, `opacity`, and `offset` are animatable (see [keyframes.md](./keyframes.md)), so gradients can animate. Paints have no spatial or timing props and cannot be stage roots.
Paints are live entities like any other: patch them with `dapi node patch`, and add a stop to an existing gradient with `dapi node insert` (`node insert <paintId> '<colorStop offset={0.5} color="#FF0055" />'`).
diff --git a/reference/jsx/roots.md b/reference/jsx/roots.md
index 2b9955bb..b4a8fd74 100644
--- a/reference/jsx/roots.md
+++ b/reference/jsx/roots.md
@@ -8,7 +8,7 @@ A mount renders one or more root elements (a fragment of roots is allowed) and *
Identities must be unique within a render, and rebuilding keeps the scene's entity id and canvas position. Scenes with no matching render are never touched. The **first** rendered root becomes the active scene. Assigning a `name` alongside is recommended (e.g. `<rect scene="intro" name="Intro">`): `scene` identifies the node across mounts, the name labels it in the editor.
-The `scene` property is valid **only** at the document root.
+The `scene` property is valid **only** at the stage root.
`dapi node insert` skips this reconciliation entirely: its roots are inserted as children and every run inserts fresh entities.