The VS Code of video editing, built for agents.
TypeScript
Refactor JSX elements to replace `<scene>` with `<rect>` using the `scene` property for root promotion
konstantin-paulus90d0959a91dc
diff --git a/README.md b/README.mdindex b1df1a06..43f49061 100644--- a/README.md+++ b/README.md@@ -28,7 +28,7 @@ const TITLES = [export default function Project() {return (- <scene key="intro" name="Intro" width={1920} height={1080} fill="black">+ <rect scene="intro" name="Intro" width={1920} height={1080} fill="black"><video src={motion} width={1920} height={1080} /><sequence><For each={TITLES}>@@ -48,7 +48,7 @@ export default function Project() {)}</For></sequence>- </scene>+ </rect>);}```diff --git a/apps/cli/src/compile-project.ts b/apps/cli/src/compile-project.tsindex d7d8ad6c..62241999 100644--- a/apps/cli/src/compile-project.ts+++ b/apps/cli/src/compile-project.ts@@ -98,7 +98,7 @@ function resolveBareSpecifier(spec: string, { cdnBase, importMap }: ResolverConf// Project files write `<rect>`; the renderer keeps receiving `Rect`, so a// tag's case still decides its environment at runtime.const BUILT_IN_TAGS: Record<string, string> = {- scene: "Scene", group: "Group", rect: "Rect", video: "Video", image: "Image",+ group: "Group", rect: "Rect", video: "Video", image: "Image",audio: "Audio", text: "Text", sequence: "Sequence", captions: "Captions",solidPaint: "SolidPaint", linearGradientPaint: "LinearGradientPaint",radialGradientPaint: "RadialGradientPaint", colorStop: "ColorStop",diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.tsindex 0deb29d6..b30e05b5 100644--- a/apps/cli/src/index.ts+++ b/apps/cli/src/index.ts@@ -1127,7 +1127,7 @@ programprogram.command("mount").description(- `Compile a Solid JSX project module and mount its roots into the canvas. Re-mounting reconciles rather than duplicates: each top-level element carries a \`key\`, and a root replaces the node with that key or creates it (a new <scene key> becomes the active scene and the camera focuses it). A mount stays live: its reactive graph keeps running (signals, effects, timers, \`useTicker\`), and the persisted module is re-executed in every context, so the mount is restored on reload and ticker-driven <surface>/<html> animate in exports and captures (structure must be deterministic). Long-running when the module declares AI assets (blocks until generation finishes). Compile errors fail before the app is contacted; inspect the result with \`dapi context\` or \`dapi node tree\`.`,+ `Compile a Solid JSX project module and mount its roots into the canvas. Re-mounting reconciles rather than duplicates: only a scene is mountable as a root, carrying its identity in \`scene\`, and a root replaces the scene with that identity or creates it (a new scene, promoted with \`scene\`, becomes the active scene and the camera focuses it). A mount stays live: its reactive graph keeps running (signals, effects, timers, \`useTicker\`), and the persisted module is re-executed in every context, so the mount is restored on reload and ticker-driven <surface>/<html> animate in exports and captures (structure must be deterministic). Long-running when the module declares AI assets (blocks until generation finishes). Compile errors fail before the app is contacted; inspect the result with \`dapi context\` or \`dapi node tree\`.`,).argument("[path]", "path to a .tsx / .jsx / .ts / .js entry module").option("--code <str>", "inline module source; export default wrapper optional for bare JSX")@@ -1390,7 +1390,7 @@ nodenode.command("insert").description(- `Insert JSX tags as children of an existing entity. The payload is an inline JSX fragment, e.g. \`'<rect width={10} height={10} />'\` — bare tags, no \`export default\`: an insert renders once and is discarded, so there is no live graph to drive (use \`dapi mount\` for anything reactive). Otherwise it shares the \`mount\` pipeline, including AI asset generation, but inserts fresh entities every run rather than reconciling by key, and deletes nothing. Roots must be valid children of the parent (a node takes any element or paint except <scene> and <colorStop>; a gradient paint takes only <colorStop> roots, which is how you add a stop to a gradient).`,+ `Insert JSX tags as children of an existing entity. The payload is an inline JSX fragment, e.g. \`'<rect width={10} height={10} />'\` — bare tags, no \`export default\`: an insert renders once and is discarded, so there is no live graph to drive (use \`dapi mount\` for anything reactive). Otherwise it shares the \`mount\` pipeline, including AI asset generation, but inserts fresh entities every run rather than reconciling by key, and deletes nothing. Roots must be valid children of the parent (a node takes any element or paint except a scene root carrying \`scene\` and <colorStop>; a gradient paint takes only <colorStop> roots, which is how you add a stop to a gradient).`,).argument("<parentId>", "entity id of the parent to insert into — a node, or a gradient paint for <colorStop> roots").argument("<code>", "JSX tags to insert, e.g. '<rect width={10} height={10} />' (no export default)")diff --git a/apps/web/src/utils/genai.ts b/apps/web/src/utils/genai.tsindex be8b7193..b9009ee8 100644--- a/apps/web/src/utils/genai.ts+++ b/apps/web/src/utils/genai.ts@@ -61,6 +61,7 @@ export function findEmptyPlacement(width: number,height: number,gap: number,+ extra: AABB[] = [],): { x: number; y: number } {const center = getViewportCenter(world);const viewport = getViewportBounds(world);@@ -69,7 +70,10 @@ export function findEmptyPlacement(const LocalTransform = c.LocalTransform;const Computed = c.Computed;- const boxes: AABB[] = [];+ // `extra` boxes are content the world can't report yet — e.g. sibling roots+ // placed earlier in the same mount, whose layout has not been computed. They+ // are avoided and anchored beside like any existing box.+ const boxes: AABB[] = [...extra];for (const cid of query(world, [Or(c.Geometry, c.Group), Not(ChildOf('*')), Not(c.Deleted), Not(c.Hidden), Not(c.Generating)])) {const w = Computed.width[cid];const h = Computed.height[cid];diff --git a/apps/web/src/utils/jsx.ts b/apps/web/src/utils/jsx.tsindex 7eafc727..c3f0c5b7 100644--- a/apps/web/src/utils/jsx.ts+++ b/apps/web/src/utils/jsx.ts@@ -49,7 +49,7 @@ import { resolveAsset, resolveGeneratedAsset } from "@/utils/jsx-generation";import { assert, assertAllSettled, parseColor } from "@/utils";import type { AssetInput, AssetRef, AssetSpecInput, ProjectDocument, ProjectTick } from "@diffusionstudio/jsx";-import type { Engine, EngineWorld, MountData } from "@/components/engine";+import type { AABB, Engine, EngineWorld, MountData } from "@/components/engine";import type { GenerationMemo } from "@/utils/jsx-generation";export class EntityNode {@@ -370,6 +370,11 @@ export class WorldDocument implements ProjectDocument<HostNode> {// through the initial adopt render; only post-commit effects write.private adopted = new Set<number>();+ // World-space boxes of the new roots this mount has already placed. A fresh+ // root has no computed layout yet, so `findEmptyPlacement` cannot see it in+ // the world; recording each placement here keeps sibling roots from stacking.+ private placedRootBoxes: AABB[] = [];+// Entities this render soft-deleted via removeNode. Solid's reconciler// shuffles by removing and re-inserting nodes, so re-attaching one of// these resurrects it — but only these: an entity deleted from outside@@ -690,14 +695,7 @@ export class WorldDocument implements ProjectDocument<HostNode> {const eid = createEntity(world);switch (tag) {- case "Scene": {- setComponent(world, eid, c.Geometry, GeometryType.RECT);- addComponent(world, eid, c.Scene);- addComponent(world, eid, c.ClipsContent);- setComponent(world, eid, c.Playback, {});- setComponent(world, eid, c.Name, getNextName(world, "Scene"));- break;- } case "Group": {+ case "Group": {setComponent(world, eid, c.Geometry, GeometryType.RECT);addComponent(world, eid, c.Group);setComponent(world, eid, c.Name, getNextName(world, "Group"));@@ -1215,6 +1213,24 @@ export class WorldDocument implements ProjectDocument<HostNode> {setComponent(world, eid, c.Key, value.trim());break;}+ case "scene": {+ // Promotes a rectangle geometry to a scene (mount root): it carries the+ // Scene markers, and the `scene` value is the root's identity (stamped+ // onto Key, which insertRoot uses to replace a scene on re-mount).+ assert(typeof value === "string", "`scene` must be a string" + `, value: ${value}`);+ assert(value.trim().length > 0, "`scene` must be a non-empty string");+ assert(+ c.Geometry[eid] === GeometryType.RECT,+ "`scene` only applies to a rectangle geometry (`<rect>`, `<group>`, `<html>`, `<image>`, `<video>`)",+ );+ if (!hasComponent(world, eid, c.Scene)) {+ addComponent(world, eid, c.Scene);+ addComponent(world, eid, c.ClipsContent);+ setComponent(world, eid, c.Playback, {});+ }+ setComponent(world, eid, c.Key, value.trim());+ break;+ }case "wgsl": {assert(c.Paint[eid] === PaintType.SHADER, "`wgsl` only applies to <ShaderPaint>");assert(typeof value === "string", "`wgsl` must be a string" + `, value: ${value}`);@@ -1414,6 +1430,10 @@ export class WorldDocument implements ProjectDocument<HostNode> {!this.htmlHosts.has(parent.eid),"a composition element cannot be <html> content; an SVG fragment (<rect>/<text>/<image>) compiles as SVG only inside <svg> or <g>; wrap it",);+ assert(+ this.adopted.has(node.eid) || !hasComponent(world, node.eid, c.Scene),+ "a scene cannot be nested: the `scene` property is valid only at the document root",+ );// Adopted entities already sit under their persisted parent, so this// no-ops for them on the initial adopt render; afterwards it moves and// resurrects them like any other entity (e.g. a <For> shuffling rows).@@ -1434,17 +1454,22 @@ export class WorldDocument implements ProjectDocument<HostNode> {if (this.stageEid !== undefined) {this.attachEntity(eid, this.stageEid);} else {- assert(hasComponent(world, eid, c.Geometry), "this element cannot be a document root");+ assert(+ hasComponent(world, eid, c.Scene),+ 'only a scene can be a mount root: promote a rectangle geometry with `scene`, e.g. <rect scene="main" width={1920} height={1080}>',+ );const key = c.Key[eid];- assert(key !== undefined, "`key` is required for `root` nodes");// Find and replace node with the same keyconst existing = query(world, [c.Key, Not(c.Deleted)]).find((other) => other !== eid && c.Key[other] === key);if (existing === undefined) {- const width = c.Computed.width[eid] ?? 0;- const height = c.Computed.height[eid] ?? 0;+ const { width, height } = this.props(eid) ?? {};+ assert(+ typeof width === "number" && typeof height === "number",+ "a scene requires numeric `width` and `height`",+ );setComponent(world, eid, c.Position, this.findPlacement(width, height));} else {setComponent(world, eid, c.Position, {@@ -1739,7 +1764,13 @@ export class WorldDocument implements ProjectDocument<HostNode> {}private findPlacement(width: number, height: number): { x: number; y: number } {- const center = findEmptyPlacement(this.world, width, height, PLACEMENT_GAP);+ const center = findEmptyPlacement(this.world, width, height, PLACEMENT_GAP, this.placedRootBoxes);+ this.placedRootBoxes.push({+ minX: center.x - width / 2,+ minY: center.y - height / 2,+ maxX: center.x + width / 2,+ maxY: center.y + height / 2,+ });return {x: Math.round(center.x - width / 2),y: Math.round(center.y - height / 2),diff --git a/examples/01-basics.tsx b/examples/01-basics.tsxindex ae756f76..2ab35ed5 100644--- a/examples/01-basics.tsx+++ b/examples/01-basics.tsx@@ -47,7 +47,7 @@ function Title(props: { text: string; start: Time; end: Time }) {export default function Basics() {return (- <scene key="example-basics" name="Basics" width={1920} height={1080} fill="black">+ <rect scene="example-basics" name="Basics" width={1920} height={1080} fill="black"><sequence name="A-roll"><videosrc={`${VIDEOS}/sintel-short.mp4`}@@ -76,6 +76,6 @@ export default function Basics() {<For each={TITLES}>{(t) => <Title {...t} />}</For><audio name="Music bed" src={MUSIC} start={0} end={12} volume={-16} />- </scene>+ </rect>);}diff --git a/examples/02-genai.tsx b/examples/02-genai.tsxindex d817c2db..f06b9375 100644--- a/examples/02-genai.tsx+++ b/examples/02-genai.tsx@@ -55,7 +55,7 @@ const ambience = generate.audio({export default function GenAi() {return (- <scene key="example-genai" name="GenAI" width={1920} height={1080} fill="black">+ <rect scene="example-genai" name="GenAI" width={1920} height={1080} fill="black"><sequence name="Generated shots"><video src={shot1} width={1920} height={1080} start={0} end={5} transition={{}} /><video src={shot2} width={1920} height={1080} start={5} end={10} />@@ -65,6 +65,6 @@ export default function GenAi() {<audio name="Ambience" src={ambience} start={0} end={10} volume={-18} /><captions preset="spotlight" verticalAlign="bottom" />- </scene>+ </rect>);}diff --git a/examples/03-ticker.tsx b/examples/03-ticker.tsxindex 2c3deb6b..4a652739 100644--- a/examples/03-ticker.tsx+++ b/examples/03-ticker.tsx@@ -25,7 +25,7 @@ export default function Ticker() {const eased = createMemo(() => 0.5 - Math.cos(angle()) / 2); // 0..1..0, smoothreturn (- <scene key="example-ticker" name="Ticker" width={1920} height={1080} fill="#101014">+ <rect scene="example-ticker" name="Ticker" width={1920} height={1080} fill="#101014">{/* center square: rotation and corner radius both derive from progress */}<rectx={860}@@ -61,6 +61,6 @@ export default function Ticker() {<text x={80} y={64} width={1200} height={60} fontSize={44} fontFamily="Inter">t = {time().toFixed(2)}s / frame {frame()} / loop {Math.round(progress() * 100)}%</text>- </scene>+ </rect>);}diff --git a/examples/04-html-in-canvas.tsx b/examples/04-html-in-canvas.tsxindex 45861f25..79cb301c 100644--- a/examples/04-html-in-canvas.tsx+++ b/examples/04-html-in-canvas.tsx@@ -24,7 +24,7 @@ export default function PromptBox() {const cursorOn = createMemo(() => Math.floor(time() * 2) % 2 === 0);return (- <scene key="example-html" name="Prompt box" width={1920} height={1080} fill="#0b0d12">+ <rect scene="example-html" name="Prompt box" width={1920} height={1080} fill="#0b0d12"><htmlx={460}y={400}@@ -60,6 +60,6 @@ export default function PromptBox() {</div></div></html>- </scene>+ </rect>);}diff --git a/examples/05-anime-timeline.tsx b/examples/05-anime-timeline.tsxindex e6097ae9..404b6871 100644--- a/examples/05-anime-timeline.tsx+++ b/examples/05-anime-timeline.tsx@@ -40,7 +40,7 @@ export default function AnimeTimeline() {const hue = () => Math.round(v.card.hue);return (- <scene key="example-anime" name="Anime timeline" width={960} height={540} fill="#101014">+ <rect scene="example-anime" name="Anime timeline" width={960} height={540} fill="#101014"><rectx={v.chip.x}y={v.chip.y}@@ -84,6 +84,6 @@ export default function AnimeTimeline() {</div></div></html>- </scene>+ </rect>);}diff --git a/examples/06-three.tsx b/examples/06-three.tsxindex 7230bfc3..164275c2 100644--- a/examples/06-three.tsx+++ b/examples/06-three.tsx@@ -96,8 +96,8 @@ export default function ThreeHelmet() {};return (- <scene key="example-three" name="Three helmet" width={960} height={540} fill="#0b0d12">+ <rect scene="example-three" name="Three helmet" width={960} height={540} fill="#0b0d12"><surface x={0} y={0} width={960} height={540} ref={setup} />- </scene>+ </rect>);}diff --git a/examples/07-webgpu.tsx b/examples/07-webgpu.tsxindex 9a465bcd..a6150a41 100644--- a/examples/07-webgpu.tsx+++ b/examples/07-webgpu.tsx@@ -110,8 +110,8 @@ export default function WebgpuTriangle() {onCleanup(() => gpu()?.device.destroy());return (- <scene key="example-webgpu" name="WebGPU triangle" width={960} height={540} fill="#0b0d12">+ <rect scene="example-webgpu" name="WebGPU triangle" width={960} height={540} fill="#0b0d12"><surface x={0} y={0} width={960} height={540} ref={setup} />- </scene>+ </rect>);}diff --git a/examples/08-shader-paint.tsx b/examples/08-shader-paint.tsxindex 8e96fb20..5234afb3 100644--- a/examples/08-shader-paint.tsx+++ b/examples/08-shader-paint.tsx@@ -37,10 +37,10 @@ const ABERRATION = /* wgsl */ `export default function ShaderPaintExample() {return (- <scene key="example-shader-paint" name="Shader paint" width={1920} height={1080} fill="#000000">+ <rect scene="example-shader-paint" name="Shader paint" width={1920} height={1080} fill="#000000"><video src={`${VIDEOS}/sintel-short.mp4`} width={1920} height={1080}><shaderPaint wgsl={ABERRATION} uniforms={{ strength: 1.5, vignette: 0.6 }} /></video>- </scene>+ </rect>);}diff --git a/examples/09-html-scene.tsx b/examples/09-html-scene.tsxnew file mode 100644index 00000000..79e2fe6a--- /dev/null+++ b/examples/09-html-scene.tsx@@ -0,0 +1,52 @@+/* @jsxImportSource @diffusionstudio/jsx */+/* An HTML scene: the mount root is <html>, so the whole frame is one DOM tree+ * laid out by the browser (flexbox here), not a box placed inside a scene.+ *+ * dapi mount examples/09-html-scene.tsx+ *+ * The `scene` prop promotes any rectangle geometry to a mount root; on <html>+ * that means the browser lays the DOM out at the full composition size and the+ * result is drawn into the frame (html-in-canvas). Requires Chromium's+ * html-in-canvas API (chrome://flags/#canvas-draw-element). The count-up and+ * the progress bar derive from the playhead, so they scrub and export+ * frame-accurately. Event handlers are dropped: this is painted, not+ * interactive.+ */++import { createMemo } from "solid-js";+import { useTicker } from "@diffusionstudio/jsx";++const DURATION = 6; // seconds+const TARGET = 128; // final count-up value++export default function HtmlScene() {+ const { time } = useTicker();++ const t = createMemo(() => Math.min(time() / DURATION, 1)); // 0..1 clamped+ const count = createMemo(() => Math.round(t() * TARGET));++ return (+ <html scene="html-scene" name="HTML scene" width={1920} height={1080}>+ <div+ style={`width:1920px;height:1080px;box-sizing:border-box;+ display:flex;flex-direction:column;justify-content:center;gap:48px;+ padding:160px;font-family:Inter;color:white;+ background:radial-gradient(120% 120% at 20% 0%,#1a2030,#0b0d12);`}+ >+ <div style="font-size:22px;letter-spacing:6px;opacity:0.5;">DIFFUSION STUDIO</div>++ <div style="display:flex;align-items:baseline;gap:24px;">+ <div style="font-size:220px;font-weight:800;line-height:1;">{count()}</div>+ <div style="font-size:40px;opacity:0.6;">frames composed</div>+ </div>++ <div style="width:100%;height:14px;border-radius:999px;background:#ffffff1a;overflow:hidden;">+ <div+ style={`width:${(t() * 100).toFixed(2)}%;height:100%;border-radius:999px;+ background:linear-gradient(90deg,#7c9cff,#c07cff);`}+ />+ </div>+ </div>+ </html>+ );+}diff --git a/examples/README.md b/examples/README.mdindex 1ae3916c..5a5ece98 100644--- a/examples/README.md+++ b/examples/README.md@@ -1,12 +1,12 @@# ExamplesSelf-contained compositions demonstrating the JSX API (see [reference/jsx](../reference/jsx/README.md)).-Run from the repo root with the editor open (`dapi open`). Each root scene carries a stable-key, so re-mounting an example replaces its scene in place.+Run from the repo root with the editor open (`dapi open`). Each root carries a stable `scene`+identity, so re-mounting an example replaces its scene in place.| Example | Command | Shows || --- | --- | --- |-| [01-basics.tsx](01-basics.tsx) | `dapi mount examples/01-basics.tsx` | `<scene>`, `<sequence>` with a dissolve, `<video>`, `<audio>`, `<image>`, `<text>` titles from data via `<For>` |+| [01-basics.tsx](01-basics.tsx) | `dapi mount examples/01-basics.tsx` | the `scene` prop promoting a root, `<sequence>` with a dissolve, `<video>`, `<audio>`, `<image>`, `<text>` titles from data via `<For>` || [02-genai.tsx](02-genai.tsx) | `dapi mount examples/02-genai.tsx` | multi-stage generation: `generate.image` refs feeding `generate.video`, TTS voiceover, generated ambience, `<captions>` || [03-ticker.tsx](03-ticker.tsx) | `dapi mount examples/03-ticker.tsx` | declarative animation: `useTicker` + `createMemo` derived values driving props || [04-html-in-canvas.tsx](04-html-in-canvas.tsx) | `dapi mount examples/04-html-in-canvas.tsx` | `<html>`: an AI prompt box as real DOM, typed out from the playhead |@@ -14,10 +14,11 @@ key, so re-mounting an example replaces its scene in place.| [06-three.tsx](06-three.tsx) | `dapi mount examples/06-three.tsx` | three.js WebGL renderer owning a `<surface>`, glTF model loaded over the network || [07-webgpu.tsx](07-webgpu.tsx) | `dapi mount examples/07-webgpu.tsx` | raw WebGPU on a `<surface>`: a triangle whose colors cycle with composition time || [08-shader-paint.tsx](08-shader-paint.tsx) | `dapi mount examples/08-shader-paint.tsx` | `<shaderPaint>` post-processing a `<video>`: WGSL chromatic aberration + vignette, uniforms patchable live |+| [09-html-scene.tsx](09-html-scene.tsx) | `dapi mount examples/09-html-scene.tsx` | an HTML scene: `<html scene=...>` as the mount root, the whole frame laid out as DOM and counting up from the playhead |Requirements: `02-genai.tsx` consumes generation credits (results are cached per session);-`04-html-in-canvas.tsx` and `05-anime-timeline.tsx` need Chromium's html-in-canvas API-(`chrome://flags/#canvas-draw-element`); `07-webgpu.tsx` and `08-shader-paint.tsx` need WebGPU;+`04-html-in-canvas.tsx`, `05-anime-timeline.tsx`, and `09-html-scene.tsx` need Chromium's+html-in-canvas API (`chrome://flags/#canvas-draw-element`); `07-webgpu.tsx` and `08-shader-paint.tsx` need WebGPU;`01-basics.tsx`, `06-three.tsx`, and `08-shader-paint.tsx` fetch remote media.Typecheck with `tsc -p examples --noEmit` (part of `npm run check`).diff --git a/packages/jsx/README.md b/packages/jsx/README.mdindex 464cdbe2..be30ebc3 100644--- a/packages/jsx/README.md+++ b/packages/jsx/README.md@@ -13,13 +13,13 @@ const hero = generate.image({ prompt: "A neon city at night, cinematic" });export default function Project() {return (- <scene key="intro" name="Intro" width={1920} height={1080}>+ <rect scene="intro" name="Intro" width={1920} height={1080}><image src={hero} /><text textAlign="center" textBaseline="middle" fontSize={128} fontWeight="bold">Hello World</text><captions />- </scene>+ </rect>);}```diff --git a/packages/jsx/src/elements.ts b/packages/jsx/src/elements.tsindex 5c6cbe9c..fa9792a7 100644--- a/packages/jsx/src/elements.ts+++ b/packages/jsx/src/elements.ts@@ -27,7 +27,6 @@ import type {HtmlProps,ImageProps,RectProps,- SceneProps,SequenceProps,ShaderPaintProps,SolidPaintProps,@@ -53,7 +52,6 @@ function hostElement<P extends object>(tag: string): (props: P) => SolidJSX.Elem};}-export const Scene = hostElement<SceneProps>("Scene");export const Group = hostElement<GroupProps>("Group");export const Rect = hostElement<RectProps>("Rect");export const Video = hostElement<VideoProps>("Video");diff --git a/packages/jsx/src/index.ts b/packages/jsx/src/index.tsindex 8630889a..41345211 100644--- a/packages/jsx/src/index.ts+++ b/packages/jsx/src/index.ts@@ -26,7 +26,6 @@ export {LinearGradientPaint,RadialGradientPaint,Rect,- Scene,Sequence,ShaderPaint,SolidPaint,@@ -55,7 +54,6 @@ export type {Keyframe,PatchProps,RectProps,- SceneProps,SequenceProps,ShaderPaintProps,SolidPaintProps,diff --git a/packages/jsx/src/jsx-runtime.ts b/packages/jsx/src/jsx-runtime.tsindex 634812fa..16f807f2 100644--- a/packages/jsx/src/jsx-runtime.ts+++ b/packages/jsx/src/jsx-runtime.ts@@ -8,7 +8,7 @@* "./renderer", so this module carries no runtime — only the JSX namespace* TypeScript resolves element and prop types from.*- * Composition elements are camelCase intrinsics (`<scene>`, `<rect>`, ...);+ * Composition elements are camelCase intrinsics (`<rect>`, `<group>`, ...);* the compile step canonicalizes them to the PascalCase components in* "./elements", so at runtime a tag's case still decides its environment.* Lowercase DOM tags are the vocabulary for `<htmlPaint>` content. The three@@ -29,7 +29,6 @@ import type {HtmlProps,ImageProps,RectProps,- SceneProps,SequenceProps,ShaderPaintProps,SolidPaintProps,@@ -59,7 +58,6 @@ export declare namespace JSX {}export interface IntrinsicElements extends HtmlElementTags, SvgElementTags {- scene: SceneProps;group: GroupProps;rect: RectProps | SolidJSX.SVGElementTags["rect"];video: VideoProps;diff --git a/packages/jsx/src/types.ts b/packages/jsx/src/types.tsindex 6a00d838..1b618902 100644--- a/packages/jsx/src/types.ts+++ b/packages/jsx/src/types.ts@@ -117,11 +117,20 @@ export type CaptionPreset =*/export type PatchProps = {/**- * Stable identity across mounts — required when the element is a document- * root: re-mounting replaces the node carrying the same key, or creates it- * if absent.+ * A within-render label so another node can reference this one: `syncTo`+ * names the `key` of the clip it aligns against. Not a mount mechanism, and+ * invalid on a scene root, which is identified by `scene`.*/key?: string;+ /**+ * Promotes this element to a scene (mount root), and is the root's stable+ * identity across mounts: re-mounting replaces the scene carrying the same+ * `scene` value, or creates it if absent. Only valid on a rectangle geometry+ * (`<rect>`, `<group>`, `<html>`, `<image>`, `<video>`); a scene root cannot+ * also carry placement or timing props (`x`/`y`/`start`/`end`/`transition`/+ * `animations`) or a separate `key`.+ */+ scene?: string;/** Human-readable node name. */name?: string;/** Position relative to the parent, px. Defaults to 0. Animatable. */@@ -226,6 +235,7 @@ export type PatchProps = {/** Every PatchProps key, at runtime — the `dapi node patch` allowlist. */export const PATCH_PROP_KEYS = Object.keys({key: true,+ scene: true,name: true,x: true,y: true,@@ -268,27 +278,10 @@ type TimingProps = Pick<PatchProps, "start" | "end" | "sourceIn" | "sourceOut">;type CommonProps = TimingProps &Pick<PatchProps,- | "key" | "name" | "x" | "y" | "offsetX" | "offsetY" | "width" | "height" | "rotation"+ | "key" | "scene" | "name" | "x" | "y" | "offsetX" | "offsetY" | "width" | "height" | "rotation"| "opacity" | "cornerRadius" | "transition" | "animations">;-export type SceneProps = {- /**- * Stable identity across mounts — required: re-mounting replaces the scene- * carrying the same key, or creates it if absent.- */- key: string;- /** Human-readable scene name — recommended, e.g. `name="Intro"`. */- name?: string;- /** Composition width in pixels. Required. */- width: number;- /** Composition height in pixels. Required. */- height: number;- /** Background fill, any CSS color (alpha is ignored). */- fill?: string;- children?: SolidJSX.Element;-};-export type GroupProps = CommonProps & Pick<PatchProps, "fill"> & {children?: SolidJSX.Element;};diff --git a/reference/README.md b/reference/README.mdindex 7ee2053f..10c7a765 100644--- a/reference/README.md+++ b/reference/README.md@@ -19,7 +19,7 @@ Each feature command has its own file (linked below). The JSX code syntax consumHow the surface is divided:- Declarative composition happens through `mount`, which renders a Solid JSX project into the canvas (see [jsx/](./jsx/README.md)); `node insert` runs the same pipeline but inserts the rendered nodes into an existing parent entity instead of mounting document roots.-- Scenes are created declaratively via `mount` (`<scene key="...">`); there is no imperative scene command.+- Scenes are created declaratively via `mount` (the `scene` property on a root, e.g. `<rect scene="...">`); there is no imperative scene command.- AI asset generation (image / video / speech / audio) is declared in the project module (`generate.*`, see [jsx/generate.md](./jsx/generate.md)) and produced on mount. `models` and `voices` list what those declarations can reference.- Inspecting an existing asset (probe / transcribe / listen / filmstrip / waveform / grab) lives under `media`; writing an asset's original file back to disk is `asset export`.- Organizing the library lives under `folder`; moving assets between folders is `asset mv`.diff --git a/reference/jsx/README.md b/reference/jsx/README.mdindex a9cae658..dd5650f2 100644--- a/reference/jsx/README.md+++ b/reference/jsx/README.md@@ -2,7 +2,7 @@The JSX API defines the code contract for injecting content into the editor via the CLI. Compositions are authored as **Solid components** that a custom renderer (built on `solid-js/universal`, Solid's equivalent of React's reconciler) mounts **directly into the editor's ECS**. Every JSX element becomes an entity; every prop is a component write. There is no hidden DOM, no CSS resolution, and no measuring pass.-A project is structured like a SolidJS app: a **root** is established on the canvas (typically a scene, identified by its key and created if absent) and the project's component tree renders into it. **All positioning is explicit** (`x`, `y`, `width`, `height` in pixels).+A project is structured like a SolidJS app: a **root** is established on the canvas (typically a scene, identified by its `scene` property and created if absent) and the project's component tree renders into it. **All positioning is explicit** (`x`, `y`, `width`, `height` in pixels).The markup is **pseudo-SVG**: elements like `<rect>`, `<text>`, `<linearGradientPaint>`, and `<colorStop>` mirror SVG's shape-and-paint model, but the tags and props are the editor's own (see [elements.md](./elements.md)), not the SVG spec.@@ -67,7 +67,7 @@ const TITLES = [export default function Project() {return (- <scene key="my-first-scene" name="MyFirstScene" fill="black" width={1920} height={1080}>+ <rect scene="my-first-scene" name="MyFirstScene" fill="black" width={1920} height={1080}><sequence><video src={heroMotion} width={1920} height={1080} start={0} end={5} transition={{ type: "dissolve" }} /><video src="/Movies/video.mp4" width={1920} height={1080} start={5} end={10} sourceIn={12} />@@ -81,7 +81,7 @@ export default function Project() {sourceOut={16}volume={-6}/>- </scene>+ </rect>);}```diff --git a/reference/jsx/audio-sync.md b/reference/jsx/audio-sync.mdindex 3c3eb5b0..67c6b715 100644--- a/reference/jsx/audio-sync.md+++ b/reference/jsx/audio-sync.md@@ -3,10 +3,10 @@`syncTo` places a node in time by listening instead of arithmetic: the node's audio is cross-correlated against another node's audio, and its `start` is computed so the two recordings coincide on the timeline. It replaces manual offset measurement for multi-recorder material: a lav or voice track against camera audio, two cameras on the same take, two microphones in one room.```tsx-<scene key="talk" width={1920} height={1080}>+<rect scene="talk" width={1920} height={1080}><video key="camera" src="/Movies/take-3.mp4" width={1920} height={1080} sourceOut={45} muted /><audio src="/Movies/lav.wav" syncTo="camera" />-</scene>+</rect>```## Semanticsdiff --git a/reference/jsx/elements.md b/reference/jsx/elements.mdindex 17ffa798..c53323b5 100644--- a/reference/jsx/elements.md+++ b/reference/jsx/elements.md@@ -4,7 +4,6 @@ camelCase composition elements map 1:1 onto internal node types. Lowercase DOM v| Element | Internal node | Notes || ------- | ------------- | ----- |-| [`<scene>`](./scene.md) | **Geometry with Scene tag** | Clips its children to `width`×`height`. Document root only. || [`<group>`](./group.md) | **Geometry with Group tag** | Container with a transform; auto-fits its size from its children. Takes no `fill` or explicit size. || [`<rect>`](./rect.md) | **Geometry with Solid paint** | A filled rectangle; takes only paint children. || [`<video>`](./video.md) | **Geometry with Video paint** | `src` resolves to a video asset. |@@ -19,6 +18,8 @@ camelCase composition elements map 1:1 onto internal node types. Lowercase DOM v| [`<html>`](./html-paint.md) | **Geometry with Html paint** | Children are real, reactive HTML drawn into the box by the browser (html-in-canvas, flagged Chromium API). `<htmlPaint>` is the paint child form. || [`<surface>`](./surface-paint.md) | **Geometry with Surface paint** | `ref` hands you a canvas to draw with any context type (2d, webgl, webgpu); sampled every frame. `<surfacePaint>` is the paint child form. |+Any rectangle geometry above (`<rect>`, `<group>`, `<video>`, `<image>`, `<html>`, `<surface>`) becomes a **scene** (the composition root) when given a `scene` identity: it then clips its children to `width`×`height` and is valid only at the document top level. See [scene.md](./scene.md).+User-defined components are ordinary Solid components; they compose the elements above and carry no runtime cost. Only the elements above produce entities.## Coordinates and sizing@@ -33,7 +34,8 @@ All visual elements accept:| Prop | Type | Default | Meaning || ---- | ---- | ------- | ------- |-| `key` | `string` | none | Stable identity across mounts; **required** on document roots (see [roots.md](./roots.md)). |+| `key` | `string` | none | A within-render label so another node can reference this one (e.g. [`syncTo`](./audio-sync.md)); |+| `scene` | `string` | none | Promotes a rectangle geometry to a scene, the only mountable root, and is its identity across mounts (see [scene.md](./scene.md)). || `name` | `string` | none | Human-readable node name. || `x`, `y` | `Animatable<number>` | `0` | Position relative to the parent, px. || `offsetX`, `offsetY` | `Animatable<number>` | `0` | Render-time translation on top of `x`/`y`, px; moves the drawn content without changing the layout box. Subpixel values are kept. |diff --git a/reference/jsx/errors.md b/reference/jsx/errors.mdindex 121a5cda..f3bdbc0e 100644--- a/reference/jsx/errors.md+++ b/reference/jsx/errors.md@@ -5,7 +5,7 @@ Where each [pipeline](./README.md#pipeline) stage fails, and with what effect:| Stage | Where it surfaces | Effect || ----- | ----------------- | ------ || Compile (syntax/type-stripping/bundling) | CLI stderr, exit 1 | App never contacted. |-| Evaluate / mount (thrown errors, invalid props, invalid root: e.g. nested `<scene>`, a root element without `key`, missing `src`, malformed `Time`, an unknown or cyclic `syncTo` key, `syncTo` combined with `start`) | CLI stderr, exit 1 | Staging root discarded; **nothing inserted**. |+| Evaluate / mount (thrown errors, invalid props, invalid root: e.g. a root that is not a scene, missing `src`, malformed `Time`, an unknown or cyclic `syncTo` key, `syncTo` combined with `start`) | CLI stderr, exit 1 | Staging root discarded; **nothing inserted**. || Generation (per-model constraints: `aspectRatio`, `duration`, feature flags) | CLI stderr, exit 1, after every generation settled | No rollback; the mounted tree stays committed. The affected placeholder stops showing its generating state and is left without a paint. || Sync (a side without a decodable audio track, or no reliable alignment) | CLI stderr, exit 1, after every alignment settled | No rollback; the tree stays committed and the node keeps its default placement. |diff --git a/reference/jsx/generate.md b/reference/jsx/generate.mdindex 801bbd56..5372ae84 100644--- a/reference/jsx/generate.md+++ b/reference/jsx/generate.md@@ -22,10 +22,10 @@ const heroMotion = generate.video({export default function Project() {return (- <scene key="intro" name="Intro" width={1920} height={1080}>+ <rect scene="intro" name="Intro" width={1920} height={1080}><video src={heroMotion} width={1920} height={1080} start={0} end={5} /><image src={hero} x={40} y={40} width={200} height={112} />- </scene>+ </rect>);}```diff --git a/reference/jsx/html-paint.md b/reference/jsx/html-paint.mdindex a913a603..53e7e7a5 100644--- a/reference/jsx/html-paint.md+++ b/reference/jsx/html-paint.md@@ -22,6 +22,19 @@ An element whose children are **real HTML**: the browser lays them out at the el```+## As a scene (full-frame HTML)++Give `<html>` a [`scene`](./scene.md) identity and it becomes the mount root: the browser lays the DOM out at the full composition size and the whole frame is HTML, with no wrapper and no repeated dimensions. A scene root is not timed by a parent, so the 16-second sourceless cutoff below does not apply here.++```tsx+<html scene="landing" name="Landing" width={1920} height={1080}>+ <div style="width:100%;height:100%;display:flex;align-items:center;justify-content:center;+ background:#0b0d12;color:#fff;font:800 120px Inter;">+ Hello+ </div>+</html>+```+## ReactivityThe children are part of the project's Solid graph: signals in attributes and text update the live DOM, and the drawn content follows on the next frame. A [`dapi mount`](../mount.md) stays live, so the graph keeps running and `useTicker` or timers can drive the markup:diff --git a/reference/jsx/lifecycle.md b/reference/jsx/lifecycle.mdindex 0edee56a..b3927397 100644--- a/reference/jsx/lifecycle.md+++ b/reference/jsx/lifecycle.md@@ -18,10 +18,10 @@ import { useTicker } from "@diffusionstudio/jsx";export default function Project() {const { time, frame } = useTicker();return (- <scene key="hud" width={1920} height={1080}>+ <rect scene="hud" width={1920} height={1080}><text width={600} height={100} fontSize={80}>{`frame ${frame()}`}</text><rect x={860 + Math.sin(time() * 4) * 200} y={490} width={100} height={100} fill="#f43" />- </scene>+ </rect>);}```diff --git a/reference/jsx/module.md b/reference/jsx/module.mdindex de9bf08b..2b2b0f0b 100644--- a/reference/jsx/module.md+++ b/reference/jsx/module.md@@ -5,9 +5,9 @@ The entry file is a standard Solid component module:```tsxexport default function Project() {return (- <scene key="intro" name="Intro" fill="black" width={1920} height={1080}>+ <rect scene="intro" name="Intro" fill="black" width={1920} height={1080}>{/* ... */}- </scene>+ </rect>);}```diff --git a/reference/jsx/paints.md b/reference/jsx/paints.mdindex 04db242c..8cf95ce8 100644--- a/reference/jsx/paints.md+++ b/reference/jsx/paints.md@@ -11,7 +11,7 @@ Internally a node's fill is not a property but a **paint child**: a sub-entity a</rect>```-Paint elements are valid inside any filled visual element (`<rect>`, `<scene>`, `<text>`, `<video>`, `<image>`); a `<group>` has no fill of its own, so it takes none. Multiple paints stack in document order; later paints render on top, and a paint child on a `<video>`/`<image>` draws over the media paint created by `src`.+Paint elements are valid inside any filled visual element (`<rect>`, `<text>`, `<video>`, `<image>`, and a scene root); a `<group>` has no fill of its own, so it takes none. Multiple paints stack in document order; later paints render on top, and a paint child on a `<video>`/`<image>` draws over the media paint created by `src`.| Element | Props | Meaning || ------- | ----- | ------- |diff --git a/reference/jsx/roots.md b/reference/jsx/roots.mdindex 580dd57f..9a3c6a08 100644--- a/reference/jsx/roots.md+++ b/reference/jsx/roots.md@@ -1,22 +1,22 @@# Roots-A mount renders one or more root elements (a fragment of roots is allowed) and **refreshes the document**: like reloading a webpage, re-running a mount rebuilds its roots in place instead of accumulating copies; a rendered root with no existing node to replace is created. Roots are typically [`<scene>`](./scene.md) elements, but any element can be a root (e.g. a bare `<rect>`). Every top-level element must declare its identity with a `key`:+A mount renders one or more root elements (a fragment of roots is allowed) and **refreshes the document**: like reloading a webpage, re-running a mount rebuilds its roots in place instead of accumulating copies; a rendered root with no existing node to replace is created. **Only a [scene](./scene.md) is mountable as a root** (a rectangle geometry promoted with the `scene` property); every top-level element declares its identity with `scene`.| Identity | Contract || -------- | -------- |-| `<scene key="intro">` | Rebuilds the existing node carrying the same key, or creates it (storing the key) if none does. Keyed nodes in the document that the render no longer produces are **deleted**; the mount owns its keyed roots. |+| `<rect scene="intro">` | Rebuilds the existing scene carrying the same identity, or creates it (storing it) if none does. Scenes in the document that the render no longer produces are **deleted**; the mount owns its roots. |-Keys must be unique within a render, and rebuilding keeps the node's entity id and canvas position. Nodes without a key (e.g. hand-made scratch scenes) are never touched. The **first** rendered root becomes the active scene. Assigning a `name` alongside the key (e.g. `<scene key="intro" name="Intro">`) is recommended: the key identifies the node across mounts, the name labels it in the editor.+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.-`<scene>` is valid **only** at the document root; scenes do not nest.+The `scene` property is valid **only** at the document root.-[`dapi node insert`](../node/insert.md) skips this reconciliation entirely: its roots take no `key` and every run inserts fresh entities.+[`dapi node insert`](../node/insert.md) skips this reconciliation entirely: its roots are inserted as children and every run inserts fresh entities.## Canvas placement-The canvas holds many roots, but a root's position on the canvas is an **editor concern, not part of the composition**: `<scene>` has no `x`/`y`, and a project describes content, not canvas arrangement.+The canvas holds many roots, but a root's position on the canvas is an **editor concern, not part of the composition**: a scene root has no `x`/`y`, and a project describes content, not canvas arrangement.-- **Rebuilt roots** (matched by `key`) keep their existing canvas position.+- **Rebuilt roots** (matched by `scene`) keep their existing canvas position.- **New roots** are placed automatically: in the nearest empty space around the current viewport center, gapped so they never overlap existing content (the same auto-placement the editor uses when generating onto the canvas). A mount that creates multiple roots places them side by side in render order.The camera is not moved; because placement anchors to the viewport center, new roots typically land in view. Use [`dapi selection focus`](../selection/focus.md) to frame them explicitly.diff --git a/reference/jsx/scene.md b/reference/jsx/scene.mdindex 4c9bc7ba..2a9fb502 100644--- a/reference/jsx/scene.md+++ b/reference/jsx/scene.md@@ -1,20 +1,36 @@-# `<scene>`+# Scenes (the `scene` property)-The composition root: clips its children to `width`×`height`. Valid **only** at the document top level; scenes do not nest. The first rendered root becomes the active scene (see [roots.md](./roots.md)).+A scene is the composition root: it clips its children to `width`×`height`. The **`scene` property promotes a rectangle geometry** (`<rect>`,`<html>`, `<surface>`) to a mount root. The property's value is the scene's identity across mounts. Scenes are valid **only** at the document top level and do not nest; the first rendered root becomes the active scene (see [roots.md](./roots.md)).```tsx-<scene key="intro" name="Intro" fill="black" width={1920} height={1080}>+// A plain scene: a rectangle promoted to the root.+<rect scene="intro" name="Intro" fill="black" width={1920} height={1080}>{/* children */}-</scene>+</rect>++// An HTML scene: the whole frame is one DOM tree laid out by the browser.+<html scene="landing" name="Landing" width={1920} height={1080}>+ <div style="width:100%;height:100%;display:flex;align-items:center;justify-content:center;">+ Hello+ </div>+</html>```-## Props+## The `scene` property++| Prop | Type | Meaning |+| ---- | ---- | ------- |+| `scene` | `string` | **Promotes** the element to a scene root and is its identity across mounts: re-mounting replaces the scene carrying the same value, or creates it (see [roots.md](./roots.md)). |++Alongside it a scene uses the ordinary geometry props:| Prop | Type | Default | Meaning || ---- | ---- | ------- | ------- |-| `key` | `string` | **required** | Identity across mounts; re-mounting replaces the scene carrying the same key (see [roots.md](./roots.md)). || `width`, `height` | `number` | **required** | Composition size in pixels. || `name` | `string` | none | Scene name (recommended). |-| `fill` | `string` | none | Background fill, any CSS color (alpha is ignored). |+| `fill` | `string` | none | Background fill, any CSS color (alpha is ignored). On `<rect>`/`<group>`; an `<html>` scene paints its own background in CSS. |++## Constraints-No timing or transform props. Canvas position is an editor concern; `<scene>` has no `x`/`y`.+- **Rectangle geometry only.** `scene` on a `<text>`, paint, or other non-rectangle element is an error.+- **No placement or timing.** A scene root is not positioned or timed by a parent, so `x`/`y`/`start`/`end`/`transition`/`animations` are rejected on it. Canvas position is an editor concern.diff --git a/reference/mount.md b/reference/mount.mdindex 1386591d..5de8afb8 100644--- a/reference/mount.md+++ b/reference/mount.md@@ -1,6 +1,6 @@# `dapi mount (<path> | --code <str>)`-Compiles a Solid JSX project module and executes it in the app, mounting the rendered roots into the document. Like reloading a webpage, re-mounting rebuilds the roots in place instead of adding copies: every top-level element declares its identity in the JSX with a `key`, and `<scene key="intro">` replaces the node carrying that key (or creates it).+Compiles a Solid JSX project module and executes it in the app, mounting the rendered roots into the document. Like reloading a webpage, re-mounting rebuilds the roots in place instead of adding copies: only a scene is mountable as a root, declaring its identity in the JSX with `scene`, and `<rect scene="intro">` replaces the scene carrying that identity (or creates it).The full JSX code syntax lives in [jsx/](./jsx/README.md); start with the [pipeline](./jsx/README.md#pipeline) and [roots](./jsx/roots.md).diff --git a/reference/node/insert.md b/reference/node/insert.mdindex ed79e398..bff0319d 100644--- a/reference/node/insert.md+++ b/reference/node/insert.md@@ -4,7 +4,7 @@ Compiles an inline JSX fragment and inserts its rendered roots as children of anThe payload is **bare JSX tags** — no `export default`, no file path. Unlike `mount`, an insert renders once and is then discarded: it is never persisted, restored, or kept live, so a component that relies on reactivity (signals, effects, `useTicker`) has nothing to drive it. Reach for [`mount`](../mount.md) when you want a live, reproducible program. The full JSX syntax lives in [jsx/](../jsx/README.md).-The rendered roots must be valid as children of the target parent, following the JSX containment rules: a node parent takes any element or paint root except `<scene>` (scenes only exist at the document top level) and `<colorStop>`; a gradient paint parent takes only `<colorStop>` roots. That is how a stop is added to an existing gradient (`node insert <paintId> '<colorStop offset={0.5} color="#FF0055" />'`); other sub-entities take no children.+The rendered roots must be valid as children of the target parent, following the JSX containment rules: a node parent takes any element or paint root except a scene (an element carrying `scene`, which exists only at the document top level) and `<colorStop>`; a gradient paint parent takes only `<colorStop>` roots. That is how a stop is added to an existing gradient (`node insert <paintId> '<colorStop offset={0.5} color="#FF0055" />'`); other sub-entities take no children.## Input@@ -18,4 +18,4 @@ None.## Errors-Exits non-zero if `<code>` is not a bare JSX fragment (contains `export default`, or has no tags), if `<parentId>` doesn't resolve to a live entity, if compilation or evaluation fails, if a rendered root is invalid as a child of the parent (e.g. a `<scene>`, or a non-`<colorStop>` in a gradient paint), or if `--index` is given for a paint or color stop root. On any of these, **nothing is inserted**.+Exits non-zero if `<code>` is not a bare JSX fragment (contains `export default`, or has no tags), if `<parentId>` doesn't resolve to a live entity, if compilation or evaluation fails, if a rendered root is invalid as a child of the parent (e.g. a scene carrying `scene`, or a non-`<colorStop>` in a gradient paint), or if `--index` is given for a paint or color stop root. On any of these, **nothing is inserted**.