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.tsindex 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.tsindex 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.mdindex 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/componVerification 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.tsindex 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.tsindex 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.tsindex 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): voidexport 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 entityexport 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.tsindex 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.tsindex 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.mdindex 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.mdindex 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.