The VS Code of video editing, built for agents.
TypeScript
Refactor example files to use <stage> and <scene> components
konstantin-paulus11fecc09ea57
diff --git a/examples/01-basics.tsx b/examples/01-basics.tsxindex 2ab35ed5..43668f87 100644--- a/examples/01-basics.tsx+++ b/examples/01-basics.tsx@@ -2,10 +2,12 @@/* The everyday composition: sequenced A-roll, an image overlay, data-driven* titles via <For>, and a music bed under everything.*- * dapi mount examples/01-basics.tsx+ * cp examples/01-basics.tsx ~/Projects/basics/index.tsx+ * dapi open ~/Projects/basics** Sources are remote URLs so the example mounts anywhere; `src` equally takes- * local paths ("/Movies/clip.mp4") and asset ids (see `dapi asset ls`).+ * local paths ("/Movies/clip.mp4"), library paths ("b-roll/drone.mp4") and+ * asset ids.* A <sequence> does not place its children: each clip gets an explicit* `start`, the next clip starts where the previous one ends, and the* dissolve declared on the outgoing clip is centered on that cut.@@ -30,52 +32,53 @@ function Title(props: { text: string; start: Time; end: Time }) {height={1080}textAlign="center"textBaseline="middle"+ color="#FFFFFF"fontFamily="Inter"fontSize={120}fontWeight="bold"start={props.start}end={props.end}- animations={[- { type: "fade", duration: 0.5 },- { type: "fade", phase: "out", duration: 0.5 },- ]}>{props.text}+ <animation type="fade" duration={0.5} />+ <animation type="fade" phase="out" duration={0.5} /></text>);}export default function Basics() {return (- <rect scene="example-basics" name="Basics" width={1920} height={1080} fill="black">- <sequence name="A-roll">- <video- src={`${VIDEOS}/sintel-short.mp4`}- start={0}- end={6}- sourceIn={10}- volume={-6}- transition={{ type: "dissolve" }}- height={1080}- width={1920}- />- <video- src={`${VIDEOS}/tears-of-steel-battle-clip-medium.mp4`}- start={6}- end={12}- sourceIn={2}- volume={-6}- height={1080}- width={1920}- />- </sequence>+ <stage>+ <scene name="Basics" width={1920} height={1080} fill="black">+ <sequence name="A-roll">+ <video+ src={`${VIDEOS}/sintel-short.mp4`}+ start={0}+ end={6}+ sourceIn={10}+ volume={-6}+ transition={{ type: "dissolve" }}+ height={1080}+ width={1920}+ />+ <video+ src={`${VIDEOS}/tears-of-steel-battle-clip-medium.mp4`}+ start={6}+ end={12}+ sourceIn={2}+ volume={-6}+ height={1080}+ width={1920}+ />+ </sequence>- {/* picture-in-picture overlay; media covers its box by default */}- <image src={STILL} x={1400} y={64} width={440} height={248} cornerRadius={24} start={0} end={12} />+ {/* picture-in-picture overlay; media covers its box by default */}+ <image src={STILL} x={1400} y={64} width={440} height={248} cornerRadius={24} start={0} end={12} />- <For each={TITLES}>{(t) => <Title {...t} />}</For>+ <For each={TITLES}>{(t) => <Title {...t} />}</For>- <audio name="Music bed" src={MUSIC} start={0} end={12} volume={-16} />- </rect>+ <audio name="Music bed" src={MUSIC} start={0} end={12} volume={-16} />+ </scene>+ </stage>);}diff --git a/examples/02-genai.tsx b/examples/02-genai.tsxindex 27a6b0c6..dd403587 100644--- a/examples/02-genai.tsx+++ b/examples/02-genai.tsx@@ -2,7 +2,8 @@/* Multi-stage generation: text-to-image keyframes, image-to-video motion,* a text-to-speech voiceover, generated ambience, and captions on top.*- * dapi mount examples/02-genai.tsx+ * cp examples/02-genai.tsx ~/Projects/genai/index.tsx+ * dapi open ~/Projects/genai** `generate.*` declarations are pure values; nothing generates until commit.* Refs form a dependency graph (keyframe -> matching second keyframe -> two@@ -56,16 +57,18 @@ const ambience = generate.audio({export default function GenAi() {return (- <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} />- </sequence>+ <stage>+ <scene 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} />+ </sequence>- <audio name="Voiceover" src={voiceover} start={1} />- <audio name="Ambience" src={ambience} start={0} end={10} volume={-18} />+ <audio name="Voiceover" src={voiceover} start={1} />+ <audio name="Ambience" src={ambience} start={0} end={10} volume={-18} />- <captions preset="spotlight" verticalAlign="bottom" />- </rect>+ <captions preset="spotlight" verticalAlign="bottom" />+ </scene>+ </stage>);}diff --git a/examples/03-ticker.tsx b/examples/03-ticker.tsxindex 4a652739..059be215 100644--- a/examples/03-ticker.tsx+++ b/examples/03-ticker.tsx@@ -2,7 +2,8 @@/* Declarative animation: useTicker exposes the playhead as reactive* accessors, createMemo derives values from it, and props consume the memos.*- * dapi mount examples/03-ticker.tsx+ * cp examples/03-ticker.tsx ~/Projects/ticker/index.tsx+ * dapi open ~/Projects/ticker** No timers, no imperative draw loop: each memo recomputes once per tick and* every consumer below reads the cached value. Press play; scrubbing works@@ -25,42 +26,44 @@ export default function Ticker() {const eased = createMemo(() => 0.5 - Math.cos(angle()) / 2); // 0..1..0, smoothreturn (- <rect scene="example-ticker" name="Ticker" width={1920} height={1080} fill="#101014">- {/* center square: rotation and corner radius both derive from progress */}- <rect- x={860}- y={440}- width={200}- height={200}- rotation={progress() * 360}- cornerRadius={16 + eased() * 84}- fill={`hsl(${hue()} 90% 60%)`}- />+ <stage>+ <scene name="Ticker" width={1920} height={1080} fill="#101014">+ {/* center square: rotation and corner radius both derive from progress */}+ <rect+ x={860}+ y={440}+ width={200}+ height={200}+ rotation={progress() * 360}+ cornerRadius={16 + eased() * 84}+ fill={`hsl(${hue()} 90% 60%)`}+ />- {/* orbiting dot */}- <rect- x={910 + Math.cos(angle()) * 420}- y={490 + Math.sin(angle()) * 300}- width={100}- height={100}- cornerRadius={50}- fill={`hsl(${(hue() + 120) % 360} 90% 65%)`}- />+ {/* orbiting dot */}+ <rect+ x={910 + Math.cos(angle()) * 420}+ y={490 + Math.sin(angle()) * 300}+ width={100}+ height={100}+ cornerRadius={50}+ fill={`hsl(${(hue() + 120) % 360} 90% 65%)`}+ />- {/* loop progress bar */}- <rect x={80} y={980} width={1760} height={12} cornerRadius={6} fill="#ffffff" opacity={0.12} />- <rect- x={80}- y={980}- width={Math.max(progress() * 1760, 12)}- height={12}- cornerRadius={6}- fill={`hsl(${hue()} 90% 60%)`}- />+ {/* loop progress bar */}+ <rect x={80} y={980} width={1760} height={12} cornerRadius={6} fill="#ffffff" opacity={0.12} />+ <rect+ x={80}+ y={980}+ width={Math.max(progress() * 1760, 12)}+ height={12}+ cornerRadius={6}+ fill={`hsl(${hue()} 90% 60%)`}+ />- <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>- </rect>+ <text x={80} y={64} width={1200} height={60} fontSize={44} fontFamily="Inter" color="#FFFFFF">+ t = {time().toFixed(2)}s / frame {frame()} / loop {Math.round(progress() * 100)}%+ </text>+ </scene>+ </stage>);}diff --git a/examples/04-html-in-canvas.tsx b/examples/04-html-in-canvas.tsxindex 79cb301c..d50f2529 100644--- a/examples/04-html-in-canvas.tsx+++ b/examples/04-html-in-canvas.tsx@@ -1,7 +1,8 @@/* @jsxImportSource @diffusionstudio/jsx *//* An AI prompt box as real HTML, centered in the frame.*- * dapi mount examples/04-html-in-canvas.tsx+ * cp examples/04-html-in-canvas.tsx ~/Projects/html-in-canvas/index.tsx+ * dapi open ~/Projects/html-in-canvas** Requires Chromium's html-in-canvas API (chrome://flags/#canvas-draw-element);* without it the mount fails with an explicit error. The <html> children are@@ -24,42 +25,43 @@ export default function PromptBox() {const cursorOn = createMemo(() => Math.floor(time() * 2) % 2 === 0);return (- <rect scene="example-html" name="Prompt box" width={1920} height={1080} fill="#0b0d12">- <html- x={460}- y={400}- width={1000}- height={280}- animations={[{ type: "slideUp", duration: 0.6 }]}- end={8}- >- <div- style={`height:100%;box-sizing:border-box;display:flex;flex-direction:column;- justify-content:space-between;padding:28px 32px;border-radius:24px;- border:1px solid #ffffff22;background:linear-gradient(180deg,#171a22,#101218);- font-family:Inter;color:white;`}- >- <div style="font-size:15px;letter-spacing:2px;opacity:0.5;">ASK THE EDITOR</div>-- <div style="font-size:30px;line-height:1.4;min-height:84px;">- {typed()}- <span style={`opacity:${cursorOn() ? 0.9 : 0};color:#7c9cff;`}>▍</span>- </div>-- <div style="display:flex;align-items:center;gap:12px;">- <span style="padding:6px 14px;border-radius:999px;background:#ffffff14;font-size:14px;opacity:0.8;">- gen-video-pro- </span>- <span style="font-size:14px;opacity:0.4;">1080p / 30 fps</span>+ <stage>+ <scene name="Prompt box" width={1920} height={1080} fill="#0b0d12">+ {/* An <html> box takes DOM children only, so the animation — a+ composition element — goes on a rect carrying the same paint the+ <html> shorthand carries. */}+ <rect x={460} y={400} width={1000} height={280} end={8}>+ <animation type="slideUp" duration={0.6} />+ <htmlPaint><div- style={`margin-left:auto;width:48px;height:48px;border-radius:50%;background:#7c9cff;- display:flex;align-items:center;justify-content:center;font-size:24px;color:#0b0d12;`}+ style={`height:100%;box-sizing:border-box;display:flex;flex-direction:column;+ justify-content:space-between;padding:28px 32px;border-radius:24px;+ border:1px solid #ffffff22;background:linear-gradient(180deg,#171a22,#101218);+ font-family:Inter;color:white;`}>- ↑+ <div style="font-size:15px;letter-spacing:2px;opacity:0.5;">ASK THE EDITOR</div>++ <div style="font-size:30px;line-height:1.4;min-height:84px;">+ {typed()}+ <span style={`opacity:${cursorOn() ? 0.9 : 0};color:#7c9cff;`}>▍</span>+ </div>++ <div style="display:flex;align-items:center;gap:12px;">+ <span style="padding:6px 14px;border-radius:999px;background:#ffffff14;font-size:14px;opacity:0.8;">+ gen-video-pro+ </span>+ <span style="font-size:14px;opacity:0.4;">1080p / 30 fps</span>+ <div+ style={`margin-left:auto;width:48px;height:48px;border-radius:50%;background:#7c9cff;+ display:flex;align-items:center;justify-content:center;font-size:24px;color:#0b0d12;`}+ >+ ↑+ </div>+ </div></div>- </div>- </div>- </html>- </rect>+ </htmlPaint>+ </rect>+ </scene>+ </stage>);}diff --git a/examples/05-anime-timeline.tsx b/examples/05-anime-timeline.tsxindex 404b6871..c66e4a7c 100644--- a/examples/05-anime-timeline.tsx+++ b/examples/05-anime-timeline.tsx@@ -1,7 +1,8 @@/* @jsxImportSource @diffusionstudio/jsx *//* Anime.js timeline scrubbed by the playhead: one clock, two render worlds.*- * dapi mount examples/05-anime-timeline.tsx+ * cp examples/05-anime-timeline.tsx ~/Projects/anime-timeline/index.tsx+ * dapi open ~/Projects/anime-timeline** Needs the html-in-canvas API (see 04-html-in-canvas.tsx). A paused anime.js* timeline tweens plain-object targets; a createEffect seeks it to the@@ -40,50 +41,52 @@ export default function AnimeTimeline() {const hue = () => Math.round(v.card.hue);return (- <rect scene="example-anime" name="Anime timeline" width={960} height={540} fill="#101014">- <rect- x={v.chip.x}- y={v.chip.y}- width={160}- height={160}- rotation={v.chip.rotation}- cornerRadius={v.chip.cornerRadius}- opacity={v.chip.opacity}- fill={`hsl(${hue()} 90% 60%)`}- end={3.25}- />+ <stage>+ <scene name="Anime timeline" width={960} height={540} fill="#101014">+ <rect+ x={v.chip.x}+ y={v.chip.y}+ width={160}+ height={160}+ rotation={v.chip.rotation}+ cornerRadius={v.chip.cornerRadius}+ opacity={v.chip.opacity}+ fill={`hsl(${hue()} 90% 60%)`}+ end={3.25}+ />- <html x={380} y={120} width={500} height={300} end={3.25}>- <div- style={{- "font-family": "Inter",- color: "white",- padding: "28px 32px",- transform: `translateY(${v.card.rise}px)`,- opacity: v.card.opacity,- }}- >- <div style={{ "font-size": "34px", "font-weight": "700", color: `hsl(${hue()} 90% 65%)` }}>- DOM, meet timeline+ <html x={380} y={120} width={500} height={300} end={3.25}>+ <div+ style={{+ "font-family": "Inter",+ color: "white",+ padding: "28px 32px",+ transform: `translateY(${v.card.rise}px)`,+ opacity: v.card.opacity,+ }}+ >+ <div style={{ "font-size": "34px", "font-weight": "700", color: `hsl(${hue()} 90% 65%)` }}>+ DOM, meet timeline+ </div>+ <div style={{ "font-size": "18px", opacity: 0.7, margin: "6px 0 24px" }}>+ anime.js seeked from the playhead at t = {time().toFixed(2)}s+ </div>+ <div style={{ height: "14px", "border-radius": "7px", background: "#ffffff22" }}>+ <div+ style={{+ width: `${v.card.progress}%`,+ height: "100%",+ "border-radius": "7px",+ background: `linear-gradient(90deg, hsl(${hue() - 40} 90% 55%), hsl(${hue()} 90% 65%))`,+ }}+ />+ </div>+ <div style={{ "font-size": "16px", opacity: 0.6, "margin-top": "10px" }}>+ {Math.round(v.card.progress)}% through the loop+ </div></div>- <div style={{ "font-size": "18px", opacity: 0.7, margin: "6px 0 24px" }}>- anime.js seeked from the playhead at t = {time().toFixed(2)}s- </div>- <div style={{ height: "14px", "border-radius": "7px", background: "#ffffff22" }}>- <div- style={{- width: `${v.card.progress}%`,- height: "100%",- "border-radius": "7px",- background: `linear-gradient(90deg, hsl(${hue() - 40} 90% 55%), hsl(${hue()} 90% 65%))`,- }}- />- </div>- <div style={{ "font-size": "16px", opacity: 0.6, "margin-top": "10px" }}>- {Math.round(v.card.progress)}% through the loop- </div>- </div>- </html>- </rect>+ </html>+ </scene>+ </stage>);}diff --git a/examples/06-three.tsx b/examples/06-three.tsxindex 4d1b54a5..c5c43bc9 100644--- a/examples/06-three.tsx+++ b/examples/06-three.tsx@@ -1,9 +1,11 @@/* @jsxImportSource @diffusionstudio/jsx *//* Three.js owning a <surface>: a glTF helmet spun by the playhead.*- * dapi mount examples/06-three.tsx+ * cp examples/06-three.tsx ~/Projects/three/index.tsx+ * dapi open ~/Projects/three*- * The <surface> ref hands three.js a detached HTMLCanvasElement to render into;+ * `ref={surfaceRef}` assigns the surface's node, whose `element` is its+ * detached canvas; onMount three.js takes it over and renders into it;* the engine samples that bitmap into the node's box every frame, so a WebGL* scene composites like any other paint (needs preserveDrawingBuffer so the* per-frame readback doesn't come back blank). One clock drives everything:@@ -16,8 +18,9 @@* without shipping an HDR.*/-import { createEffect, createSignal, onCleanup } from "solid-js";+import { createEffect, createSignal, onCleanup, onMount } from "solid-js";import { useTicker } from "@diffusionstudio/jsx";+import type { SceneNode } from "@diffusionstudio/jsx";import * as THREE from "three";import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";import { RoomEnvironment } from "three/examples/jsm/environments/RoomEnvironment.js";@@ -31,7 +34,11 @@ export default function ThreeHelmet() {const { time } = useTicker();const [loaded, setLoaded] = createSignal(false);- const setup = (el: HTMLCanvasElement) => {+ let surfaceRef: SceneNode | undefined;++ onMount(() => {+ const el = surfaceRef!.element;+ if (!el) return;const renderer = new THREE.WebGLRenderer({canvas: el,antialias: true,@@ -93,11 +100,13 @@ export default function ThreeHelmet() {pmrem.dispose();renderer.dispose();});- };+ });return (- <rect scene="example-three" name="Three helmet" width={960} height={540} fill="#0b0d12">- <surface x={0} y={0} width={960} height={540} ref={setup} />- </rect>+ <stage>+ <scene name="Three helmet" width={960} height={540} fill="#0b0d12">+ <surface x={0} y={0} width={960} height={540} ref={surfaceRef} />+ </scene>+ </stage>);}diff --git a/examples/07-webgpu.tsx b/examples/07-webgpu.tsxindex a6150a41..d39efdb8 100644--- a/examples/07-webgpu.tsx+++ b/examples/07-webgpu.tsx@@ -1,19 +1,23 @@/* @jsxImportSource @diffusionstudio/jsx *//* WebGPU owning a <surface>: a triangle whose colors cycle with the playhead.*- * dapi mount examples/07-webgpu.tsx+ * cp examples/07-webgpu.tsx ~/Projects/webgpu/index.tsx+ * dapi open ~/Projects/webgpu*- * The <surface> ref hands a detached canvas to a WebGPU context; the engine+ * `ref={surfaceRef}` assigns the surface's node, whose `element` is its+ * detached canvas; onMount a WebGPU context takes it over, and the engine* samples the bitmap into the node's box every frame. Device setup is async,- * so the ref creates the draw effect synchronously and a signal wakes it once- * the pipeline exists. Composition time feeds a uniform and the fragment+ * so the draw effect is created synchronously in the component body and a+ * signal wakes it once the pipeline exists. Composition time feeds a uniform+ * and the fragment* shader derives the colors from it (a phase-shifted cosine palette), so the* playhead is the only clock: scrubbing and exports stay frame-accurate.* Fails with a console error where WebGPU is unavailable.*/-import { createEffect, createSignal, onCleanup } from "solid-js";+import { createEffect, createSignal, onCleanup, onMount } from "solid-js";import { useTicker } from "@diffusionstudio/jsx";+import type { SceneNode } from "@diffusionstudio/jsx";const SHADER = /* wgsl */ `@group(0) @binding(0) var<uniform> time: f32;@@ -53,7 +57,12 @@ export default function WebgpuTriangle() {const { time } = useTicker();const [gpu, setGpu] = createSignal<Gpu>();- const setup = async (el: HTMLCanvasElement) => {+ let surfaceRef: SceneNode | undefined;++ onMount(async () => {+ const el = surfaceRef!.element;+ if (!el) return;+const adapter = await navigator.gpu?.requestAdapter();if (!adapter) throw new Error("WebGPU is not available");const device = await adapter.requestDevice();@@ -80,7 +89,7 @@ export default function WebgpuTriangle() {});setGpu({ device, context, pipeline, uniforms, bindGroup });- };+ });createEffect(() => {const g = gpu();@@ -110,8 +119,10 @@ export default function WebgpuTriangle() {onCleanup(() => gpu()?.device.destroy());return (- <rect scene="example-webgpu" name="WebGPU triangle" width={960} height={540} fill="#0b0d12">- <surface x={0} y={0} width={960} height={540} ref={setup} />- </rect>+ <stage>+ <scene name="WebGPU triangle" width={960} height={540} fill="#0b0d12">+ <surface x={0} y={0} width={960} height={540} ref={surfaceRef} />+ </scene>+ </stage>);}diff --git a/examples/08-shader-paint.tsx b/examples/08-shader-paint.tsxindex 5234afb3..2ec976c3 100644--- a/examples/08-shader-paint.tsx+++ b/examples/08-shader-paint.tsx@@ -2,16 +2,16 @@/* A shader paint post-processing a video: chromatic aberration pulsing with* the playhead plus a vignette, driven by two uniforms.*- * dapi mount examples/08-shader-paint.tsx+ * cp examples/08-shader-paint.tsx ~/Projects/shader-paint/index.tsx+ * dapi open ~/Projects/shader-paint** <shaderPaint> applies its WGSL to the media paint directly below it in the* paint stack (here: the paint created by the video's `src`). The engine* provides `sampleSource(uv)` (box-space sampling that honors objectFit),* `globals.time` (the clip's local time in seconds, playhead-driven, so* scrubbing and exports stay frame-accurate), and binds the `uniforms` prop- * to the shader's @group(1) declarations by name. Patch them live:- *- * dapi node patch '[{ "id": <paintId>, "uniforms": { "strength": 3, "vignette": 0.8 } }]'+ * to the shader's @group(1) declarations by name. Drive a uniform from a+ * signal and it is a hot update; edit the file and the project remounts.*/const VIDEOS = "https://mdn.github.io/shared-assets/videos";@@ -37,10 +37,12 @@ const ABERRATION = /* wgsl */ `export default function ShaderPaintExample() {return (- <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>- </rect>+ <stage>+ <scene 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>+ </stage>);}diff --git a/examples/README.md b/examples/README.mdindex 9a2a98f6..47f47c78 100644--- a/examples/README.md+++ b/examples/README.md@@ -1,14 +1,21 @@# ExamplesSelf-contained compositions demonstrating the JSX API (see [reference/jsx](../reference/jsx/README.md)).-Each root carries a stable `scene` identity, so re-mounting an example replaces its scene in place.+Each one is a whole project entry file: it default-exports a component rendering a+`<stage>` with one `<scene>` in it. To run one, copy it into a project folder as the+entry and open that folder:++```sh+cp examples/01-basics.tsx ~/Projects/basics/index.tsx+dapi open ~/Projects/basics+```| Example | Shows || --- | --- |-| [01-basics.tsx](01-basics.tsx) | the `scene` prop promoting a root, `<sequence>` with a dissolve, `<video>`, `<audio>`, `<image>`, `<text>` titles from data via `<For>` |+| [01-basics.tsx](01-basics.tsx) | `<stage>` / `<scene>`, `<sequence>` with a dissolve, `<video>`, `<audio>`, `<image>`, `<text>` titles from data via `<For>`, `<animation>` children || [02-genai.tsx](02-genai.tsx) | multi-stage generation: `generate.image` refs feeding `generate.video`, TTS voiceover, generated ambience, `<captions>` || [03-ticker.tsx](03-ticker.tsx) | declarative animation: `useTicker` + `createMemo` derived values driving props |-| [04-html-in-canvas.tsx](04-html-in-canvas.tsx) | `<html>`: an AI prompt box as real DOM, typed out from the playhead |+| [04-html-in-canvas.tsx](04-html-in-canvas.tsx) | `<htmlPaint>`: an AI prompt box as real DOM, typed out from the playhead || [05-anime-timeline.tsx](05-anime-timeline.tsx) | anime.js timeline seeked from `useTicker`, driving an ECS node and `<html>` content in lockstep || [06-three.tsx](06-three.tsx) | three.js WebGL renderer owning a `<surface>`, glTF model loaded over the network || [07-webgpu.tsx](07-webgpu.tsx) | raw WebGPU on a `<surface>`: a triangle whose colors cycle with composition time |@@ -17,4 +24,5 @@ Each root carries a stable `scene` identity, so re-mounting an example replacesRequirements: `02-genai.tsx` consumes generation credits (results are cached per session);`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`).+Typecheck with `tsc -p examples --noEmit` (part of `npm run check`). `06-three.tsx`+needs `three` installed to typecheck; it is not a dependency of this repo.diff --git a/package-lock.json b/package-lock.jsonindex 8f643ed3..bc90e0d9 100644--- a/package-lock.json+++ b/package-lock.json@@ -12426,6 +12426,9 @@"name": "@diffusionstudio/jsx","version": "0.1.0","license": "MPL-2.0",+ "dependencies": {+ "koota": "^0.6.6"+ },"devDependencies": {"typescript": "~5.9.3"},diff --git a/packages/jsx/README.md b/packages/jsx/README.mdindex b3fd4c4a..c1ca5a29 100644--- a/packages/jsx/README.md+++ b/packages/jsx/README.md@@ -2,22 +2,14 @@The editor supplies the runtime when a project is mounted, so this package isneeded for **types and tooling** — IntelliSense and `tsc --noEmit`. It carries-no renderer: `useTicker` and `useFile` are declarations that throw outside a-mount, and elements only become a composition once the editor renders them.+no renderer: `useTicker` is a declaration that throws outside a mount, and+elements only become a composition once the editor renders them. The pure+helpers (`generate.*`, `parseTime`, the source-stamp constants) are real here;+everything else is a type.-```sh-npm install --save-dev @diffusionstudio/jsx solid-js-```+See [reference/jsx](https://github.com/diffusionstudio/editor/blob/main/reference/jsx/README.md)+for the authoring surface itself.-```jsonc-// tsconfig.json-{- "compilerOptions": {- "jsx": "preserve",- "jsxImportSource": "@diffusionstudio/jsx"- }-}-```## Licensediff --git a/packages/jsx/package.json b/packages/jsx/package.jsonindex 026b6fdf..99d815b5 100644--- a/packages/jsx/package.json+++ b/packages/jsx/package.json@@ -30,6 +30,9 @@"generative-ai","video-editing"],+ "dependencies": {+ "koota": "^0.6.6"+ },"peerDependencies": {"solid-js": "^1.9.0"},diff --git a/packages/jsx/src/index.ts b/packages/jsx/src/index.tsindex f1f68f20..d724a5df 100644--- a/packages/jsx/src/index.ts+++ b/packages/jsx/src/index.ts@@ -69,6 +69,7 @@ export type {KeyframeTrackProps,MediaPaintProps,RectProps,+ SceneNode,SceneProps,SequenceProps,ShaderPaintProps,@@ -79,7 +80,6 @@ export type {StrokeCap,StrokeJoin,StrokeProps,- SurfaceHandle,SurfacePaintProps,SurfaceProps,TextCase,diff --git a/packages/jsx/src/types.ts b/packages/jsx/src/types.tsindex 78e95507..06b40c0f 100644--- a/packages/jsx/src/types.ts+++ b/packages/jsx/src/types.ts@@ -3,6 +3,7 @@* file, You can obtain one at http://mozilla.org/MPL/2.0/. */import type { JSX as SolidJSX } from "solid-js";+import type { Entity } from "koota";import type { AssetRef } from "./generate";/**@@ -390,12 +391,15 @@ type TrackChildren = {};/**- * What every composition element accepts on top of its own props. Read by the- * compile step and never seen by a host: an id is not a property of the- * composition, it is how the source addresses the element.+ * What every composition element accepts on top of its own props: the props+ * that address or wire the element rather than describe it. `id` is read by+ * the compile step and never seen by a host — it is how the source addresses+ * the element.*/export type SourceProps = {id?: string;+ /** Callback or variable ref, SolidJS-style; receives the element's `SceneNode` when it is created. */+ ref?: SceneNode | ((node: SceneNode) => void);};/**@@ -682,24 +686,44 @@ export type ShaderPaintProps = PaintProps & {};/**- * What a `<surface>` / `<surfacePaint>` ref receives: the element's node, as- * every ref does, with the paint's backing canvas on it. Draw to `canvas` with- * any context type (2d, webgl, webgpu); the engine samples the bitmap every- * frame and stretches it into the holder's box. The canvas is allocated with- * the element and sized to the holder's `width`/`height` (a same-size set is a- * no-op, so `renderer.setSize` from your own code is not clobbered); null- * where the host has no DOM. Both ref forms work: `ref={(s) => ...}` and- * `let s: SurfaceHandle; <surface ref={s} />`.+ * One element of the mounted document, and its place in it: what an element's+ * `ref` receives, and the one object the document and the renderer both hold+ * for the entity, so `===` between two of them means what it says. Both ref+ * forms work, as in SolidJS: `ref={(node) => ...}` and+ * `let surfaceRef: SceneNode | undefined; <surface ref={surfaceRef} />`.+ *+ * `E` is what `element` holds. It defaults to the backing canvas — the main+ * consumer, a `<surface>` / `<surfacePaint>` ref — and the runtime document+ * instantiates it with the DOM node type it manages.*/-export type SurfaceHandle = { readonly canvas: HostCanvas | null };+export interface SceneNode<E = HostCanvas> {+ /** The Koota entity the element rendered into; `entity.get`/`set` reach the runtime traits. */+ readonly entity: Entity;+ /** Native composition elements participate in the Koota scene graph. */+ readonly native: boolean;+ /** The camelCase tag the element was authored as. */+ tag: string;+ props: Record<string, unknown>;+ parent: SceneNode<E> | null;+ children: SceneNode<E>[];+ /**+ * The real DOM node backing the element, null where there is none — typed+ * for the main consumer, a `<surface>` / `<surfacePaint>`'s backing canvas.+ * Draw to it with any context type (2d, webgl, webgpu); the engine samples+ * the bitmap every frame and stretches it into the holder's box. The canvas+ * is allocated with the element and sized to the holder's `width`/`height`+ * (a same-size set is a no-op, so `renderer.setSize` from your own code is+ * not clobbered). Purely-native elements (rects, text, scenes) carry no DOM+ * node, and an `<html>` subtree's is really its root element.+ */+ readonly element: E | null;+}-export type SurfacePaintProps = PaintProps & {- /** Callback or variable ref; receives a `SurfaceHandle`. */- ref?: SurfaceHandle | ((surface: SurfaceHandle) => void);-};+/** `<surfacePaint>` — a canvas the element's `ref` draws into (`element` on the received node). Takes no children. */+export type SurfacePaintProps = PaintProps;-/** `<Surface>` — a rectangle carrying a `<SurfacePaint>` with the given ref. */-export type SurfaceProps = CommonProps & Pick<SurfacePaintProps, "ref">;+/** `<Surface>` — a rectangle carrying a `<SurfacePaint>`; its `ref`'s `element` is the canvas. */+export type SurfaceProps = CommonProps;/*** `<audio>` — a clip with a sound and no picture. It draws nothing inside adiff --git a/packages/reconciler/src/document.ts b/packages/reconciler/src/document.tsindex 181efdd5..f7622915 100644--- a/packages/reconciler/src/document.ts+++ b/packages/reconciler/src/document.ts@@ -14,17 +14,6 @@ import type { AnimatableProperty, AssetRef } from '@diffusionstudio/jsx';import type { Entity, World } from 'koota';import type { ProjectDocument } from './host';-/**- * The node a `<surface>` or `<surfacePaint>` element creates: what its `ref`- * receives, like any other element's ref receives its node. `canvas` is the- * backing canvas (on the geometry for a `<surface>`, whose surface is its- * intrinsic paint; on the paint sub-entity for a `<surfacePaint>`), allocated- * with the element and sized to the holder's box; null without a DOM.- */-export interface SurfaceNode extends SceneNode {- readonly canvas: HTMLCanvasElement | null;-}-/** Props that address or wire an element rather than describe it. */const UNAUTHORED_PROPS: ReadonlySet<string> = new Set([SOURCE_ATTR, LOOP_ATTR, 'children', 'ref']);@@ -85,14 +74,14 @@ export function isSceneNode(node: SceneNode | undefined): node is SceneNode {return typeof node === 'object' && node !== null && 'entity' in node;}-function isDomText(node: SceneNode | undefined): node is SceneNode & { readonly domNode: Text } {- return typeof Text !== 'undefined' && node?.domNode instanceof Text;+function isDomText(node: SceneNode | undefined): node is SceneNode & { readonly element: Text } {+ return typeof Text !== 'undefined' && node?.element instanceof Text;}/*** The text nodes among `node`'s children, in order; empty when it holds none.*/-function textParts(node: SceneNode): (SceneNode & { readonly domNode: Text })[] {+function textParts(node: SceneNode): (SceneNode & { readonly element: Text })[] {return node.children.filter(isDomText);}@@ -105,7 +94,7 @@ function syncChars(node: SceneNode): void {const { entity } = node;if (!entity.isAlive() || !isText(entity)) return;entity.add(Chars);- entity.set(Chars, { value: textParts(node).map((part) => part.domNode.data).join('') });+ entity.set(Chars, { value: textParts(node).map((part) => part.element.data).join('') });}/**@@ -367,7 +356,7 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {props: {},parent: null,children: [],- domNode: null,+ element: null,};root.add(Host);root.set(Host, this.stage);@@ -391,7 +380,7 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {props: {},parent: null,children: [],- domNode: null,+ element: null,};entity.add(Host);entity.set(Host, node);@@ -412,7 +401,7 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {if (tag === 'canvas') {throw new Error('<canvas> is not supported as HTML content; use <surface> for custom drawing');}- const domNode = SVGElements.has(tag)+ const element = SVGElements.has(tag)? document.createElementNS('http://www.w3.org/2000/svg', tag): document.createElement(tag);const entity = createEntity(this.world);@@ -423,7 +412,7 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {props: {},parent: null,children: [],- domNode,+ element,};entity.add(Host);entity.set(Host, node);@@ -432,7 +421,7 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {const name = tag.charAt(0).toLowerCase() + tag.slice(1);let entity: Entity;- let domNode: Element | null = null;+ let element: Element | null = null;switch (name) {case 'stage':@@ -557,7 +546,7 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {if (name === 'solidPaint') entity.add(Color);if (name === 'shaderPaint') entity.add(Shader);if (name === 'surfacePaint') {- domNode = document.createElement('canvas');+ element = document.createElement('canvas');}if (name === 'htmlPaint') {const root = document.createElement('div');@@ -569,7 +558,7 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {canvas.toggleAttribute('layoutsubtree', true);canvas.appendChild(root);- domNode = root;+ element = root;}break;}@@ -590,7 +579,7 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {canvas.toggleAttribute('layoutsubtree', true);canvas.appendChild(root);- domNode = root;+ element = root;resizeEntity(this.world, entity, { width: 100, height: 100 });break;}@@ -604,7 +593,7 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {entity.set(Position, { x: 0, y: 0 });entity.add(Paint);entity.set(Paint, { value: PaintType.SURFACE });- domNode = document.createElement('canvas');+ element = document.createElement('canvas');resizeEntity(this.world, entity, { width: 100, height: 100 });break;}@@ -672,17 +661,9 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {props: {},parent: null,children: [],- domNode,+ element,};- if (name === 'surface' || name === 'surfacePaint') {- Object.assign(node, {- get canvas() {- return node.domNode instanceof HTMLCanvasElement ? node.domNode : null;- },- });- }-entity.add(Host);entity.set(Host, node);return node;@@ -697,7 +678,7 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {props: {},parent: null,children: [],- domNode: document.createTextNode(text),+ element: document.createTextNode(text),};entity.add(Host);entity.set(Host, node);@@ -706,7 +687,7 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {public replaceText(node: SceneNode, text: string): void {if (!isDomText(node)) return;- node.domNode.data = text;+ node.element.data = text;const owner = node.parent;if (owner) syncChars(owner);}@@ -734,7 +715,7 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {}for (const [index, part] of parts.entries()) {- part.domNode.data = index === 0 ? text : '';+ part.element.data = index === 0 ? text : '';}syncChars(node);}@@ -742,8 +723,8 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {public setProperty(node: SceneNode, name: string, value: unknown): void {if (!isSceneNode(node)) return;- if (!node.native && node.domNode instanceof Element) {- setDomProperty(node.domNode, name, value);+ if (!node.native && node.element instanceof Element) {+ setDomProperty(node.element, name, value);}const { entity } = node;@@ -1473,7 +1454,7 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {}const candidate = (!parent.native || parent.tag === 'html' || parent.tag === 'htmlPaint')- ? parent.domNode+ ? parent.element: null;const domContainer = candidate instanceof Element ? candidate : null;@@ -1485,20 +1466,20 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {node.parent = parent;if (domContainer) {- const domAnchor = anchor?.domNode;+ const domAnchor = anchor?.element;domContainer.insertBefore(- node.domNode,+ node.element,domAnchor?.parentNode === domContainer ? domAnchor : null,);} else {- node.domNode.remove();+ node.element.remove();}syncChars(parent);return;}if (domContainer) {- if (node.native || !(node.domNode instanceof Element)) {+ if (node.native || !(node.element instanceof Element)) {throw new Error('A composition element cannot be HTML content.');}@@ -1508,8 +1489,8 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {else parent.children.splice(at, 0, node);node.parent = parent;- const domAnchor = anchor?.domNode;- domContainer.insertBefore(node.domNode, domAnchor?.parentNode === domContainer ? domAnchor : null);+ const domAnchor = anchor?.element;+ domContainer.insertBefore(node.element, domAnchor?.parentNode === domContainer ? domAnchor : null);return;}@@ -1563,7 +1544,7 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {}node.children.length = 0;node.parent = null;- node.domNode?.remove();+ node.element?.remove();if (node.entity.isAlive() && node.entity !== this.stage.entity) {attempt(() => node.entity.destroy());@@ -1609,12 +1590,12 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {public dispose(): void {for (const entity of this.world.entities) {if (!entity.isAlive() || entity.has(IsExcluded) || entity === this.stage.entity) continue;- const domNode = entity.get(Host)?.domNode;+ const element = entity.get(Host)?.element;- if (domNode instanceof HTMLImageElement) {- attempt(() => URL.revokeObjectURL(domNode.src));+ if (element instanceof HTMLImageElement) {+ attempt(() => URL.revokeObjectURL(element.src));}- attempt(() => domNode?.remove());+ attempt(() => element?.remove());attempt(() => entity.destroy());}diff --git a/packages/reconciler/src/elements.ts b/packages/reconciler/src/elements.tsindex 64c59458..76d0af9b 100644--- a/packages/reconciler/src/elements.ts+++ b/packages/reconciler/src/elements.ts@@ -50,9 +50,9 @@ import type {/*** A component wrapping one host element: creates the node, routes `ref`- * through the renderer's `use` (so hosts with `applyRef` hand the callback- * the backing object, e.g. a surface's canvas), and spreads the remaining- * props and children reactively.+ * through the renderer's `use` (so the callback receives the node — or, for+ * hosts with `applyRef`, whatever backing object they hand it), and spreads+ * the remaining props and children reactively.*/function hostElement<P extends object>(tag: string): (props: P) => SolidJSX.Element {return (props) => {diff --git a/packages/reconciler/src/renderer.ts b/packages/reconciler/src/renderer.tsindex ea7f291c..a332e786 100644--- a/packages/reconciler/src/renderer.ts+++ b/packages/reconciler/src/renderer.ts@@ -74,8 +74,8 @@ export const {/*** Ref application (compiled `ref={fn}`). Hosts that materialize elements* lazily route refs through `applyRef` so the callback receives the backing- * object (e.g. a canvas paint's canvas) once it exists; hosts without- * `applyRef` keep the renderer's immediate call with the host node.+ * object once it exists; hosts without `applyRef` keep the renderer's+ * immediate call with the host node.*/export function use(fn: (target: unknown, arg?: unknown) => void, node: unknown, arg?: unknown): unknown {const document = doc();diff --git a/packages/runtime/MIGRATION.md b/packages/runtime/MIGRATION.mddeleted file mode 100644index c9955578..00000000--- a/packages/runtime/MIGRATION.md+++ /dev/null@@ -1,163 +0,0 @@-# bitecs → koota migration status--Working doc for moving the editor engine from bitecs (`apps/web/src/components/engine/`) into this headless runtime package, and for tracking how far `apps/web` has gotten consuming it. Kept short on purpose: the code carries the "how", this carries what a fresh session cannot read off it.--## Ground rules--- `@diffusionstudio/runtime` holds everything that runs without a DOM and without solid-js (the CLI/node capture path consumes it). Browser-only systems (input, keyboard, camera, HUD, dom sync, timeline UI), persistence, history and Solid reactivity stay in `apps/web`; Solid bindings live in `packages/koota-solid`.-- Persistence to IndexedDB is **not** required for now. `EntityRecord` (`src/world/serialize.ts`) is an in-memory snapshot format for copy/paste, duplicate and split-on-overlap only, free to change.-- Breaking API/type changes inside the codebase are fine.-- Comments: lean, only constraints the code can't show. No em dashes in prose. Tabs, MPL header on ported files.--## Runtime package--Fully ported. Layout: `src/traits/*` (~85 components split by concern), `src/world/` (create-world, `store`, serialize, observers), `src/queries/`, `src/systems/` (playback → motion → transform → render, sequenced by `runSystems`), `src/actions/`, `src/media/`, `src/math/`, `src/fonts/`, `src/utils/`. Encoders live in their own package, `@diffusionstudio/encoder`.--Call-outs that outlive the port:--- Use `store(world, trait)` (`src/world/store.ts`) in systems, never bare `getStore`: koota registers stores on first add/query, so `getStore` throws on a fresh world.-- Renames: the `ScaleMode` enum is `ScaleModeType` (the trait took the name); `Computed.delay` is `Computed.origin`; predicates lost the world param (`isScene(entity)`); `TimelineNode.eid` is `entity: Entity`; media handle traits carry a `Handle` suffix so trait and class can share an export surface.-- Nothing in the runtime may import the encoder (cycle). The encoder's tsconfig must mirror this one (`DOM.Iterable`, `@webgpu/types`, `@types/audioworklet`), since exports point at TS sources and consumers compile them.-- DOM access is lazy everywhere; nothing touches DOM at import time.-- Verification so far: `npx tsc --noEmit` in the package plus a throwaway `smoke-test.tmp.ts` run with `npm exec --yes tsx@latest`, deleted afterwards. No test infra in the package yet.--## Stage model--Every world spawns one `Stage` entity; all rendered entities descend from it. "Top-level" means "direct child of the stage", never "has no parent".--- `world.get(Root)` is it, `isStage()` tests it, `getParentNode()` returns null when the parent is the stage (use it wherever top-level matters), `getParentEntity()` returns the raw parent including the stage.-- `ChildOf` is `{ exclusive: true, autoDestroy: 'orphan' }`, so destroying the stage tears down the document; clearing a project is destroy + respawn.-- The stage id is per-session: `serializeEntity` omits `ChildOf` to the stage and `cloneFromRecords` attaches parentless records to the target world's stage. `appendChild` asserts top-level and relies on exclusive re-targeting; `removeChild` re-parents to the stage rather than dropping `ChildOf`.--## Authored time model--`Delay`/`Trim` became four one-value traits in the JSX's vocabulary, all frames: `Start`, `End` (parent-relative placement) and `SourceIn`, `SourceOut` (the slice of the node's own source that plays). One trait per value because a clip rarely says more than one of these, and absence is the usual answer.--- Defaults (`resolveDuration`): absent Start/SourceIn are 0; an absent bound means the whole source, or 16s (`DEFAULT_DURATION_FRAMES`) without one. Scenes and groups without an End fit their children.-- **Every bound caps, shortest wins**: nothing silently overrides anything, and caps are read at resolve time, so no value is rewritten behind the user's back (`clampTrimToAssetDuration` is gone: a shorter asset shortens the clip, swapping back restores the reach).-- `trimEntityIn/Out(world, entity, frame)` move an in/out point at a scene frame. `trimEntityIn` pins the implied End first so a head trim doesn't drag the tail; `trimEntityOut` writes SourceOut only when one is already authored.-- The five timing traits share one observer loop, propagating through the subtree. Removal passes the departing trait as `ignore`, because koota fires onRemove *before* clearing it.--## Decisions the code doesn't show--- **No history layer.** Actions write directly; the app groups undo steps by observing koota events. No `Deleted` tombstone either: `deleteEntity` is `entity.destroy()` and the subtree cascades. Entity ids are not stable across delete/undo, so key external refs by `Key`.-- **Keyframe auto-sync deliberately stayed out of observers**: koota change events don't say which field changed, so syncing every field would mint spurious keyframes. Editing surfaces call `syncKeyframeTrack` for the property they changed (`resizeEntity` already does for width/height).-- Actions are plain world-first functions, not koota `createActions`; the bound-record pattern only obscured that they call each other.-- Motion has no iteration order and no top-level exclusion, so keyframed scenes promoted to top level now play instead of silently freezing. Strip tracks in the promotion action if freezing is wanted.-- `TextStyle` defaults are all-undefined: a range override carries only its set fields (sparse slot = inherit). Node-level fallbacks (16px/Inter/400/leading 1) live in the text renderer's accessors.-- `HitRegions` entries are callback-less; the app's input system drains the list each frame and attaches handlers. Headless worlds push nothing, so it can't grow unbounded.-- The app's history layer must treat `Transition` onRemove during a tick as system-driven, not undoable.-- Still app-side from the old `api/observers.ts`: persistence scheduling, timeline index rebuilds, `syncInteractiveState`, Selected waveform show/hide, ClipHeight/Expanded, ExportSettings defaults, drag-origin traits.--## koota gotchas (0.6.6)--- **Local patch, do not lose:** `patches/koota+0.6.6.patch`, applied by the root `postinstall`. `Or(...)` was evaluated per 32-trait bitmask generation and required a match in every one, so Or queries created after the Or'd traits straddle a generation boundary silently returned empty. On a koota bump, retest (register 40 dummy traits, then create a fresh Or query) before dropping it.-- `Not(...)` takes plain traits only; relation pairs (`Not(ChildOf('*'))`) throw at runtime. Maintain a tag via observers if an indexed exclusion is needed.-- No hierarchy-ordered queries (no bitecs `Hierarchy(ChildOf)`). Transform does its own parent-first DFS, and that ordering is load-bearing there.-- Object/array trait fields need callback initializers (`colors: () => []`); AoS traits are `trait(() => instance)` and accept instances or null through plain `set`.-- Max 16 live worlds; `world.destroy()` in test loops and throwaway offline worlds. Stores are indexed by `entity.id()`; `world.id()` is a world slot, not an entity. World traits sit on a hidden internal entity that is not public API.-- `set` throws if the trait is missing and merges partials; `add` is idempotent and never resets values, hence add-then-set everywhere. On an exclusive relation, `add` re-targets in place.-- Events: exclusive re-target fires remove(old) then add(new); a redundant same-pair add fires nothing; **remove events fire while the departing child is still in the old target's queries** (hence the `exclude`/`ignore` params in `rebuildCaches` and the timing observers). onAdd fires after initial values are applied and may set traits. onChange fires even when the value is unchanged.-- **`destroy()` strips an entity's traits before it fires the ChildOf removal**, so a handler on that event cannot ask the departing child what it was. `rebuildCaches` files by trait and so filed nothing on the way out, leaving every destroyed entity in its parent's `Cache` lists (a deleted stroke kept its row, a deleted node kept its place in `children`); `evictFromCaches` drops it by identity instead. Anything else keyed on what a child *is* has the same hole.--## apps/web integration--Depends on `@diffusionstudio/runtime` + `@diffusionstudio/koota-solid`, migrating slice by slice. The bitecs engine in `apps/web/src/components/engine/` is still fully intact and untouched; both providers are mounted side by side in `pages/home.tsx`, keyed on `projectId`.--Done:--| Slice | Where |-|---|---|-| Engine shell (canvas mount/resize/DPR, AudioContext, tick + `frame` signal) | `engine/create-engine.ts`, `engine/context.tsx` |-| Projects on disk (desktop): folder with an `index.tsx` exporting `<stage>` | `apps/web/src/projects/`, `apps/desktop/src/projects.ts` |-| Editing commands, reported as source-vocabulary edits for write-back | `engine/editor.ts` (`DocumentEditor`, `useEditor()`) |-| Keyframes as edits (`writeKeyframe`/`toggleKeyframe`/`syncKeyframe`/`removeKeyframeTrack`) | `engine/keyframes.tsx`, `components/ui/keyframe.tsx` |-| Hooks | `engine/hooks/` (`useSelection`, `useAssetSelection`, `useDerived`, `useTool`, `useEditor`) plus koota-solid's `useTrait`/`useHas`/`useQuery`/`useWorld` |-| Draw tools + toolbar (armed tool is the `Tool` world trait) | `components/canvas/draw-overlay.tsx` |-| Input, HUD, camera, alignment | `engine/input/`, `engine/hud/`, `engine/align.ts` |-| Project config (per-scene export settings in package.json) | `engine/project-config.ts` |-| Panels: all of them (header, background, scene template, asset info, time, appearance, alignment, export, layout, text, strokes, shadows, effects, animations, transition, masks, audio, fills, transform, caption, interpolation) | `components/sidebar-right/inspector/` |-| Local font families (web fonts and loading are the runtime's) | `engine/fonts.ts` (`getLocalFonts`) |--Hosted JSX surface is `COMPOSITION_TAGS` (`packages/jsx/src/source.ts`): the structural tags, the media tags, `<captions>`, the paint family, `<stroke>`, `<shadow>`, `<effect>`, `<animation>`, `<keyframeTrack>`/`<keyframe>`, `<html>`/`<surface>`. `mask` is a `<rect>` prop, not a tag.--Conventions worth repeating when migrating the next panel:--- Reads of `Computed` (anything the systems write without events) go through `useDerived`, which samples once per engine tick; `useTrait`/`useHas` cannot follow them.-- Writes go through `editor.editProperty` in JSX vocabulary. `false` is the value the writer removes an attribute for, so a default is unset rather than written.-- `syncKeyframe` after a prop write keeps an existing track in step, since the motion system would otherwise overwrite the edit next tick. **Exception:** `width`/`height` sync *before* the write, because the document's handler is `resizeEntity`, which syncs the track itself and would mint an unsourced keyframe first. The canvas resize in `engine/input/interactions.ts` has the same gap, unfixed.-- State with no JSX spelling (`KeepAspectRatio`, `ClipsContent`, `Skew`) is written to the trait alone and does not survive a recompile. Giving any of them a prop is a separate decision; a lock snapshot would then have to come from the authored size, not from whatever `Size` holds at mount.-- `components/ui/keyframe-bitecs.tsx` has one importer left, the timeline's keyframe layer; it goes when that moves.-- A picker that previews on hover writes the trait alone, so while it is open the trait holds the hover and not the authored value. Keep the authored one in a signal seeded at mount (panels remount per selection) and move it only on a selection: it is what the control displays *and* what the close restores. Reading it back off the trait restores the hover instead, permanently. `AppearanceSettings`' blend mode and the text panel's family/weight both do this.-- What a `<text>` says is its children, not a prop, so it travels as its own edit end to end: `editor.editText` -> `TextEdit` -> the writer's `SourceSet.text` -> `RuntimeDocument.setText`. The document keeps the reconciler's text nodes: the first says all of it and the rest say nothing, so a project that later re-renders one of them still lands.-- A text is the one element whose box is optional (`Size` absent = sized to its glyphs), so the text panel's "Grow" toggle is `width`/`height` being authored at all. Unsetting a bound drops `Size` only once neither is left, which is why the toggle writes `width` before `height`.-- `Cache`'s lists are derived like `Computed` (store writes, no events), so a panel listing sub-entities reads them through `useDerived` too. Keep the empty fallback a module constant: a fresh `[]` per sample defeats the memo's comparison.-- Reordering siblings is a swap through `editor.reparent`, not an index write: `ItemIndex` is the document's to assign (`insertNode` renumbers the whole sibling list), and a move needs an anchor, since `reparent` appends without one and refuses an append into the parent the element already has. So "move later" moves the *next* sibling in front of this one.-- A shared control that knows *which* prop it edits keyframes it itself, off an `Entity` (`ColorOpacityPicker`'s `keyframeTarget`, now koota's); only a control that cannot know takes the diamond as a slot (`ControlledTextField`, `ColorOpacityRow`). Moving one of these moves it whole: the bitecs panels still calling it lose their diamonds until they migrate, and its recent-colors palette now queries the koota world for them too (both providers are mounted).--Still on bitecs: the timeline's keyframe layer and the whole timeline UI, plus auto-captions (`components/genai/use-auto-captions.ts`). Two of the panels are therefore complete but unreachable until those move: nothing on the koota side *creates* a caption (a `<captions>` element gets into the world by being written in a project file) and nothing *selects* a keyframe (only nodes and scenes are selected, by the canvas).--The stroke panel moved with the model: `StrokeStyle` is the stroke's, not the node's (as `<stroke width join cap miterLimit>` always was), so Weight/Join/Miter sit under each stroke's row instead of once per node. `<stroke>` is a solid paint that takes no paint children, so its picker is the color one alone, with no gradient or asset tab and no `FillPicker` behind it. `cap` still has no control (it shows only on open paths, and there are no icons for it).--The effects panel dropped its add menu: the plus authors an `<effect type="blur" value={8}>` outright and opens the inspector on it, where a select in the header (standing where a title would, as the export inspector's does) changes which filter it is. Every effect is the same one number under a different name, so the type is a control like any other rather than a question asked before the element exists. What that select has to answer for is the unit: `value` is px for `blur`, degrees for `hueRotate` and a 0-1 amount for the six others (`effect-types.ts` carries the table), so a switch within a unit keeps the value while one across it takes the new type's default and drops the `value` track, whose numbers meant the old unit. `type` and `value` are both required props and so are always written, never unset. `<effect>` gained `hidden` (`Pick<CompositeProps, "hidden">`, as `<shadow>` has it): the renderer already skipped a hidden effect, and the panel's row menu had no way to say so.--The animations panel took the same plus: it authors `<animation type="fade">` (every node can play a fade) and opens the inspector, whose header select picks the preset out of the groups the node can play, `animation-types.ts` carrying them. The Text and Audio groups are offered on a text node and on one with something to hear (an audio clip, a video paint, a video fill), plus whichever group holds the preset already set, so an animation authored before the node lost its audio still has a value the select can show. `type` is required and always written; `phase`, `duration` and `delay` unset at "in", 1s and 0. Phase moved out of the header into a row of its own, since the header now names the animation. Rows list the in-animations before the out ones, each in the file's order, which is the order two animations on one property resolve in.--The transition panel is the odd one of the three: `transition` is a prop of the clip (a `TransitionSpec`, one per clip), not a child element, so there is one row and the plus goes once a transition is there, the way the export panel's does. Its plus authors `{ type: "dissolve", duration: 1 }` and opens the inspector, where the same header select changes the style. **Both fields are written every time**: `setProperty` merges a partial into the transition already set, while the writer spells the attribute as whatever it was last handed, so a partial write would leave the file and the trait saying different things (and a switch back to `dissolve` would never land). Removal writes `false`, not `null`: `null` is a spelling the prop accepts but the writer would put it in the file, while `false` is what it drops the attribute for.--The masks panel got shorter with the model. A mask is `<rect mask>`, a rect like any other, so it needs no inspector of its own: a row selects it and the transform, time and appearance panels are then its own. Three things the bitecs "Add mask" authored are gone with them: the white solid fill and the trim to the parent's window (a mask is never drawn, and without an `end` it already clips for the parent's whole window), and the `[Mask Shape]` name suffix, which was there for a timeline that could not tell a mask apart otherwise. What it still authors is the parent's own size (a mask without one is 500x500, which is what an empty group gets) at a 20px inset, so the new mask shows itself instead of landing invisibly on top of the parent. `Expanded` is not set on the parent: that is app-side timeline state the koota side has not picked up yet.--The audio panel kept its knob, meter and buttons; what moved is where they write. `volume` (decibels, unset at 0 since that is unity) and `muted` are props; **solo is not** — `Soloed` is a runtime-only tag with no JSX spelling, so the button writes the trait alone and the solo is gone on the next recompile, which is what a monitoring toggle should be. The knob writes whole decibels: it is what the field and the knob both display, and a dragged knob would otherwise mint a new fraction (and a new keyframe) per frame. The meter is unchanged, reading `AudioBusHandle` through `useTrait` (the playback system spins the bus up once the node has audio, and sets it back to null when the decoders are released, so the accessor holds null while the trait is still there).--Fixed while the panel moved: the `gain` animation used to write a 0-1 linear ramp into `Computed.volume`, which everything else reads as decibels (`audio-bus.ts` does `10 ** (db / 20)`), so a Volume animation ramped 0 dB to 1 dB, inaudibly, instead of silence to unity. It now ramps the *amplitude* and adds it to the volume as decibels (`amplitudeToDecibels`, -Infinity at silence, which the bus already reads as a gain of zero). Two consequences worth knowing: it reads `Computed.volume` instead of replacing it, unlike the visual presets, so a clip set to -6 dB fades to -6 dB rather than up to unity and an overlapping in and out compose; and a fade sounds even because it is even in amplitude, not in decibels.--The fills panel needed two tags that did not exist. The runtime renders an image or a video **fill** (`renderFills` handles the media paints), but the paint family had no word for one: media was only ever a `<video>`/`<image>` node. So `<imagePaint>` and `<videoPaint>` were added to `COMPOSITION_TAGS`, the intrinsics, `elements.ts` and `PAINT_TYPES`; they mirror the node tags exactly (`src`, `objectFit`, and `bindAsset`'s rule that a frames directory plays as a sequence), which is why they are two tags rather than one `<mediaPaint>` taking its kind from the asset.--What that panel now says that the old one did not: **a fill's kind is its tag**, so changing it is not a property write but a swap. `FillPicker.replaceFill` inserts the new element in front of the next fill (keeping its place in the paint stack) and removes the old one, then hands the caller the entity it ended up with (`onReplace`) — the panel's `picked` signal has to move with it, and the old element's keyframe tracks go with it, which is honest: they drove a paint that no longer exists. The same swap is what linear ↔ radial does, writing the stops and the rotation out onto the new element. Picking another asset for a fill that already is one of the same kind is a plain `src` write, so the fit and the tracks survive.--Two details worth keeping: gradient stops have no `Cache` list of their own (`readGradientStops` queries `ColorStop, ChildOf(fill)` and sorts by offset, since where a stop sits is its `offset` and the file's order says nothing), and the fill picker's asset tab reuses the sidebar's `LazyAssetItem`, so renaming, replacing and deleting an asset work the same from both places. `ScaleModeType.NONE` is not offered: `Fit` has no word for it. The stub "Preview" and "Replace media" toasts of the old asset picker were dropped rather than carried over.--The shadow panel kept the shape it had: a row per `<shadow>` opening a floating inspector, since nothing in the shadow model moved the way the stroke's line style did. The one thing it says that the file does not is what "Add shadow" authors (`opacity` 0.25, `blur` 4, `offsetY` 4): `<shadow>`'s own defaults are all zero, which casts the silhouette back onto itself, so a shadow added from the panel has to spell out where it sits. Every control unsets at the prop's default (0 for the offsets and the blur, 1 for opacity); `color` is required and always written.--Two deliberate departures from the old text panel: `letterSpacing` is shown in px (the trait's unit and the prop's; the bitecs panel showed the same number as a percentage), and the font a text is set in — family, weight, size — is written out plainly rather than unset at its default, since a font is what a text *is* and not a modifier of it. The caption half of the panel is reachable now that `<captions>` has a host, but what it writes (`fontFamily`, `fontSize`, ...) is not in `CaptionsProps`; see the caption panel below.--The transform panel is where the props run out: position, rotation, offset and scale are props like any other, but **anchor, flip, skew and constraints have no JSX spelling**, so those four rows write their traits alone and are gone on the next recompile, the way `KeepAspectRatio` and `ClipsContent` are. Two things follow from that. The skew row lost its keyframe diamonds: `skew.x`/`skew.y` are runtime property paths (the motion system does animate them), but `TRACK_PROPERTIES` maps no prop name onto them, so no `<keyframeTrack>` can name a skew and a diamond there would have toggled nothing. And `Anchor`'s trait defaults are (0, 0) while a node *without* the trait pivots about its centre (`computeLocalMatrix` reads an absent slot as 0.5), so the row writes both axes on every edit: adding the trait one axis at a time would move the pivot to the corner. The picker went presentational (it takes the anchor and an `onPick`) so that fallback is spelled once.--`x`/`y` are written out even at 0, as the canvas writes them on a drag: where a node sits is what it is, the way a size is. Everything else in the panel unsets at its default, `rotation` included, so the row's "Reset to Default" removes the attribute where the canvas's rotate handle would write `rotation={0}`.--Uniform versus per-axis scale is the corner-radius pattern again: uniform is `scale`, separate is `scaleX`/`scaleY`, `scale` wins wherever both are set (the motion system's rule), and a mode switch drops the other mode's props *and* its tracks. Uniform unsets at 1; the axes are written out even at 1, since that is what says the node is on separate scale at all. The `world.history.transaction` that wrapped the switch went with the history layer the koota side does not have.--Fixed while the panel moved: the motion system mirrored an animated uniform scale onto `scaleY` only for a node that also had `UniformScale`, but the panel unsets `scale` at 1, so keyframing uniform scale at 100% (the ordinary case) minted a `scale` track on a node with no `UniformScale` and squashed it horizontally as the track played. A `scale` track *is* the uniform scale, whether or not the prop is authored alongside it, so the mirror now follows the track too.--The constraints row behaves as it did, but its "does this node take constraints at all" test now mirrors `resolveConstraintOffsets`: a sequence is not a spatial parent, so look above it, and the answer is yes only against a scene's frame. Setting one moves nothing until that frame changes, because the runtime seeds `ConstraintCache` the first time it sees the node with a `Constraint`.--The caption panel needed the element it edits: `<captions>` was in `COMPOSITION_TAGS`, the intrinsics and `elements.ts`, and the runtime rendered, timed and decoded it, but `createNode` threw on the tag, so no caption could exist in a koota world. It has a host now: a TEXT geometry with `Chars` and `Caption`, and deliberately **no `TextStyle` and no `Size`** — the preset's decoder authors both, plus the paints and shadows it draws with, and an absent `TextStyle` is the flag `resolveCaptionDecoder` reads to know it has not run yet. `preset`, `colors` and `verticalAlign` are the three props the host understands (`CAPTION_PRESETS`/`CAPTION_ALIGNS` name the enums, next to `ANIMATION_TYPES` and `EFFECT_TYPES`); `seed` is a transcription input with no trait behind it and falls through with everything else a richer vocabulary might say. `CaptionsProps` gained `IdentityProps`: the editor reports `selected` as a prop edit on every click, so a node it can select and cannot spell `selected` on is one whose selection it cannot write back.--`colors` is positional (the decoders read `colors[0]`, `colors[1]`, ... and fall back to their own constants), so the host writes it **by index, holes and all**: a slot the file leaves out, or spells with a color that does not parse, is one the preset fills itself, and compacting the array would shift the rest along. The panel writes the other way round, spelling every slot the preset has whenever one changes, since a shorter array would read back as the slots before it.--Fixed while the panel moved: switching preset stacked the new preset's look on the old one's. `resolveCaptionDecoder` re-runs `applyStyles` on a type change, and `applyStyles` *appends* the fill (and, for classic, the shadow) it draws with; the bitecs panel papered over this app-side by deleting every child of the caption entity first. That belongs to the model, not the panel, so `clearPresetStyling` now drops the paints, shadows and text ranges of the departing preset (and its `TextStyle`) before the new one applies. Animations and keyframe tracks are the file's and stay.--Two things the panel says that the old one did not. A preset change unsets `colors` rather than carrying it: the slots are the preset's, and Guinea's three do not mean what Spotlight's one did. And `verticalAlign` got a control at all — the trait and the prop are new since the bitecs model, and nothing else in the editor could reach them. Unset there is the preset's own placement rather than a fourth value, so no tab is active until one is picked and the row's context menu is how it goes back.--Worth knowing: `placeCaption` returns false when `getParentNode` is null, so a `<captions>` directly under `<stage>` is never sized, placed or styled. Captions belong inside a scene, whose frame is what "centered" and "bottom margin" are measured against.--Still narrower than the inspector: `CaptionsProps` declares timing, offset, `src` and the three above, while the inspector also shows layout, appearance, text, fills, strokes, shadows and effects for a caption target. Those write props `<captions>` does not have, so the file they produce would not typecheck. Settling that (widen the element, or narrow the panel list) is its own decision and was left alone.--The interpolation panel is a plain port: `<keyframe easing>` was already hosted, and the widgets under it (the bezier, spring and step curves, and the preview) never touched the ECS, so only the top of the file moved. What changed is the vocabulary. The panel's four ease presets and four spring presets **are** the eight easings the JSX has names for, and `EASINGS` (now exported from the reconciler) is the one table mapping name to descriptor, so `easing-types.ts` builds both preset lists off it rather than restating the beziers. A preset is written back as its name, so the file reads `easing="easeOut"` and `easing="bouncy"`; a curve dragged by hand has no name and travels as `cubicBezier(...)`, a hold as `steps(n)`. Linear is `<keyframe>`'s default and unsets. The `easingVersion` signal the bitecs panel bumped after every write is gone: a koota `set` fires a change event, which is what `useTrait` is waiting for.--Which spring preset is showing is matched on the parsed numbers, not on the descriptor string, so a file spelling one as `spring(0.50,628)` still reads as Gentle; everything the panel writes itself is canonical, so the write side matches on the string.--**A decision the timeline slice has to make**: `useSelection` splits the `Selected` query on `has(Keyframe)`, so a selected keyframe is how this panel is reached — but `editor.setSelected` reports `selected` as a prop edit for anything it selects, and `KeyframeProps` has no `selected`. Whoever moves the keyframe layer either gives `<keyframe>` the prop (as `<captions>` was given `IdentityProps`) or stops reporting selection for sub-entities. For a keyframe the second looks right: unlike a node's, the selection is momentary, there can be dozens of them, and persisting it would churn the source on every click in the timeline.--**Left stale on purpose** (deferred to a docs/examples pass): the eight `examples/*.tsx` still open with `<rect scene="...">` and no `<stage>`, so `tsc -p examples --noEmit` fails on them, and `reference/jsx/*` still describes the pre-`<stage>` model and `key` as the `syncTo` target. `reference/jsx` is stale as a whole; patching rows piecemeal would hide that.--## Remaining work--1. **apps/web**: the timeline UI (its keyframe layer included) and auto-captions, app-side world traits (store, timelineIndex signal), history via koota events, re-adding the editing-surface `syncKeyframeTrack` calls the observers slice dropped. The inspector panels are all across. `utils/captions.ts` stays app-side, rewired to `@diffusionstudio/encoder`. Once real content loads into the koota world, delete the hidden bitecs canvas and `engine/components`, `engine/api` progressively.-2. **CLI**: point node capture at the runtime + encoder packages, importing `MAX_FRAMES_PER_SHEET` from the encoder instead of redefining it in `cli-channels.ts`.--## Package reminders--- Exports: root `.` plus `./traits`, `./systems`, `./media`; everything is also re-exported from `src/index.ts`. The `./capture` entry in package.json is dangling (`src/capture/` no longer exists) and wants deleting.-- tsconfig sets `erasableSyntaxOnly: false` (enums with reverse lookups, same as apps/web).-- Deps: koota (patched), mediabunny, animejs, colord, `@diffusionstudio/assets` (the asset model moved out into its own package; sqids went with the id allocator). Dev: `@webgpu/types`.diff --git a/packages/runtime/README.md b/packages/runtime/README.mdindex 413e6ff5..29d61374 100644--- a/packages/runtime/README.md+++ b/packages/runtime/README.md@@ -3,5 +3,3 @@Headless editor runtime built on [koota](https://github.com/pmndrs/koota): traits, world creation and serialization, actions, deterministic systems, media decoding, and capture.Must work without a DOM and without solid-js so the CLI and node capture can consume it directly. Browser-only concerns (input, keyboard, HUD, timeline canvas UI, persistence) live in `apps/web`; Solid reactivity bindings live in `@diffusionstudio/koota-solid`.--The bitecs to koota migration is in progress; see [MIGRATION.md](./MIGRATION.md) for status, design decisions, koota gotchas (including the local koota patch), and the remaining work.diff --git a/packages/runtime/src/actions/resize.ts b/packages/runtime/src/actions/resize.tsindex 3d48e545..a78e1972 100644--- a/packages/runtime/src/actions/resize.ts+++ b/packages/runtime/src/actions/resize.ts@@ -60,16 +60,16 @@ export function resizeEntity(world: World, entity: Entity, params: ResizeParams)});// handle DOM nodes- const domNode = entity.get(Host)?.domNode;+ const element = entity.get(Host)?.element;- if (domNode instanceof HTMLCanvasElement) {- domNode.width = width ?? domNode.width;- domNode.height = height ?? domNode.height;+ if (element instanceof HTMLCanvasElement) {+ element.width = width ?? element.width;+ element.height = height ?? element.height;}- if (domNode instanceof HTMLElement) {- domNode.style.width = `${width ?? domNode.style.width.replace('px', '')}px`;- domNode.style.height = `${height ?? domNode.style.height.replace('px', '')}px`;+ if (element instanceof HTMLElement) {+ element.style.width = `${width ?? element.style.width.replace('px', '')}px`;+ element.style.height = `${height ?? element.style.height.replace('px', '')}px`;}// The Size observer propagates Computed sizes; constraints resolve here.diff --git a/packages/runtime/src/systems/assets.ts b/packages/runtime/src/systems/assets.tsindex cf88620e..6298798f 100644--- a/packages/runtime/src/systems/assets.ts+++ b/packages/runtime/src/systems/assets.ts@@ -116,12 +116,12 @@ function resolve(world: World, entity: Entity, promise: Promise<Asset>, generatifunction isDomImage(entity: Entity): boolean {return typeof HTMLImageElement !== 'undefined'- && entity.get(Host)?.domNode instanceof HTMLImageElement;+ && entity.get(Host)?.element instanceof HTMLImageElement;}function pointDomImageAt(entity: Entity, source: string | null): void {const node = entity.get(Host);- const image = node?.domNode;+ const image = node?.element;if (typeof HTMLImageElement === 'undefined' || !(image instanceof HTMLImageElement) || !node) return;releaseDomImageSource(image);@@ -145,7 +145,7 @@ async function bindDomImage(entity: Entity, asset: Asset, token: object): Promis}pointDomImageAt(entity, url);- const image = entity.get(Host)?.domNode;+ const image = entity.get(Host)?.element;if (typeof HTMLImageElement !== 'undefined' && image instanceof HTMLImageElement) {await image.decode().catch(() => undefined);}diff --git a/packages/runtime/src/systems/playback.ts b/packages/runtime/src/systems/playback.tsindex 8ce2699d..32b8cf4f 100644--- a/packages/runtime/src/systems/playback.ts+++ b/packages/runtime/src/systems/playback.ts@@ -202,7 +202,7 @@ function forwardAudioDecoder(world: World, scene: Entity, entity: Entity, audioSfunction forwardHtmlHost(world: World, scene: Entity, entity: Entity, fill: Entity): void {const computed = store(world, Computed);- const root = fill.get(Host)?.domNode;+ const root = fill.get(Host)?.element;if (world.get(Mode)?.value === 'realtime'|| computed.visibility[entity.id()] !== 1|| !(root instanceof HTMLElement)) return;diff --git a/packages/runtime/src/systems/render.ts b/packages/runtime/src/systems/render.tsindex 7d199cfe..948ebdab 100644--- a/packages/runtime/src/systems/render.ts+++ b/packages/runtime/src/systems/render.ts@@ -215,7 +215,7 @@ export function renderIntrinsicFill(world: World, entity: Entity): void {const intrinsic = getIntrinsicPaint(entity);if (intrinsic === PaintType.SURFACE) {- const canvas = entity.get(Host)?.domNode;+ const canvas = entity.get(Host)?.element;if (canvas instanceof HTMLCanvasElement) {const ctx = getCtx(world);const computed = store(world, Computed);@@ -258,7 +258,7 @@ type DrawElementContext = Ctx2D & {function renderHtmlFill(world: World, entity: Entity, source: Entity): void {- const root = source.get(Host)?.domNode;+ const root = source.get(Host)?.element;const surface = world.get(RenderSurface);const ctx = surface?.ctx;if (!(ctx instanceof CanvasRenderingContext2D)) return;@@ -353,7 +353,7 @@ export function renderFills(world: World, entity: Entity): void {} else if (paint === PaintType.HTML) {renderHtmlFill(world, entity, fill);} else if (paint === PaintType.SURFACE) {- const canvas = fill.get(Host)?.domNode;+ const canvas = fill.get(Host)?.element;if (canvas instanceof HTMLCanvasElement) {ctx.save();ctx.clip();diff --git a/packages/runtime/src/traits/document.ts b/packages/runtime/src/traits/document.tsindex d0d0bc3d..9cd2dcb7 100644--- a/packages/runtime/src/traits/document.ts+++ b/packages/runtime/src/traits/document.ts@@ -4,27 +4,19 @@import { trait } from 'koota';-import type { Entity } from 'koota';+import type { SceneNode as AuthoredSceneNode } from '@diffusionstudio/jsx';/** The real DOM node owned by a scene node. */export type DomNode = Element | Text;/**- * One element of the document, and its place in it. `parent` and `children`- * are the tree the reconciler reads back: text nodes and element nodes in the- * one order they were inserted in, which is what the document answers- * `getFirstChild` and `getNextSibling` from.+ * One element of the document, and its place in it: the authoring `SceneNode`+ * (see @diffusionstudio/jsx) instantiated with the DOM node type the document+ * manages. `parent` and `children` are the tree the reconciler reads back:+ * text nodes and element nodes in the one order they were inserted in, which+ * is what the document answers `getFirstChild` and `getNextSibling` from.*/-export interface SceneNode {- readonly entity: Entity;- /** Native composition elements participate in the Koota scene graph. */- readonly native: boolean;- tag: string;- props: Record<string, unknown>;- parent: SceneNode | null;- children: SceneNode[];- readonly domNode: DomNode | null;-}+export type SceneNode = AuthoredSceneNode<DomNode>;// The document node an entity was rendered from, on the entity itself: the// one object the document and the renderer both hold for it, so `===` betweendiff --git a/reference/README.md b/reference/README.mdindex db7438b4..fd3420e7 100644--- a/reference/README.md+++ b/reference/README.md@@ -4,6 +4,8 @@ Reference for `dapi`, the Diffusion Studio CLI. Every canvas and project commandEach feature command has its own file (linked below). The JSX code syntax specified in [jsx/](./jsx/README.md) is **pseudo-SVG**, mirroring SVG's shape-and-paint model with the editor's own tags and props rather than the SVG spec.+A project is a folder of that JSX, and **the source is the document**: the app compiles the entry file and renders every element into an editable node, and edits made on the canvas are written back to the element that authored them. So the loop is `dapi open <dir>` once, then edit the files — there is no command that pushes content into the app. What the commands do is read the running app ([`context`](./context.md), [`capture`](./capture.md), [`logs`](./logs.md)), inspect media, and list what a declaration may name.+## Groups**Top-level:** [`whoami`](./whoami.md), [`logs`](./logs.md), [`screenshot`](./screenshot.md), [`report`](./report.md), [`context`](./context.md) (alias `ctx`), [`capture`](./capture.md), [`models`](./models.md), [`voices`](./voices.md), [`fonts`](./fonts.md), [`fetch`](./fetch.md).@@ -29,7 +31,7 @@ How the surface is divided:### Document- [`dapi open`](./open.md): launch the app and open (or create) a project folder, anywhere on disk-- [`dapi context`](./context.md): which project the app has open, where its playhead sits, and its registered fonts+- [`dapi context`](./context.md): which project the app has open, where its playhead sits, its registered fonts, and where its generations stand- [`dapi capture`](./capture.md): render a node in isolation to a labelled contact sheet, or one PNG per position### Media@@ -59,6 +61,7 @@ How the surface is divided:```tsAsset = { id: string; path: string; type: string } // asset ids are content hashes; `path` is the library pathTime = number | `${number}f` | "MM:SS" // seconds, frames at 30 fps ("45f"), or a clock string; see jsx/timing.md+NodeId = string // an element's `id` in the project's JSX; `file:id` when two files collide```Time inputs take the `Time` format unless noted otherwise. Times in **outputs** are plain seconds.diff --git a/reference/context.md b/reference/context.mdindex faaaba8d..6bd9fc96 100644--- a/reference/context.md+++ b/reference/context.md@@ -1,6 +1,9 @@# `dapi context`-Summary of app state. Alias: `ctx`.+Summary of app state: what the project's source cannot say. The composition+itself — its scenes, what is selected, which scene is active, the work area —+is all in the JSX, and a caller that wants any of it reads the file. Alias:+`ctx`.## Input@@ -19,6 +22,13 @@ One JSON object:};currentTime: number | null; // playhead in the active scene, in seconds; null if no scene is activefontFamilies: string[]; // families registered in the running world, valid as `fontFamily`+ generations: { // every generated source in the project, and where it stands+ element: string | null; // the element's source stamp, `<file>:<id>`; null for an entity no element produced+ name: string | null; // the element's `name`, when it has one+ state: "generating" | "failed" | "done";+ error?: string; // what it failed with, on `failed` rows+ asset?: string; // the library path it landed as, on `done` rows+ }[];}```@@ -35,3 +45,11 @@ one a command was run from: check it before writing to source files.`fontFamilies` is what text can be drawn with right now — loaded into the world,not merely named in the source — and always includes the editor default. Forevery family installed on the machine, see [`dapi fonts`](./fonts.md).++`generations` is how a caller waits for `generate.*` declarations without+blocking: generation is asynchronous, so poll this until nothing is+`generating`. A `done` row's `asset` is a library path, ready for+[`dapi media probe`](./media/probe.md) and its siblings; a `failed` row's+`error` is the same message the element carries as its `error` prop, which is+what keeps it from being generated again (see+[jsx/errors.md](./jsx/errors.md#failed-sources)).diff --git a/reference/jsx/README.md b/reference/jsx/README.mdindex f9a5afc9..63b73a5e 100644--- a/reference/jsx/README.md+++ b/reference/jsx/README.md@@ -1,30 +1,49 @@# JSX Code Syntax-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 a folder of JSX, and **that source is the document**. The entry file default-exports a **Solid component**; the app compiles it and a custom renderer (built on `solid-js/universal`, Solid's equivalent of React's reconciler) mounts it **directly into the editor's ECS**. Every composition 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 `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).+It goes back the other way too: every element carries an `id`, so a rect dragged on the canvas, a clip trimmed on the timeline or a retyped line lands as a prop on the element it was authored as. Saving recompiles and remounts the project — the way reloading a page rebuilds it — and a compile error leaves the last good render on the canvas.++A project is structured like a SolidJS app: the root is a [`<stage>`](./stage.md) holding one [`<scene>`](./scene.md) per frame you cut in, and the 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.-> **Status:** the CLI commands that drove this pipeline (`dapi mount`, `dapi node insert`, `dapi node patch`, and the rest of `dapi node`/`dapi asset`/`dapi project`/`dapi folder`/`dapi selection`) have been removed pending a rebuild where JSX becomes the source of truth for the document. This file documents the contract they will implement again: mounting a project's roots into the document, inserting into an existing parent entity, and assigning props on existing nodes. `dapi node capture` survived the cut as the top-level [`dapi capture`](../capture.md), unrelated to authoring — it only renders an existing node to PNGs.+```tsx+export default function Project() {+ return (+ <stage background="#161616">+ <scene name="Intro" width={1920} height={1080} fill="black">+ <video src="b-roll/drone.mp4" start={0} end={6} width={1920} height={1080} />+ <text y={860} width={1920} textAlign="center" fontFamily="Inter" fontSize={96} start={1} end={5}>+ Hello+ <animation type="fade" duration={0.5} />+ <animation type="fade" phase="out" duration={0.5} />+ </text>+ </scene>+ </stage>+ );+}+```## Contents| File | Covers || ---- | ------ |-| [module.md](./module.md) | Project module contract, module environment, types and tooling |-| [roots.md](./roots.md) | Root elements, `key` identity, canvas placement |+| [module.md](./module.md) | Project module contract, module environment, `id`, types and tooling |+| [stage.md](./stage.md) | `<stage>`: the root, canvas background and camera, canvas placement |+| [scene.md](./scene.md) | `<scene>`: the clipped, playable frame and the timeline its children sit on || [elements.md](./elements.md) | Element-to-node mapping, coordinates and sizing, the shared property table |-| [scene.md](./scene.md), [group.md](./group.md), [rect.md](./rect.md), [text.md](./text.md), [video.md](./video.md), [image.md](./image.md), [audio.md](./audio.md) | Per-element props |+| [group.md](./group.md), [rect.md](./rect.md), [text.md](./text.md), [video.md](./video.md), [image.md](./image.md), [audio.md](./audio.md) | Per-element props || [fonts.md](./fonts.md) | Fonts for `<text>` and HTML: local families, `dapi fonts` |-| [paints.md](./paints.md) | `<solidPaint>`, gradients, `<colorStop>` |+| [paints.md](./paints.md) | `<solidPaint>`, gradients, `<colorStop>`, `<imagePaint>` / `<videoPaint>` |+| [styles.md](./styles.md) | `<stroke>`, `<shadow>`, `<effect>`: outlines, drop shadows and filters || [html.md](./html.md) | `<html>`: reactive HTML children drawn into the box || [surface-paint.md](./surface-paint.md) | `<surface>`: a ref-provided canvas you draw into, sampled every frame || [shader-paint.md](./shader-paint.md) | `<shaderPaint>`: a WGSL fragment shader over the media paint below it |-| [media.md](./media.md) | `src` resolution (paths, URLs, asset ids, `AssetRef`) |-| [timing.md](./timing.md) | `start` / `end` / `sourceIn` / `sourceOut`, time formats |+| [media.md](./media.md) | `src` resolution (paths, URLs, asset ids, `AssetRef`), image sequences, modifiers |+| [timing.md](./timing.md) | `start` / `end` / `sourceIn` / `sourceOut` / `playbackRate`, time formats || [keyframes.md](./keyframes.md) | Keyframe animation and easing |-| [animations.md](./animations.md) | The `animations` prop: preset in/out animations |+| [animations.md](./animations.md) | `<animation>`: preset in/out animations || [transitions.md](./transitions.md) | The `transition` prop on sequence clips || [sequences.md](./sequences.md) | `<sequence>` sequential placement || [adjustment-layer.md](./adjustment-layer.md) | `<adjustmentLayer>`: a transform over the clip below it |@@ -36,10 +55,13 @@ The markup is **pseudo-SVG**: elements like `<rect>`, `<text>`, `<linearGradient## Pipeline-1. **Compile**: the entry file bundles with esbuild + `babel-preset-solid` in `universal` mode, so JSX compiles against the editor's renderer runtime (`@diffusionstudio/jsx`) instead of the DOM. Compile errors fail here, before the app is contacted.-2. **Ship**: the resulting single-file ESM bundle is delivered to the running app.-3. **Evaluate**: the app imports the module. Top-level code (including top-level `await`) runs to completion. The module's **default export** is the project component.-4. **Mount**: the component tree is rendered into a **staging root**. The universal renderer materializes each element as an ECS entity with the appropriate components (see [elements.md](./elements.md)). Mounting is synchronous; an error here aborts the import with nothing inserted.-5. **Commit**: the rendered roots are reconciled against the document (see [roots.md](./roots.md)) as a **single undoable operation** that also covers the generated assets below.-6. **Generate**: declared assets generate in dependency order, **blocking the command** until every one has landed. Each placeholder renders a generating state until its asset lands, then the node's paint is attached (see [generate.md](./generate.md)).-7. **Sync**: nodes declaring `syncTo` are aligned once every generated asset has landed: each node's audio is cross-correlated against its target's and its `start` is written from the measured offset (see [audio-sync.md](./audio-sync.md)). Local and blocking; captions wait for it.+Everything below runs in the app, on open and again on every save of a project file.++1. **Stamp**: every composition element that has no `id` is given one, written back into your source. Ids are what an entity is traced to, so they are minted before the file is numbered rather than after (see [module.md](./module.md#ids)). A project where nothing is missing an id is not written to.+2. **Compile**: the entry file bundles with esbuild + `babel-preset-solid` in `universal` mode, so JSX compiles against the editor's renderer runtime instead of the DOM. `solid-js`, `solid-js/store` and `@diffusionstudio/jsx` are external — the app supplies its own instances; everything else is bundled. A compile error is reported and the canvas keeps the last good render.+3. **Evaluate**: the app imports the module. Top-level code runs to completion. The module's **default export** is the project component.+4. **Mount**: the component tree renders **directly into the world**. There is no staging tree: each element materializes as an entity as it is created, and the root `<stage>` is the one already there. Mounting is synchronous, and a throw part-way through leaves nothing behind — the document is disposed and the previous render stays on the canvas.+5. **Resolve**: every `src` resolves in the background — a path or asset id is loaded, a `generate.*` declaration is generated in dependency order, a `<captions>` without a `src` transcribes its scene. Each element renders a generating state until its asset lands, and an element that fails carries the reason (see [generate.md](./generate.md), [errors.md](./errors.md)). Non-blocking: the composition is on the canvas and editable while this runs, and [`dapi context`](../context.md) reports where each generation stands.+6. **Live**: the reactive graph keeps running for as long as the project is open — signals, effects, `useTicker` (see [lifecycle.md](./lifecycle.md)). Export, capture and the next open re-execute the same module.++A save replaces the whole run: the old mount is disposed and the new one takes the stage. Scenes are rebuilt rather than accumulated, and the entities the previous render owned go with it.diff --git a/reference/jsx/adjustment-layer.md b/reference/jsx/adjustment-layer.mdindex ac06c10f..964e6a65 100644--- a/reference/jsx/adjustment-layer.md+++ b/reference/jsx/adjustment-layer.md@@ -3,8 +3,8 @@A layer that draws nothing of its own and transforms **the clip below it**. While the layer's clip lasts, its transform composes onto that of the sibling directly beneath it in the stack, so a punch-in, a drift or a keyframed zoom is authored once, in a row of its own, and trimmed and slid along the timeline without the clip it acts on being touched.```tsx-<scene width={1920} height={1080}>- <video src="interview.mp4" />+<scene name="Interview" width={1920} height={1080}>+ <video src="a-roll/interview.mp4" /><adjustmentLayer start={2} end={6} scale={1.4} /></scene>```@@ -37,7 +37,7 @@ Inside a [`<sequence>`](./sequences.md) the layer acts on what sits below the *s| `scaleX`, `scaleY` | `number` | `1` | Per-axis scale. || `width`, `height` | `number` | `1920` × `1080` | **Never drawn**: the box the transform pivots around. Set them to the scene's own size on a frame shaped otherwise, so `rotation` and `scale` turn about its middle. || `hidden` | `boolean` | absent | Excludes the layer without removing it: the clip below is left alone and the layer keeps its place in the timeline. |-| `start`, `end`, `sourceIn`, `sourceOut` | `Time` | see [timing.md](./timing.md) | When the layer acts. |-| `name` | `string` | none | Human-readable node name. |+| `start`, `end` | `Time` | see [timing.md](./timing.md) | When the layer acts. A layer is sourceless, so with no `end` it takes the 16-second default. |+| `id`, `name` | `string` | see [elements.md](./elements.md#common-props) | Address and label. |It has no `fill`, no `opacity` and no `blendMode`: it has no pixels of its own to give them to. Its children are [`<animation>`](./animations.md) and [`<keyframeTrack>`](./keyframes.md) elements — what the layer's transform is animated with.diff --git a/reference/jsx/animations.md b/reference/jsx/animations.mdindex db5f5e25..14553eda 100644--- a/reference/jsx/animations.md+++ b/reference/jsx/animations.md@@ -3,7 +3,7 @@`<animation>` declares one **preset in/out animation** on the clip holding it: it plays over the clip's head (`"in"`) or tail (`"out"`), between the node's static state and the preset's start/end state. For hand-authored motion on individual props, use [keyframes](./keyframes.md); the two compose on distinct properties.```tsx-<video src="/Movies/intro.mp4" width={1920} height={1080} start={0} end={8}>+<video src="b-roll/intro.mp4" width={1920} height={1080} start={0} end={8}><animation type="fade" duration="15f" /><animation type="slideUp" phase="out" duration={0.5} delay={0.2} /></video>@@ -16,7 +16,7 @@| `duration` | `Time` | 1 second | Length of the animation. || `delay` | `Time` | `0` | Gap between the clip edge and the animation: after the head for `"in"`, before the tail for `"out"`. |-Valid under any node (`<rect>`, `<text>`, `<video>`, `<image>`, `<audio>`, `<group>`, `<captions>`). An `<animation>` is an element like any other: it has an `id`, the editor writes changes back to it, and it is copied with its node.+Valid under any node (`<rect>`, `<text>`, `<video>`, `<image>`, `<audio>`, `<group>`, `<captions>`, `<adjustmentLayer>`). An `<animation>` is an element like any other: it has an `id`, the editor writes changes back to it, and it is copied with its node.## Typesdiff --git a/reference/jsx/audio-sync.md b/reference/jsx/audio-sync.mdindex 7883040d..24a42137 100644--- a/reference/jsx/audio-sync.md+++ b/reference/jsx/audio-sync.md@@ -3,20 +3,22 @@`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-<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" />-</rect>+<scene name="Talk" width={1920} height={1080}>+ <video id="camera" src="a-roll/take-3.mp4" width={1920} height={1080} sourceOut={45} muted />+ <audio src="a-roll/lav.wav" syncTo="camera" />+</scene>```+> **Status:** `syncTo` is part of the authoring surface and typechecks, and the correlation itself is implemented in the runtime, but the mount does not apply it yet — a node carrying `syncTo` is placed by its own `start` (0 by default) as if the prop were absent. Set `start` explicitly until it lands.+## Semantics-- `syncTo` names the `key` of another element in the same render. Both sides must carry an audio track; any pairing works (audio-to-video, audio-to-audio, video-to-video).+- `syncTo` names the [`id`](./module.md#ids) of another element in the same render. Both sides must carry an audio track; any pairing works (audio-to-video, audio-to-audio, video-to-video).- The computed placement is `start = target.start + offset`, where `offset` is the measured source-time offset between the two recordings (positive when this node's recording started after the target's; possibly negative). `syncTo` and `start` are mutually exclusive.- `sourceIn`/`sourceOut` keep their normal meaning and remain yours to set. When omitted on a synced node, the window defaults to the intersection of the node's natural extent with the target's window (instead of the usual natural-duration fit), so a lav track simply covers its take.- Alignment reads source content: `muted` and `volume` on either side do not affect the measurement. Use `muted` to keep only one side audible, as on the camera track above.-- Chains resolve in dependency order (A may sync to B while B syncs to C). Unknown keys, cycles, and combining `syncTo` with `start` are mount errors; nothing is inserted.+- Chains resolve in dependency order (A may sync to B while B syncs to C). Unknown ids and cycles are mount errors.## Execution-Alignment runs at the sync stage of the [pipeline](./README.md#pipeline): after generated assets land (either side may be generated), before captions read the scene. It is local, consumes no credits, and blocks the command, so exit `0` means final placement. A correlation too weak to trust fails the command (see [errors.md](./errors.md)) while the node keeps its default placement. Offsets are **cached** by the pair of source contents, so re-mounting an unchanged project re-measures nothing.+Alignment runs at the resolve stage of the [pipeline](./README.md#pipeline), after both sides' assets have landed (either side may be generated) and before captions read the scene. It is local and consumes no credits. A correlation too weak to trust is reported rather than guessed at (see [errors.md](./errors.md)), and the node keeps its default placement. Offsets are **cached** by the pair of source contents, so re-mounting an unchanged project re-measures nothing.diff --git a/reference/jsx/audio.md b/reference/jsx/audio.mdindex 22dac42d..fc52982e 100644--- a/reference/jsx/audio.md+++ b/reference/jsx/audio.md@@ -1,9 +1,11 @@# `<audio>`-An audio clip: no picture, carries volume. When timing is omitted, the node fits its natural duration (see [timing.md](./timing.md)). It draws nothing inside a scene; placed directly on the canvas (see [roots.md](./roots.md)) the editor shows its waveform in a box, which `x`/`y`/`width`/`height` place.+An audio clip: no picture, carries volume. When timing is omitted, the node fits its natural duration (see [timing.md](./timing.md)).++It draws nothing inside a scene, but on the canvas it is still something to point at: the editor shows its waveform in a box, and `x`/`y`/`width`/`height` are where that box is. Leave them off inside a scene, where they mean nothing.```tsx-<audio src="https://my.videoarchive.com/audio/clip.wav" start={2.2} sourceOut={16} volume={-6} />+<audio src="music/bed.mp3" start={2.2} sourceOut={16} volume={-6} />```## Props@@ -11,11 +13,21 @@ An audio clip: no picture, carries volume. When timing is omitted, the node fits| Prop | Type | Default | Meaning || ---- | ---- | ------- | ------- || `src` | `string \| AssetRef` | **required** | See [media.md](./media.md). |-| `name` | `string` | none | Human-readable node name. |+| `id`, `name` | `string` | see [elements.md](./elements.md#common-props) | Address and label. || `x`, `y` | `number` | `0` | Where the waveform box sits on the canvas. No meaning inside a scene. || `width`, `height` | `number` | `500`, `150` | Size of that box. || `start`, `end`, `sourceIn`, `sourceOut` | `Time` | see [timing.md](./timing.md) | Temporal placement. |+| `playbackRate` | `number` | `1` | Speed multiplier for the clip's local time. || `volume` | `number` | `0` | Decibels: `0` = unity, negative attenuates (`-6` ≈ half as loud), `-Infinity` = silence. Not linear. || `muted` | `boolean` | `false` | Excludes the node's audio from the mix; independent of `volume`. |-| `syncTo` | `string` | none | Key of another element carrying audio; derives `start` by audio alignment (see [audio-sync.md](./audio-sync.md)). Mutually exclusive with `start`. |-| `animations` | `AnimationSpec[]` | none | Preset in/out animations (see [animations.md](./animations.md)); only `"gain"` is audible. |+| `syncTo` | `string` | none | `id` of another element carrying audio; derives `start` by audio alignment (see [audio-sync.md](./audio-sync.md)). Mutually exclusive with `start`. |+| `error` | `string` | none | Why this element's source never became an asset (see [errors.md](./errors.md#failed-sources)). |++An audio clip has no picture, so it takes no transform beyond its canvas box and no paints. Its children are [`<keyframeTrack>`](./keyframes.md) (a `volume` track) and [`<animation>`](./animations.md), of which only `"gain"` is audible:++```tsx+<audio src="music/bed.mp3" start={0} end={12} volume={-16}>+ <animation type="gain" duration={1} />+ <animation type="gain" phase="out" duration={2} />+</audio>+```diff --git a/reference/jsx/captions.md b/reference/jsx/captions.mdindex 343c096a..08a1585f 100644--- a/reference/jsx/captions.md+++ b/reference/jsx/captions.md@@ -1,37 +1,58 @@# Captions-`<captions />` inside a scene transcribes that scene's audio into a caption node: a styled, timed transcript, produced on import. To caption an already-open scene, insert one with `dapi node insert`.+`<captions />` inside a scene transcribes that scene's audio into a caption node: a styled, timed transcript.```tsx-<captions />+<scene name="Talk" width={1920} height={1080}>+ <video src="a-roll/take-3.mp4" width={1920} height={1080} />+ <captions preset="whisper" />+</scene>```-Transcription is **asynchronous and non-blocking**: the caption node is inserted at commit and its transcript attaches once ready. Because it reads the scene's audio, it runs **after** any generated assets in the scene have landed and after [audio sync](./audio-sync.md) has resolved; captioning a generated `voice`/`audio` track transcribes the finished audio at its final placement. The scene must contain an unmuted audio or video source; otherwise the caption node is left empty.+Transcription is **asynchronous and non-blocking**: the caption node is on the canvas from the moment the project mounts and its transcript attaches once ready. Because it reads the scene's audible mix, it waits until **every other source in the scene has landed** — a generated `voice` or `audio` track is transcribed at its final placement, not at the placeholder. The scene must contain an unmuted, unhidden audio or video source; without one the node carries an [`error`](./errors.md#failed-sources) saying so.-Transcripts are **cached**: every transcript asset records a fingerprint of the scene's audible mix (source content, placement, source offset, playback rate, gain). When a scene's fingerprint matches an existing transcript, that asset is reused instead of transcribing again; re-mounting a project with unchanged audio consumes no credits. Any change to the scene's audio invalidates the fingerprint.+## Bringing your own transcript++Give `src` a transcript file — `.srt`, `.vtt`, or a transcript `.json` — and it is mounted as it is; no transcription runs and no credits are spent. It resolves like any other [`src`](./media.md) (library path, asset id, path, URL), except that `generate.*` is not accepted.++```tsx+<captions src="transcripts/interview.srt" preset="classic" />+```## Props| Prop | Type | Default | Meaning || ---- | ---- | ------- | ------- |+| `src` | `string` | none | A transcript file to mount instead of transcribing the scene. || `preset` | see below | `"classic"` | Caption style preset. || `colors` | `string[]` | preset defaults | Fills the preset's color slots in order; any CSS color, alpha ignored. Ignored by presets without slots. |-| `verticalAlign` | `"top" \| "center" \| "bottom"` | preset default | Vertical placement of the caption block: anchored to the top or bottom safe margin (100 px), or centered. Horizontal placement stays with the preset. |-| `seed` | `number` | none | Joins the transcript cache key: a value unused for this audio transcribes the scene again instead of reusing the cached transcript (it costs credits). Reusing a value replays that take from cache. |+| `verticalAlign` | `"top" \| "center" \| "bottom"` | preset default | Vertical placement of the caption block: anchored to the top or bottom safe margin, or centered. Horizontal placement stays with the preset. |+| `seed` | `number` | `0` | Joins the transcript cache key — see [Caching](#caching). Ignored when `src` is set. || `offsetX`, `offsetY` | `number` | `0` | Render-time nudge in px on top of the preset placement; subpixel values are kept. A slide animation drives the same channel and wins while it plays. |-| `start`, `end`, `sourceIn`, `sourceOut` | `Time` | full transcript | Trim which stretch of the transcript is captioned, using the same [timing](./timing.md) semantics as media nodes. Set the source window (`sourceIn`/`sourceOut`) and timeline placement (`start`/`end`) together — see [Trimming](#trimming). |+| `start`, `end`, `sourceIn`, `sourceOut` | `Time` | full transcript | Trim which stretch of the transcript is captioned, using the same [timing](./timing.md) semantics as media nodes. See [Trimming](#trimming). |+| `id`, `name` | `string` | see [elements.md](./elements.md#common-props) | Address and label. |++`<animation>` children are valid; the text-only types (`"appearWord"`, `"appearChar"`, `"scramble"`) apply.The preset positions the caption block; `verticalAlign` overrides only its vertical anchor (`whisper` and `cascade` default to `bottom`, all other presets to `center`), and `offsetX`/`offsetY` nudge the drawn result from there.+## Caching++A transcript is cached under **the scene's id and the `seed`**, and the cached asset is reused whenever that pair comes up again — so reopening a project transcribes nothing and consumes no credits.++The audio itself is not part of the key. **Recutting a scene does not re-transcribe it**: to pick up changed audio, bump `seed`. A value used before replays that take from cache; a value that has not been used for this scene transcribes it again, which costs credits.+## TrimmingCaptions carry the same [timing](./timing.md) props as media nodes, and the transcript is source content that must stay aligned to the audio — so advance `start` and `sourceIn` together (and `end`/`sourceOut`), never `start` alone. To show only from 15 s onward, set both `sourceIn={15}` and `start={15}`. One node can't skip a gap, so to blank captions out for a middle stretch — e.g. under an overlay — use two nodes that meet at the gap:```tsx-<captions start={0} end={15} sourceIn={0} sourceOut={15} /> // before the overlay-<captions start={20} sourceIn={20} /> // after the overlay+<captions start={0} end={15} sourceIn={0} sourceOut={15} /> {/* before the overlay */}+<captions start={20} sourceIn={20} /> {/* after the overlay */}```+Both read the same cached transcript: two `<captions>` in one scene do not transcribe it twice.+## Presets`preset` selects the caption style: the same presets as the editor's caption inspector. Some presets expose **color slots**, filled in order by the `colors` prop; a missing or omitted entry falls back to the slot's default.diff --git a/reference/jsx/elements.md b/reference/jsx/elements.mdindex 703ea273..9f2b38de 100644--- a/reference/jsx/elements.md+++ b/reference/jsx/elements.md@@ -1,53 +1,114 @@# Element reference-camelCase composition elements map 1:1 onto internal node types. Lowercase DOM vocabulary is valid only inside [`<html>`](./html.md) content.--| Element | Internal node | Notes |-| ------- | ------------- | ----- |-| [`<group>`](./group.md) | **Container 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. With `mask` it clips its parent instead of drawing. |-| [`<video>`](./video.md) | **Geometry with Video paint** | `src` resolves to a video asset. |-| [`<image>`](./image.md) | **Geometry with Image paint** | `src` resolves to an image asset. |-| [`<audio>`](./audio.md) | **Geometry with Audio component and a hidden Waveform paint** | No visual output; carries volume. |-| [`<text>`](./text.md) | **Geometry with Text component** | Children become editable glyphs. |-| [`<textRange>`](./text.md#textrange) | **Text range sub-entity** | Style override over a run of the parent `<text>`'s glyphs, by character index. |-| [`<sequence>`](./sequences.md) | **Sequential group** | Track container for back-to-back clips; positions are explicit. |-| [`<captions>`](./captions.md) | **Caption node** | Transcribes the enclosing scene's audio. |-| [`<adjustmentLayer>`](./adjustment-layer.md) | **Adjustment layer** | Draws nothing; its transform composes onto the clip directly below it, for as long as its own clip lasts. |-| [`<solidPaint>`](./paints.md) | **Solid paint** | Paint child. |-| [`<linearGradientPaint>` / `<radialGradientPaint>`](./paints.md) | **Gradient paint** | Paint child; takes `<colorStop>` children. |-| [`<colorStop>`](./paints.md) | **Gradient color stop** | Valid only inside gradient paints. |-| [`<html>`](./html.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. |--A `<rect>` 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).+camelCase composition elements map 1:1 onto entities. Lowercase DOM vocabulary is valid only inside [`<html>`](./html.md) content.++## Structure++| Element | What it is |+| ------- | ---------- |+| [`<stage>`](./stage.md) | The infinite canvas, and the only valid root. Holds `<scene>` children, and loose nodes parked beside them. |+| [`<scene>`](./scene.md) | A clipped, playable frame; owns the timeline its children sit on. Only under `<stage>`, never nested. |+| [`<group>`](./group.md) | Container with a transform; auto-fits its box and its span from its children. No size and no fill of its own. |+| [`<sequence>`](./sequences.md) | Track-like container for back-to-back clips, and where [transitions](./transitions.md) are declared. No transform of its own. |++## Nodes++| Element | What it is |+| ------- | ---------- |+| [`<rect>`](./rect.md) | A rectangle. Takes paints, strokes, shadows and effects. With `mask` it clips its parent instead of drawing. |+| [`<text>`](./text.md) | Text; its children are the glyphs. Sizes itself to them unless given a box. |+| [`<textRange>`](./text.md#textrange) | A style override over a run of the parent `<text>`'s glyphs, by character index. |+| [`<video>`](./video.md) | A video clip: a rect whose intrinsic paint is the media `src` names. |+| [`<image>`](./image.md) | A picture: a rect whose intrinsic paint is the media `src` names. |+| [`<audio>`](./audio.md) | A clip with a sound and no picture; on the canvas, a waveform box. |+| [`<captions>`](./captions.md) | A styled, timed transcript of the enclosing scene (or of a transcript file). |+| [`<adjustmentLayer>`](./adjustment-layer.md) | Draws nothing; its transform composes onto the clip directly below it, for as long as its own clip lasts. |+| [`<html>`](./html.md) | A rect whose paint is real, reactive HTML drawn into the box by the browser. |+| [`<surface>`](./surface-paint.md) | A rect whose paint is a canvas your `ref` draws into, sampled every frame. |++## Paints++Children of a node, stacked in document order over its intrinsic fill. See [paints.md](./paints.md).++| Element | What it is |+| ------- | ---------- |+| `<solidPaint>` | A solid color; what the `fill` prop is shorthand for. |+| `<linearGradientPaint>` / `<radialGradientPaint>` | A gradient; takes `<colorStop>` children. |+| `<colorStop>` | One gradient stop. Valid only inside a gradient paint. |+| `<imagePaint>` / `<videoPaint>` | Media painted into another element's box — a rect or a text filled with a picture. |+| [`<htmlPaint>`](./html.md) | The paint form of `<html>`. |+| [`<surfacePaint>`](./surface-paint.md) | The paint form of `<surface>`. |+| [`<shaderPaint>`](./shader-paint.md) | A WGSL fragment shader over the media paint below it, or procedural where there is none. |++## Styles and motion++Sub-entity children of the node (or paint) that holds them. See [styles.md](./styles.md), [animations.md](./animations.md), [keyframes.md](./keyframes.md).++| Element | What it is |+| ------- | ---------- |+| `<stroke>` | An outline of the parent's box or glyphs. Several stack. |+| `<shadow>` | A drop shadow beneath the parent's silhouette. Several stack. |+| `<effect>` | A CSS-style filter over the parent's rendered pixels. Several stack. |+| `<animation>` | One preset in/out animation of the node holding it. |+| `<keyframeTrack>` | The keyframes of one prop of the element holding it. |+| `<keyframe>` | One keyframe of the track holding it. |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- Coordinates are **pixels relative to the parent's box**, origin top-left. No percentages, no layout keywords; explicit numbers until the layout engine lands.-- **Every element's box defaults to its parent's box**: `x` and `y` default to `0`, `width` and `height` default to the parent's size (the JSX analog of `position: absolute; inset: 0`). The scene's box is its required `width`×`height`.+- `x` and `y` default to `0`. **Size defaults are per element**, not inherited from the parent:++| Element | Default box |+| ------- | ----------- |+| `<video>`, `<image>`, `<adjustmentLayer>` | 1920 × 1080 |+| `<scene>` | required — the frame's own size |+| `<rect>`, `<html>`, `<surface>` | 100 × 100 |+| `<audio>` | 500 × 150 (the waveform box on the canvas) |+| `<rect mask>` | 500 × 500 |+| `<text>` | fits its glyphs |+| `<captions>` | the preset's — it lays out the caption block against the scene's frame |+| `<group>`, `<sequence>` | fits its children |++- A `<text>` given neither `width` nor `height` sizes itself to what it says; giving it either fixes the box and wraps into it.+- `<group>` and `<sequence>` never take a size: theirs is the union of their children's.- How media pixels map into the box is controlled by `objectFit` (default `"cover"`), never by the box itself. A generated asset's placeholder therefore always has a definite size, even before the asset exists.## Common props-All visual elements accept:+Every node accepts:| Prop | Type | Default | Meaning || ---- | ---- | ------- | ------- |-| `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 `<rect>` 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. |+| `id` | `string` | stamped | How the element is addressed — by the editor writing back to it, by `dapi capture`, by [`syncTo`](./audio-sync.md). Written into your source if you leave it out (see [module.md](./module.md#ids)). |+| `ref` | `SceneNode` variable or `(node: SceneNode) => void` | none | SolidJS-style ref; receives the element's node when it is created. For `<surface>`/`<surfacePaint>` the node's `element` is the backing canvas (see [surface-paint.md](./surface-paint.md)). |+| `name` | `string` | none | Human-readable node name; what labels the node in the editor. || `x`, `y` | `number` | `0` | Position relative to the parent, px. |-| `offsetX`, `offsetY` | `number` | `0` | Render-time translation on top of `x`/`y`, px; moves the drawn content without changing the layout box. Subpixel values are kept. |-| `width`, `height` | `number` | parent size | Box size, px. |+| `offsetX`, `offsetY` | `number` | `0` | Render-time translation on top of `x`/`y`, px; moves the drawn content without changing the layout box (the channel the slide animations drive). Subpixel values are kept. |+| `width`, `height` | `number` | per element | Box size, px — see the table above. || `rotation` | `number` | `0` | Rotation in degrees. |-| `opacity` | `number` | `1` | `0`-`1`. |+| `scale` | `number` | `1` | Uniform scale about the box origin. Overrides `scaleX`/`scaleY` while set. |+| `scaleX`, `scaleY` | `number` | `1` | Per-axis scale. |+| `opacity` | `number` | `1` | `0`–`1`; out-of-range values clamp, like CSS. || `cornerRadius` | `number` | `0` | Uniform corner radius, px. || `cornerRadiusTopLeft`, `cornerRadiusTopRight`, `cornerRadiusBottomRight`, `cornerRadiusBottomLeft` | `number` | `cornerRadius` | Per-corner radius, px; a corner without one takes `cornerRadius`, so `cornerRadius={20} cornerRadiusTopLeft={0}` rounds three corners. |+| `blendMode` | `BlendMode` | `"sourceOver"` | How the element composites over what is below it: the canvas blend modes, camelCase — `multiply`, `screen`, `overlay`, `darken`, `lighten`, `colorDodge`, `colorBurn`, `hardLight`, `softLight`, `difference`, `exclusion`, `hue`, `saturation`, `color`, `luminosity`. |+| `hidden` | `boolean` | absent | Excludes the element from rendering (and its audio from the mix) without removing it: it keeps its place in the timeline and its children. || `start`, `end`, `sourceIn`, `sourceOut` | `Time` | see [timing.md](./timing.md) | Temporal placement. |+| `playbackRate` | `number` | `1` | Speed multiplier for the node's local time (see [timing.md](./timing.md#playback-rate)). || `transition` | `TransitionSpec \| null` | none | Transition into the next clip; direct children of `<sequence>` only (see [transitions.md](./transitions.md)). |-Numeric props are animated by `<keyframeTrack>` children (see [keyframes.md](./keyframes.md)); preset in/out effects are `<animation>` children (see [animations.md](./animations.md)).+Props are animated by [`<keyframeTrack>`](./keyframes.md) children naming them; preset in/out effects are [`<animation>`](./animations.md) children. No prop takes keyframes inline.++### Editor state++Three more props are written by the editor and read back on the next mount. They are not part of the composition — nothing rendered or exported depends on them — but the source is the document, so a row resized in the timeline has nowhere else to be remembered:++| Prop | Type | Meaning |+| ---- | ---- | ------- |+| `selected` | `boolean` | Whether the editor has the element selected. Absent means not. |+| `clipHeight` | `number` | Height of the element's row in the timeline, px. Absent means the common row height. |+| `expanded` | `boolean` | Whether the timeline shows the element's keyframe rows below its clip. Absent means collapsed. |+Write them or delete them freely; the editor rewrites its own.diff --git a/reference/jsx/errors.md b/reference/jsx/errors.mdindex 613ea6ae..3dc92067 100644--- a/reference/jsx/errors.md+++ b/reference/jsx/errors.md@@ -4,16 +4,29 @@ 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. 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. |+| **Compile** (syntax, an unresolved import, a PascalCase composition tag, a control-flow component with no import) | A "Project failed to compile" toast, with the compiler's message; also on the app console ([`dapi logs`](../logs.md)) | Nothing is remounted. The canvas keeps the last good render, so a project in the middle of an edit is never blanked. |+| **Evaluate / mount** (a throw at module scope or during render, a root that is not `<stage>`, a tag the host does not know, an element parented into its own subtree) | A "Project failed to render" toast with the thrown message | The half-built document is disposed — **nothing is left behind** — and the previous render stays on the canvas. |+| **Source resolution** (a path that does not exist, an unreachable URL, a per-model constraint on `aspectRatio` / `duration` / a feature flag, a caption with no audible audio in its scene) | The element on the canvas, and `generations` in [`dapi context`](../context.md) | Per element, not per mount: everything else stays mounted and playable. The element stops showing its generating state and is left without a paint, carrying the reason — see below. |-Runtime errors are mapped back to the source via inline sourcemaps produced at compile time.+Runtime errors are reported against the compiled module. Since types are stripped rather than checked, run `npx tsc --noEmit` in the project folder to catch what the compile will not.++## Failed sources++A failed **generation** is written back into your file as the element's `error` prop:++```tsx+<image src={generate.image({ prompt: "a red fox" })} error="Model refused the prompt" />+```++That is deliberate, and it is what keeps a refused or impossible generation from being run — or paid for — again by every reopen of the project. An element holding an `error` is not resolved a second time, and nothing in the editor takes the prop off silently.++**Removing the `error` attribute is what asks for the run again**, and it is the only thing that does. Not another take, not another prompt.++Only generations are written down this way: a load that failed is cheap to try again, and an asset that has since been put back should simply load. An element rendered inside a `<For>` is left alone too — writing a prop to one iteration would mean unrolling the loop into the file, which is not a change to make behind your back over a generation that failed.## Blank or partial `<html>` content in captures-A mount that looks right in the viewport but captures black, frozen, or partially missing frames is almost always one of four things — check them in this order:+A composition that looks right in the viewport but captures black, frozen, or partially missing frames is almost always one of four things — check them in this order:1. **A stateful animation seek.** GSAP records a tween's start values at the tween's *first* render, and captures/exports sample frames out of order — so a tween whose target was written to outside the timeline before its first render bakes that mutated state in as its starting values and replays it at every subsequent frame. Symptom: deterministic but *order-dependent* wrong frames — the same time renders when requested first and comes out wrong when requested after a later frame. See the caveat in [html.md](./html.md): give tweens explicit start values with `fromTo`, never write to or reset tween targets between seeks, and derive capture-critical values statelessly from `time()`.2. **`scale()` on a large or clipped subtree.** The rasterizer renders these as empty (see [html.md limitations](./html.md#requirements-and-limitations)). Symptom: one wrapper's entire subtree missing at every sampled time while siblings render. Fix: translate/opacity animation; `scale` only on small content-sized leaves without inner clips.diff --git a/reference/jsx/generate.md b/reference/jsx/generate.mdindex 19e2df8c..fbffedbc 100644--- a/reference/jsx/generate.md+++ b/reference/jsx/generate.md@@ -1,6 +1,6 @@# Generated assets-Assets that don't exist yet are **declared as values** with the `generate` namespace from `@diffusionstudio/jsx`. A declaration returns an **`AssetRef`** that is passed wherever a source is expected (`src`, `startFrame`, `endFrame`, `refs`). This makes generative content declarative: the project describes the asset it wants and the editor produces it on mount.+Assets that don't exist yet are **declared as values** with the `generate` namespace from `@diffusionstudio/jsx`. A declaration returns an **`AssetRef`** that is passed wherever a source is expected (`src`, `startFrame`, `endFrame`, `refs`). This makes generative content declarative: the project describes the asset it wants and the app produces it on mount.```tsximport { generate } from "@diffusionstudio/jsx";@@ -22,15 +22,19 @@ const heroMotion = generate.video({export default function Project() {return (- <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} />- </rect>+ <stage background="#161616">+ <scene 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>+ </stage>);}```-Declarations are **pure**: calling `generate.*` registers a spec and returns a ref; no generation starts until [commit](./README.md#pipeline). A ref that is never used by a mounted element (directly or as an input to another asset) is dropped. Declarations may live at module scope or inside components.+Declarations are **pure**: calling `generate.*` validates its options and returns a ref; nothing is requested until an element carrying it mounts. A ref that is never used by a mounted element (directly or as an input to another asset) is never generated. Declarations may live at module scope or inside components.++Generation is **asynchronous and non-blocking**: the element is on the canvas immediately, showing a generating state, and its paint attaches when the asset lands. [`dapi context`](../context.md) reports where each one stands — generating, failed with the reason, or done with the library path it landed as — and a declaration that fails leaves its element carrying an [`error`](./errors.md#failed-sources).## Declaration options@@ -78,4 +82,6 @@ generate.audio(opts: {## Caching and idempotency-Generation is long-running and consumes credits, so results are **cached by content**: a key derived from the fully-resolved spec (`type`, `model`, `prompt`, resolved references, `seed`, …). Within a session, re-running an unchanged project reuses cached assets instead of regenerating, and two declarations with identical specs collapse to a single asset; changing any option produces a new asset. Set `seed` to make a spec reproducible. Finished generations are stored in the project's library under `generated/` with their spec key, so the cache survives app restarts; deleting the asset from the library regenerates it on the next mount.+Generation is long-running and consumes credits, so results are **cached by content**: a key derived from the fully-resolved spec — `type`, `model`, `prompt`, the resolved ids of any references, `seed`, and the rest of the options, with the defaults filled in. Re-mounting an unchanged project reuses cached assets instead of regenerating, two declarations with identical specs collapse to a single asset, and identical concurrent declarations share one request; changing any option produces a new asset. Set `seed` to make a spec reproducible.++Finished generations are stored in the project's library under `generated/` with their spec key, so the cache survives app restarts — and a save that only touched an unrelated part of the file regenerates nothing. Deleting the asset from the library regenerates it on the next mount.diff --git a/reference/jsx/group.md b/reference/jsx/group.mdindex cf80c4cb..7d5643f8 100644--- a/reference/jsx/group.md+++ b/reference/jsx/group.md@@ -1,6 +1,6 @@# `<group>`-A container with a transform but no dimensions of its own: a group derives its box from its children, and they are positioned relative to it.+A container with a transform but no box of its own: a group derives its bounds from its children, and they are positioned relative to it.```tsx<group x={100} y={100}>@@ -10,4 +10,16 @@ A container with a transform but no dimensions of its own: a group derives its b## Props-A group takes only **transform** (`x`, `y`, `rotation`, `opacity`) and **timing** (`start`, `end`) props (see [common props](./elements.md#common-props) and [timing.md](./timing.md)). It has no `fill` and no explicit `width` / `height`, and takes no [paint children](./paints.md): its size is auto-fit from its children. When timing is omitted, a group spans its children in time as well (see [timing.md](./timing.md)).+A group takes the [common](./elements.md#common-props) **transform** (`x`, `y`, `offsetX`, `offsetY`, `rotation`, `scale`, `scaleX`, `scaleY`, `opacity`), **composite** (`blendMode`, `hidden`) and **timing** (`start`, `end`) props.++It has **no `fill`, no `width` and no `height`**, and takes no [paint children](./paints.md): its box is the union of its children's. `<effect>`, `<animation>` and `<keyframeTrack>` children are valid — an effect on a group filters the group as a whole.++## Timing++A group with no `end` of its own **spans its children**: it begins where the earliest one begins and ends where the last one ends, and follows them as they move. Give it an `end` and it trims them instead — children outside the window do not play. See [timing.md](./timing.md).++An empty group, having nothing to span, falls back to the 16-second default.++## Grouping and ungrouping++Groups are what the editor's group action creates and what its ungroup action takes apart, so a group written by hand and one made on the canvas are the same element. A [`<sequence>`](./sequences.md) is a group with the non-overlap invariant added and its own transform taken away.diff --git a/reference/jsx/html.md b/reference/jsx/html.mdindex 60cd9d84..b17ecd20 100644--- a/reference/jsx/html.md+++ b/reference/jsx/html.md@@ -1,6 +1,6 @@# `<html>`-An element whose children are **real HTML**: the browser lays them out at the element's box size and the result is drawn into the box via the [html-in-canvas](https://github.com/WICG/html-in-canvas) API. `dapi` always drives the Diffusion Studio Electron app, which ships with this API enabled, so `<html>` is always available — reach for it liberally. It is the recommended way to build motion graphics, overlays, and any UI-heavy content: styled cards, tables, code blocks, flex/grid layouts — anything painful to assemble from `<rect>` and `<text>`.+An element whose children are **real HTML**: the browser lays them out at the element's box size and the result is drawn into the box via the [html-in-canvas](https://github.com/WICG/html-in-canvas) API. The Diffusion Studio app ships with this API enabled, so `<html>` is always available — reach for it liberally. It is the recommended way to build motion graphics, overlays, and any UI-heavy content: styled cards, tables, code blocks, flex/grid layouts — anything painful to assemble from `<rect>` and `<text>`.Driving the markup with a [GSAP](https://gsap.com) timeline is **recommended** — it keeps the animation frame-accurate: build the timeline paused, then `seek` it from the [`useTicker`](./lifecycle.md#useticker) playhead so it follows scrubbing and exports rather than the wall clock. GSAP works in seconds, so the playhead feeds `seek` directly.@@ -26,15 +26,17 @@ export default function Intro() {createEffect(() => tl.seek(time()));return (- <rect scene="intro" width={800} height={120}>- <html x={50} y={5} width={700} height={110} cornerRadius={24} end={32}>- <div style={`display:flex;align-items:center;gap:16px;height:100%;- background:#111;color:#fff;font:500 40px Inter;padding:0 32px;`}>- <span ref={index} style="color:#7c9cff;">01</span>- <span ref={label}>Introduction</span>- </div>- </html>- </rect>+ <stage>+ <scene name="Intro" width={800} height={120}>+ <html x={50} y={5} width={700} height={110} cornerRadius={24} end={32}>+ <div style={`display:flex;align-items:center;gap:16px;height:100%;+ background:#111;color:#fff;font:500 40px Inter;padding:0 32px;`}>+ <span ref={index} style="color:#7c9cff;">01</span>+ <span ref={label}>Introduction</span>+ </div>+ </html>+ </scene>+ </stage>);}```@@ -45,7 +47,7 @@ The `<html>` box carries all [common props](./elements.md#common-props). Its pai## Reactivity-The 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` stays live, so the graph keeps running and `useTicker` or timers can drive the markup:+The 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 mounted project stays live, so the graph keeps running and `useTicker` or timers can drive the markup:```tsxconst [count, setCount] = createSignal(0);@@ -72,11 +74,13 @@ Like all paints, `<htmlPaint>` stacks with siblings in document order and clips## Persistence and export-The compiled module is persisted with the document: on reload, export, and `dapi capture` the engine re-executes it and rebuilds the DOM content in that context. Exports wait for the browser's rendering update before sampling each frame, so the drawn HTML appears in the output; ticker-driven signals follow the playhead and animate frame-accurately. This assumes the module's structure is deterministic (`Math.random()`/`Date.now()` must not decide the shape of the tree).+The module is re-executed in every context: on reload, export, and [`dapi capture`](../capture.md) the engine re-executes it and rebuilds the DOM content in that context. Exports wait for the browser's rendering update before sampling each frame, so the drawn HTML appears in the output; ticker-driven signals follow the playhead and animate frame-accurately. This assumes the module's structure is deterministic (`Math.random()`/`Date.now()` must not decide the shape of the tree).## Requirements and limitations-- `<audio>` and `<video>` tags are rejected: media doesn't play under a paint host. Use the [`<audio>`](./audio.md) and [`<video>`](./video.md) composition elements, which own playback and the timeline.+- `<audio>` and `<video>` tags are rejected: media doesn't play under a paint host. Use the [`<audio>`](./audio.md) and [`<video>`](./video.md) composition elements, which own playback and the timeline. `<canvas>` is rejected too — its pixels don't survive the rasterization; use [`<surface>`](./surface-paint.md).+- **Composition elements cannot appear inside HTML content, and DOM elements cannot appear outside it.** Both are errors at mount, naming which way round it went.+- Pointer and media event handlers on the DOM children are ignored: the subtree is rasterized into the canvas, not interacted with. Styles, classes, attributes, `innerHTML` and `textContent` all apply and are reactive.- **`<html>` is sourceless, so with no `end` it defaults to a 16-second duration and disappears after 16 s** — a silent cutoff with no error.- **`scale()` blanks large or clipped subtrees in captures.** The rasterizer renders a subtree as *empty* when a CSS `scale()` sits on a large wrapper (e.g. a full-box `width:100%;height:100%` group), or when any `overflow:hidden` clip lives beneath a scaled ancestor. Animate entrances, holds, and exits with `translate` and `opacity`; use `scale` only on small, content-sized leaf elements with no clipping inside them. A masked text reveal (`overflow:hidden` + inner `translateY`) is fine as long as no ancestor of the mask carries a transform.- **Nested fractional `opacity` blanks the subtree in captures.** A child with `opacity` < 1 under an ancestor whose `opacity` is also < 1 makes the rasterizer drop the ancestor's entire subtree for exactly as long as the ancestor's opacity is fractional — so a wrapper fading in over children styled with `opacity: 0.7` is blank mid-fade and pops in the moment the fade lands on 1. Keep animated `opacity` to a single level of the tree: dim static children with alpha colors (`rgba()` / `hsl()` alpha) instead of `opacity`.diff --git a/reference/jsx/image.md b/reference/jsx/image.mdindex 8e37eb8d..8008a2a7 100644--- a/reference/jsx/image.md+++ b/reference/jsx/image.md@@ -1,9 +1,9 @@# `<image>`-An image. `src` resolves to an image asset (see [media.md](./media.md)).+A picture: a rect whose intrinsic paint is the media `src` names (see [media.md](./media.md)).```tsx-<image src="/photo.jpg" x={40} y={40} width={200} height={112} />+<image src="stills/photo.jpg" x={40} y={40} width={200} height={112} />```## Props@@ -14,7 +14,11 @@ All [common props](./elements.md#common-props), plus:| ---- | ---- | ------- | ------- || `src` | `string \| AssetRef` | **required** | See [media.md](./media.md). || `objectFit` | `"cover" \| "contain" \| "fill"` | `"cover"` | How the source maps into the box. |+| `frameRate` | `number` | `30` | Frames per second for a `src` naming a directory of numbered frames, which plays on `<image>` as footage does (see [media.md](./media.md#image-sequences)). Nothing for a still to read. || `removeBackground` | `boolean` | `false` | Cuts the subject out, leaving the rest transparent (see [media.md](./media.md#source-modifiers)). || `upscale` | `number` | `1` | Resolution multiplier; enlarges the source, not the box (see [media.md](./media.md#source-modifiers)). |+| `error` | `string` | none | Why this element's source never became an asset (see [errors.md](./errors.md#failed-sources)). |-A paint child draws over the media paint created by `src` (see [paints.md](./paints.md)); a [`<shaderPaint>`](./shader-paint.md) child instead post-processes it, so the image renders through the shader.+Without `width`/`height` the box is 1920×1080. A still has no duration to fit, so with no `end` it takes the 16-second default (see [timing.md](./timing.md)).++A paint child draws over the media paint created by `src` (see [paints.md](./paints.md)); a [`<shaderPaint>`](./shader-paint.md) child instead post-processes it, so the image renders through the shader. `<stroke>`, `<shadow>`, `<effect>`, `<animation>` and `<keyframeTrack>` children are valid too.diff --git a/reference/jsx/keyframes.md b/reference/jsx/keyframes.mdindex 45cf9a94..8508b89e 100644--- a/reference/jsx/keyframes.md+++ b/reference/jsx/keyframes.md@@ -3,7 +3,7 @@A `<keyframeTrack>` animates one prop of the element holding it over the node's local time; its `<keyframe>` children are the values along the way:```tsx-<image src="/photo.jpg" start={0} end={5}>+<image src="stills/photo.jpg" start={0} end={5}><keyframeTrack property="x"><keyframe time={0} value={-400} easing="easeOut" /><keyframe time={1} value={200} />@@ -20,7 +20,7 @@ A `<keyframeTrack>` animates one prop of the element holding it over the node's| `<keyframeTrack>` | `property` (**required**) | The prop of the holding element it drives, by name. One track per prop. || `<keyframe>` | `time` (**required**), `value` (**required**), `easing` | One keyframe: node-local time in any [time format](./timing.md#time-formats), the value at that time (a number, or any CSS color on a `color` track), and the easing into the next keyframe. |-Animatable props (`property`): `x`, `y`, `offsetX`, `offsetY`, `width`, `height`, `rotation`, `scale`, `scaleX`, `scaleY`, `opacity`, `cornerRadius`, `cornerRadiusTopLeft`, `cornerRadiusTopRight`, `cornerRadiusBottomRight`, `cornerRadiusBottomLeft`, `volume`, `color`, `offset`, `blur`, `value`. Whose prop is the track's holder's: a track under a [paint or color stop](./paints.md) animates the paint (`color`, `opacity`, `offset`), under a `<stroke>` the stroke (`width` is the line width), under a `<shadow>` the shadow (`blur`, `offsetX`, `offsetY`), under an `<effect>` its `value`. For preset in/out effects (fade, slides, text reveals, ...) use [`<animation>`](./animations.md) instead.+Animatable props (`property`): `x`, `y`, `offsetX`, `offsetY`, `width`, `height`, `rotation`, `scale`, `scaleX`, `scaleY`, `opacity`, `cornerRadius`, `cornerRadiusTopLeft`, `cornerRadiusTopRight`, `cornerRadiusBottomRight`, `cornerRadiusBottomLeft`, `volume`, `color`, `offset`, `blur`, `value`. Whose prop is the track's holder's: a track under a [paint or color stop](./paints.md) animates the paint (`color`, `opacity`, `offset`), and one under a [`<stroke>`, `<shadow>` or `<effect>`](./styles.md) that style's own — `width` is a stroke's line width, `blur`/`offsetX`/`offsetY` a shadow's, `value` an effect's amount. For preset in/out effects (fade, slides, text reveals, ...) use [`<animation>`](./animations.md) instead.## Semanticsdiff --git a/reference/jsx/lifecycle.md b/reference/jsx/lifecycle.mdindex b3927397..9534299c 100644--- a/reference/jsx/lifecycle.md+++ b/reference/jsx/lifecycle.md@@ -2,15 +2,23 @@## A mount stays live-After `dapi mount` returns, its reactive graph keeps running: signals, effects, timers, and [`useTicker`](#useticker) keep driving the mounted entities. Updates land in the document immediately (not as undo steps) — prop writes, conditional inserts and removals (`<Show>`, `<For>`), text, and reactive `src` swaps including `generate.*`. The materialized nodes are ordinary editable entities; asset generation is owned by the engine. `syncTo` and new `<captions>` are mount-only and throw if changed after commit. A run ends when a later `mount` claims one of its root keys (swapping the entities and disposing the old graph) or the project closes.+Opening a project compiles the entry file and renders it into the document. After that the reactive graph **keeps running**: signals, effects, timers, and [`useTicker`](#useticker) keep driving the mounted entities for as long as the project is open. Updates land in the document immediately — prop writes, conditional inserts and removals (`<Show>`, `<For>`), text, and reactive `src` swaps including `generate.*`. The materialized nodes are ordinary editable entities; asset resolution is owned by the engine.-The compiled module is persisted with the document and re-executed in every context: reload rebuilds the graph and its runtime hosts (`<surface>`/`<html>`), and export and capture drive the ticker across the frames they render. Re-execution binds to the existing entities rather than re-authoring them, so hand-edits survive; it rewrites only the props your effects animate. This requires the module's structure to be deterministic: `Math.random()` and `Date.now()` must not decide element counts or `<Show>`/`<For>` branches (using them inside an effect is fine).+A save re-runs the pipeline. The old mount is disposed and the new render takes the stage, the way reloading a page rebuilds it — scenes are rebuilt rather than accumulated, and the entities the previous render owned go with it. A compile error changes nothing: the last good render stays on the canvas and the failure is reported.-`node insert` renders into an existing parent and is not persisted or kept live.+The compiled bundle is remembered with the project, so the next open puts the last known render on the canvas while the compile chews through the sources; whichever finishes first shows, and the fresh compile replaces it either way.++**Export and capture re-execute the module** in a world of their own — the same source, a fresh mount, the ticker driven across the frames being rendered. That is what makes a live composition reproducible rather than ephemeral, and it requires the module's structure to be deterministic: `Math.random()` and `Date.now()` must not decide element counts or `<Show>`/`<For>` branches. Using them inside an effect, or inside a draw callback, is fine.++## Edits come back++The other direction is the point of the [`id`](./module.md#ids) on every element: a rect dragged on the canvas, a clip trimmed on the timeline, a keyframe moved, a line retyped — each lands as a prop on the element that authored it, written into your file. So the two directions do not fight: hand edits and canvas edits are edits to the same document.++What the editor writes is what it changed. Elements it inserted or moved are written as new JSX; an element rendered inside a `<For>` is unrolled into one element per iteration first, since a single element cannot hold one iteration's value.## `useTicker`-A mount can subscribe to the project's timeline instead of reaching for wall-clock timers:+A project can subscribe to the timeline instead of reaching for wall-clock timers:```tsximport { useTicker } from "@diffusionstudio/jsx";@@ -18,15 +26,17 @@ import { useTicker } from "@diffusionstudio/jsx";export default function Project() {const { time, frame } = useTicker();return (- <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" />- </rect>+ <stage>+ <scene name="HUD" width={1920} height={1080}>+ <text width={600} height={100} fontSize={80} color="#FFFFFF">{`frame ${frame()}`}</text>+ <rect x={860 + Math.sin(time() * 4) * 200} y={490} width={100} height={100} fill="#f43" />+ </scene>+ </stage>);}```-Call it in a component body. It returns accessors for the playhead of the scene the mount's root lives in (or is):+Call it in a component body. It returns accessors for the playhead of the scene the mount renders into:| Accessor | Value || -------- | ----- |@@ -35,30 +45,8 @@ Call it in a component body. It returns accessors for the playhead of the scene| `delta()` | Seconds advanced since the previous engine tick: 0 while paused, negative on a backward scrub or loop || `playing()` | Whether the scene is playing |-The values respect play, pause, scrubbing, looping, and playback speed, which wall-clock timers do not. Each accessor only propagates when its value changes, so a paused scene re-runs nothing and `frame()` consumers update at most once per frame. Ticker-driven drawing follows the playhead in the editor and in exports and captures; wall-clock timers (`setInterval`, `requestAnimationFrame`) render live but do not appear in exports.--## `useFile`+The values respect play, pause, scrubbing, looping, and playback speed, which wall-clock timers do not. Each accessor only propagates when its value changes, so a paused scene re-runs nothing and `frame()` consumers update at most once per frame. Ticker-driven drawing follows the playhead in the editor **and in exports and captures**; wall-clock timers (`setInterval`, `requestAnimationFrame`) render live but do not appear in the output.-Resolves a [`src`](./media.md) (path, asset id, URL, or a `generate.*` ref) to its `File`, so effects can read the raw bytes: draw a library image onto a [`<surface>`](./surface-paint.md), parse a data file, decode audio. The module is sandboxed and can't fetch a path or asset id itself, so resolution goes through the host, exactly as `src` does.--```tsx-import { createSignal, createEffect } from "solid-js";-import { useFile } from "@diffusionstudio/jsx";--function Logo() {- const [canvas, setCanvas] = createSignal<HTMLCanvasElement>();- const [file] = useFile("/assets/logo.png"); // path, asset id, URL, or AssetRef-- createEffect(async () => {- const el = canvas();- const f = file(); // undefined until it resolves- if (!el || !f) return;- const ctx = el.getContext("2d")!;- ctx.drawImage(await createImageBitmap(f), 0, 0, el.width, el.height);- });-- return <surface ref={setCanvas} width={640} height={360} />;-}-```+`useTicker` is host-bound: it only works inside a mounted project, and throws with a message saying so anywhere else.-Returns Solid's `createResource` tuple unchanged: `[file, { mutate, refetch }]`. The `file` accessor reads `undefined` until resolution completes, then the `File`; `file.loading` and `file.error` report progress and failure. Resolution is async (fetch a URL, read a path or library asset, await a `generate.*` ref); export and capture await the first resolution before rendering frame 0. A `node insert` has no surviving effect to consume the result.+> **Status:** the runtime document does not provide a timeline clock yet, so `useTicker()` currently throws inside a mounted project too (`useTicker: this host does not provide a timeline clock`) — and, being called in a component body, takes the whole mount with it. Until it is wired, drive motion with [`<animation>`](./animations.md) and [`<keyframeTrack>`](./keyframes.md), which run on the same playhead.diff --git a/reference/jsx/media.md b/reference/jsx/media.mdindex 2db5a1e5..229f8db3 100644--- a/reference/jsx/media.md+++ b/reference/jsx/media.md@@ -1,12 +1,26 @@# Media source resolution-`src` (on [`<video>`](./video.md), [`<image>`](./image.md), [`<audio>`](./audio.md), and the DOM [`<img>`](./html.md#images) inside `<html>`) accepts:+`src` (on [`<video>`](./video.md), [`<image>`](./image.md), [`<audio>`](./audio.md), the [media paints](./paints.md#media-paints), [`<captions>`](./captions.md), and the DOM [`<img>`](./html.md#images) inside `<html>`) accepts:-- **Library path**: e.g. `"b-roll/drone.mp4"`, an asset of the project's library by its path there (folder + name, as shown in the asset panel and recorded in the project's `assets.yml`). The preferred form: it is portable and survives the file being relinked. A directory of numbered images is an image sequence and plays on `<video>` or `<image>`.+- **Library path**: e.g. `"b-roll/drone.mp4"`, an asset of the project's library by its path there (folder + name, as shown in the asset panel and recorded in the project's `assets.yml`). The preferred form: it is portable and survives the file being relinked.- **Asset id**: e.g. `"9f3a2c1d7e4b8a01"`, the content hash of a library asset (`assets.yml` lists them).- **Global path**: e.g. `"/Movies/video.mp4"`, resolved against the user's OS. Not added to the library.- **Remote URL**: e.g. `"https://my.videoarchive.com/audio/clip.wav"`, fetched on mount. Not added to the library.-- **`AssetRef`**: the value returned by a `generate.*` declaration (see [generate.md](./generate.md)). The node is inserted immediately as a placeholder and its paint is attached once the asset has generated; the result is stored under the library's `generated/` folder.+- **`AssetRef`**: the value returned by a `generate.*` declaration (see [generate.md](./generate.md)). The node is mounted immediately as a placeholder and its paint is attached once the asset has generated; the result is stored under the library's `generated/` folder.++Resolution is **asynchronous and non-blocking**: the element is on the canvas as soon as the project mounts, showing a generating state until its source lands. A source that never lands leaves the element carrying an [`error`](./errors.md#failed-sources).++## Image sequences++A path naming a **directory of numbered frames** (`shot_001.png`, `shot_002.png`, …) is an image sequence, and plays on `<video>` or `<image>` exactly as footage does.++A folder of pictures has a count, not a duration, so `frameRate` is what says how long the clip runs: 600 frames at 24 is 25 seconds, at 60 is 10. Default 30. There is nothing for encoded video or a still to read it against — a file carries its own rate, and neither has a frame count to divide.++```tsx+<video src="renders/beauty-pass" frameRate={24} width={1920} height={1080} />+```++`frameRate` is not [`playbackRate`](./timing.md#playback-rate), which retimes a source against the timeline whatever its natural speed is; this is what that natural speed *is*. It is unrelated to the composition's own frame rate, which the export sets.## Source modifiers@@ -16,7 +30,7 @@| ---- | -- | ------- || `removeBackground` | `<image>` | Cuts the subject out, leaving the rest transparent. || `upscale` | both | Resolution multiplier — `upscale={2}` asks for twice the pixels. Enlarges the source, not the box. |-| `addAudio` | `<video>` | Scores footage that has no sound. |+| `addAudio` | `<video>` | Scores footage that has no sound. Independent of `volume` and `muted`, which mix whatever track the clip ends up with. |```tsx<image src="footage/fox.png" removeBackground upscale={2} width={800} height={450} />@@ -28,8 +42,6 @@ Modifiers compose with declarations: `<image src={generate.image({ prompt: "a re## The library-A project's assets are recorded in `assets.yml` next to its entry file: for each asset, its library `path`, where its bytes are (`source`: the absolute path of a file imported from disk — imports never move or copy files — or a project-relative path under `assets/` for files the app produced), and what it was found to be. Folders are virtual: they are the prefixes of the paths. Renaming or moving an asset in the panel rewrites the `src` props that named it. Files placed under `assets/` by hand are taken into the library on the next load.--An `<img>` additionally takes a `data:` or `blob:` URL, which goes to the browser as it is.+A project's assets are recorded in `assets.yml` next to its entry file: for each asset, its library `path`, where its bytes are (`source`: the absolute path of a file imported from disk — imports never move or copy files — or a project-relative path under `assets/` for files the app produced), and what it was found to be. Folders are listed too, so an empty one survives a reload. Renaming or moving an asset in the panel rewrites the `src` props that named it. Files placed under `assets/` by hand are taken into the library on the next load.-To read a source's raw bytes inside an effect (rather than mount it as a node), pass the same input to [`useFile`](./lifecycle.md#usefile), which resolves it to a `File`.+An `<img>` inside [`<html>`](./html.md) additionally takes a `data:` or `blob:` URL, which goes to the browser as it is.diff --git a/reference/jsx/module.md b/reference/jsx/module.mdindex b8a986c3..8b7eb58a 100644--- a/reference/jsx/module.md+++ b/reference/jsx/module.md@@ -1,29 +1,65 @@# Project module-The entry file is a standard Solid component module:+A project is a folder: a real npm package whose entry file (`package.json` `main`, `index.tsx` by default) default-exports a Solid component rendering a [`<stage>`](./stage.md).```tsxexport default function Project() {return (- <rect scene="intro" name="Intro" fill="black" width={1920} height={1080}>- {/* ... */}- </rect>+ <stage background="#161616">+ <scene name="Intro" width={1920} height={1080} fill="black">+ {/* ... */}+ </scene>+ </stage>);}```+The component receives no props. [`dapi open <dir>`](../open.md) opens the folder — creating it, and an `index.tsx` holding an empty stage, if it is not a project yet.-The component receives no props; which document node each rendered root maps onto is declared in the JSX itself via `key` (see [roots.md](./roots.md)).+## The folder++`open` writes as little as it takes to make a folder a project, and the rest of the scaffold appears lazily. What ends up there:++| Path | What it is |+| ---- | ---------- |+| `index.tsx` | The entry. Its default export renders the composition. |+| `package.json` | The project record: `projectId` (its identity, kept across renames), `displayName`, `main`, and the dapi commands as scripts. |+| `tsconfig.json` | Types for the composition tags, through `jsxImportSource`. |+| `assets.yml` | The asset library (see [media.md](./media.md#the-library)). |+| `assets/` | Files the app produced itself, generations under `assets/generated/`. Media imported from elsewhere on disk is linked where it lies, never copied. |+| `cache/` | Derived data (thumbnails, waveforms). Disposable. |+| `AGENTS.md` | The agent entry point: what to read in `.diffusion/docs/`. |+| `.diffusion/docs/` | App-owned copy of this reference and the examples, stamped with the app version and regenerated when it changes. Read it, never edit it. |++Everything but `.diffusion/` is written once and is yours from then on.++## Ids++Every composition element carries an `id`, and the app stamps one onto every element that lacks it before each compile — written back into your source, six base-36 characters, unique within its file:++```tsx+<rect id="k3f9x1" x={40} y={40} width={640} height={360} fill="#FF0055" />+```++An id is what makes an element addressable: it is how an entity is traced back to the JSX that produced it, so a change made on the canvas can be written to the element it came from, and it is what [`dapi capture`](../capture.md) takes to render one node. It is also how elements point at each other within a render — [`syncTo`](./audio-sync.md) names the id of the clip it aligns against.++**Ids are yours to write.** Any string is valid, and `id="hero"` is worth more to read than anything minted. The stamp only fills in elements that have none, so renaming one by hand is safe. Ids are stripped at compile time and never reach the runtime as a prop; what survives is the stamp that carries them.## Module environmentImports resolve by category:-- **Host modules** (marked external at compile time, resolved in-app so the project shares the editor's reactive runtime): `solid-js`, `solid-js/store`, `@diffusionstudio/jsx`. These must be the editor's own instance and never come from anywhere else.+- **Host modules** (marked external at compile time, resolved in-app so the project shares the editor's reactive runtime): `solid-js`, `solid-js/store`, `@diffusionstudio/jsx`. These must be the editor's own instance and never come from anywhere else — a project's own `node_modules` copy is types only.- **Userland packages** — any other bare specifier (`three`, `gsap`, `d3-scale`, …). A project folder is a real npm package, so these work as they normally do: install one (`npm i three`) and esbuild resolves it from the project's `node_modules` and bundles it into the compiled module, subpath imports and `exports` maps included. Nothing is installed for you and there is no CDN fallback — a specifier that does not resolve fails the compile with `Could not resolve "three"`, and the canvas keeps the last good render. Libraries must be browser-compatible (no Node builtins); sources under `node_modules` skip the JSX transform, so a package must ship compiled JavaScript rather than raw JSX.- **Local imports**: relative/absolute paths (`./helper`, local JSON) are resolved on disk and bundled. Static `https://…` imports are **not** supported — they survive bundling as a require the renderer cannot satisfy, and fail at mount.-- The module executes **inside the editor process**, unsandboxed. This is local tooling with a local trust model, the same trust as running the CLI itself. Only effects made through the JSX runtime are part of the document (and its undo history); anything else the module does is unsupported.-- Solid's control flow (`<For>`, `<Show>`, `<Index>`, `<Switch>`) and primitives (`createSignal`, `createMemo`, …) are fully available during mount. See [lifecycle.md](./lifecycle.md) for what happens after mount.+- The module executes **inside the editor process**, unsandboxed. This is local tooling with a local trust model, the same trust as running the app itself. Only effects made through the JSX runtime are part of the document; anything else the module does is unsupported.+- Solid's control flow (`<For>`, `<Show>`, `<Index>`, `<Switch>`) and primitives (`createSignal`, `createMemo`, …) are fully available. Control-flow components need their import (`import { For } from "solid-js"`); the compile says so by name when one is missing. See [lifecycle.md](./lifecycle.md) for what happens after mount.++## Tag spelling++Composition elements are **camelCase** intrinsics (`<rect>`, `<keyframeTrack>`, `<linearGradientPaint>`); the compile canonicalizes them to the components the renderer receives. Writing one PascalCase (`<Rect>`) is a compile error naming the tag you meant.++Lowercase DOM tags are the vocabulary for [`<html>`](./html.md) content. Three names belong to both vocabularies — `rect`, `text`, `image` — and resolve lexically: inside an SVG container (`<svg>`, `<g>`, `<defs>`, …) they are SVG content, everywhere else composition elements.## Types and tooling@@ -38,6 +74,6 @@ Imports resolve by category:}```-The CLI does not typecheck; types are stripped at compile time. Run `tsc --noEmit` in the project folder for type safety.+The compile does not typecheck; types are stripped. Run `npx tsc --noEmit` in the project folder for type safety.Installing a userland package gives it both its runtime code and its types. A package that ships no declarations of its own needs its `@types/…` alongside it (`npm i -D @types/three`). `@diffusionstudio/jsx` and `solid-js` are the exception: they are declared in the scaffolded `package.json` for types only, since the compiler always keeps them external and the running composition uses the app's own instance.diff --git a/reference/jsx/paints.md b/reference/jsx/paints.mdindex bbbd5b7a..d0aadcf4 100644--- a/reference/jsx/paints.md+++ b/reference/jsx/paints.md@@ -11,16 +11,34 @@ 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>`, `<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`.+Paint elements are valid inside any filled visual element (`<rect>`, `<text>`, `<textRange>`, `<video>`, `<image>`, `<html>`, `<surface>`, and a `<scene>`); 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 || ------- | ----- | ------- || `<solidPaint>` | `color` (**required**), `opacity` | Solid fill; equivalent to the `fill` prop. || `<linearGradientPaint>` | `rotation`, `opacity` | Linear gradient across the parent's box; `rotation` in degrees, `0` = left to right. || `<radialGradientPaint>` | `rotation`, `opacity` | Radial gradient centered in the parent's box. |-| `<colorStop>` | `offset` (**required**, `0`-`1`), `color` (**required**), `opacity` | Gradient color stop. Valid only inside gradient paints, which take no other children. |+| `<colorStop>` | `offset` (**required**, `0`–`1`), `color` (**required**), `opacity` | Gradient color stop. Valid only inside gradient paints, which take no other children. |+| `<imagePaint>` / `<videoPaint>` | `src` (**required**), `objectFit`, `frameRate`, `opacity` | Media painted into the parent's box — see below. || [`<htmlPaint>`](./html.md) | `opacity`, HTML children | Reactive HTML laid out and drawn into the parent's box (flagged Chromium API). `<html>` is shorthand for a `<rect>` carrying one. |-| [`<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. |+| [`<surfacePaint>`](./surface-paint.md) | `opacity`, `ref` | A canvas your `ref` 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) | `wgsl` (**required**), `uniforms`, `opacity` | 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 with `<keyframeTrack>` children (see [keyframes.md](./keyframes.md)), so gradients can animate. Paints have no spatial or timing props and cannot be stage roots.+Every paint also takes `blendMode` and `hidden`, which mean on a paint what they mean on a node.++Colors accept any CSS color; alpha is ignored (use `opacity`). `color`, `opacity`, and `offset` are animatable with `<keyframeTrack>` children (see [keyframes.md](./keyframes.md)), so gradients can animate. Paints have no spatial or timing props of their own and cannot be roots.++## Media paints++`<imagePaint>` and `<videoPaint>` are the same media a [`<video>`](./video.md) or [`<image>`](./image.md) element is, as a paint child: they fill *something else* with it, so a rect or a text can be filled with a picture.++```tsx+<text fontSize={220} fontWeight="bold" width={1920} textAlign="center">+ OCEAN+ <videoPaint src="b-roll/waves.mp4" objectFit="cover" />+</text>+```++They take `src` exactly as the elements do (see [media.md](./media.md)), plus `objectFit` and `frameRate`. Which tag it is only says what the source is expected to be: the paint follows what the `src` turns out to name, so a frames directory plays under either.++The media paint a `<video>` or `<image>` element creates from its own `src` is *intrinsic* — it sits at the bottom of that element's paint stack, beneath any paint child. Timing stays the element's; a media paint has none of its own.diff --git a/reference/jsx/rect.md b/reference/jsx/rect.mdindex 298d130b..785da1b5 100644--- a/reference/jsx/rect.md+++ b/reference/jsx/rect.md@@ -1,6 +1,6 @@# `<rect>`-A filled rectangle. Takes [paint children](./paints.md), plus `<stroke>`, `<shadow>`, `<effect>`, `<animation>` and `<keyframeTrack>`; use `cornerRadius` for rounded corners.+A rectangle. Takes [paint children](./paints.md), plus [`<stroke>`, `<shadow>`, `<effect>`](./styles.md), [`<animation>`](./animations.md) and [`<keyframeTrack>`](./keyframes.md); use `cornerRadius` for rounded corners.```tsx<rect x={40} y={40} width={640} height={360} cornerRadius={24} fill="#FF0055" />@@ -12,9 +12,11 @@ All [common props](./elements.md#common-props), plus:| Prop | Type | Default | Meaning || ---- | ---- | ------- | ------- |-| `fill` | `string` | light gray | Any CSS color; alpha is ignored (use `opacity`). Shorthand for a solid paint child. |+| `fill` | `string` | none | Any CSS color; alpha is ignored (use `opacity`). Shorthand for a solid paint child, drawn beneath any paint children. || `mask` | `boolean` | `false` | Makes the rect a mask of its parent instead of a drawn shape — see below. |+A rect with neither `fill` nor a paint child draws nothing; it is still a box that clips masks, carries children and takes up its place in the timeline. Without `width`/`height` a rect is 100×100.+## MasksA `<rect mask>` clips the element holding it instead of drawing: the parent's fills, strokes, shadows and children show only inside the rect's box. It is still a rect — same coordinates, `cornerRadius`, transform and timing — so it can be moved, rotated, keyframed and animated independently of what it clips: a mask whose `width` is keyframed across a text is a wipe, a mask that starts later than its parent is a reveal.diff --git a/reference/jsx/roots.md b/reference/jsx/roots.mddeleted file mode 100644index b4a8fd74..00000000--- a/reference/jsx/roots.md+++ /dev/null@@ -1,22 +0,0 @@-# 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. **Only a [scene](./scene.md) is mountable as a root** (a `<rect>` promoted with the `scene` property); every top-level element declares its identity with `scene`.--| Identity | Contract |-| -------- | -------- |-| `<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. |--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 stage root.--`dapi node insert` 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**: a scene root has no `x`/`y`, and a project describes content, not canvas arrangement.--- **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` to frame them explicitly.diff --git a/reference/jsx/scene.md b/reference/jsx/scene.mdindex 65af0bb2..9f535e6e 100644--- a/reference/jsx/scene.md+++ b/reference/jsx/scene.md@@ -1,29 +1,42 @@-# Scenes (the `scene` property)+# `<scene>`-A scene is the composition root: it clips its children to `width`×`height`. The **`scene` property promotes a `<rect>`** to a mount root. The property's value is the scene's identity across mounts. Scenes are valid **only** at the document top level; the first rendered root becomes the active scene (see [roots.md](./roots.md)).+A scene is the **clipped, playable frame** a composition is made in, and the only element allowed directly under [`<stage>`](./stage.md). It clips its children to `width`×`height` and **owns the timeline they are placed on**, so it takes no timing of its own — nothing outside a scene has a clock to be placed against.```tsx-// A scene: a rectangle promoted to the root.-<rect scene="intro" name="Intro" fill="black" width={1920} height={1080}>- {/* children */}-</rect>+<scene name="Intro" width={1920} height={1080} fill="black">+ {/* children, placed on this scene's timeline */}+</scene>```-## 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:+## Props| Prop | Type | Default | Meaning || ---- | ---- | ------- | ------- |-| `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) |+| `width`, `height` | `number` | **required** | Composition size in pixels — the frame that is rendered and exported. Required by the type; a scene that somehow reaches the runtime without them is 1920×1080. |+| `x`, `y` | `number` | `0` | Where the frame sits on the infinite canvas. Scenes without one all sit at the origin. |+| `fill` | `string` | none | Background fill, any CSS color; alpha is ignored. A scene without one is transparent, and exports with alpha. |+| `name` | `string` | none | Human-readable node name; what labels the scene in the editor. Recommended. |+| `volume` | `number` | `0` | Decibels on the scene's own bus, which everything in it mixes into — the master fader. `0` = unity, negative attenuates (`-6` ≈ half as loud), `-Infinity` = silence. A clip's own `volume` composes with this one. |+| `active` | `boolean` | absent | Whether this is the scene the playhead, the timeline and `dapi capture` operate on. |+| `workarea` | `[in, out] \| null` | `null` | The stretch of the scene that plays and exports, in any [time format](./timing.md#time-formats). |+| `selected` | `boolean` | absent | Whether the editor has the scene selected. |++A scene also takes paints as children, exactly as a `<rect>` does (see [paints.md](./paints.md)); `fill` is the shorthand for a solid one.++## Editor state in the source++`active`, `selected`, `x` and `y` are editor concerns rather than part of the composition, but they live in the file for the same reason [`<stage>`](./stage.md)'s `camera` does: the source is the document, so a scene dragged or clicked on the canvas has nowhere else to be written back to. The editor writes the bare attribute and removes it again.++Two rules the runtime holds for `active`: **at most one element is active**, and **only a root** — a direct child of `<stage>` — can be. A nested `active` is dropped, and when a file names more than one the last one rendered wins.++`workarea` is the exception among them: it is carried by the source the way `active` is (the timeline's brackets have nowhere else to go), but it is read wherever the file is, so **what it says is what comes out of a render**. Playback loops within it, and an export is of it and nothing else.++```tsx+// Renders seconds 2–8 of the scene, and nothing else.+<scene name="Cut" width={1920} height={1080} workarea={[2, 8]}>{/* ... */}</scene>+```## Constraints-- **`<rect>` only.** `scene` on any other element is an error.-- **No placement.** A scene root will be auto positioned+- **Only under `<stage>`.** Scenes do not nest. Other elements may sit at root level beside them (see [stage.md](./stage.md)), but only a scene has a timeline, and only a scene renders.+- **No timing props.** A scene is the clock its children are placed against; it spans whatever they span.diff --git a/reference/jsx/sequences.md b/reference/jsx/sequences.mdindex 059f178e..e6eb2622 100644--- a/reference/jsx/sequences.md+++ b/reference/jsx/sequences.md@@ -1,15 +1,15 @@# Sequences-`<sequence>` is a track-like container for back-to-back clips. It carries no timing of its own and **does not position its children at mount** — give each child an explicit `start` (see [timing.md](./timing.md)). What it adds is clip-to-clip [transitions](./transitions.md) on direct children, and, in the editor, a non-overlapping invariant: dragging or regrouping clips trims or removes whatever they land on.+`<sequence>` is a track-like container for back-to-back clips. It carries no transform and no timing of its own, and **does not position its children at mount** — give each child an explicit `start` (see [timing.md](./timing.md)). What it adds is clip-to-clip [transitions](./transitions.md) on direct children, and, in the editor, a non-overlapping invariant: dragging or regrouping clips trims or removes whatever they land on.```tsx-<sequence>+<sequence name="A-roll">{/* timeline 0–12 */}- <video src="/Movies/intro.mp4" width={1920} height={1080} start={0} end={12} />+ <video src="b-roll/intro.mp4" width={1920} height={1080} start={0} end={12} />{/* timeline 12–2:30, source from 5 s */}- <video src="/Movies/main.mp4" width={1920} height={1080} start={12} end="02:30" sourceIn={5} />+ <video src="b-roll/main.mp4" width={1920} height={1080} start={12} end="02:30" sourceIn={5} />{/* from 2:30, plays to its natural end */}- <video src="/Movies/outro.mp4" width={1920} height={1080} start="02:30" />+ <video src="b-roll/outro.mp4" width={1920} height={1080} start="02:30" /></sequence>```@@ -19,8 +19,8 @@ The next clip's `start` must match the previous clip's on-timeline end — its `| Prop | Type | Meaning || ---- | ---- | ------- |-| `name` | `string` | Human-readable node name. |+| `id`, `name` | `string` | Address and label. |-Purely structural; nothing else.+Purely structural; nothing else. A sequence is a [group](./group.md) with its spatial identity taken away — `x`, `y`, `rotation` and `scale` on one are ignored, and its children are positioned against whatever contains the sequence. Like a group it **spans its children in time**, so it needs no timing of its own.-Direct children of a sequence may declare a [`transition`](./transitions.md) into the following clip.+Direct children of a sequence may declare a [`transition`](./transitions.md) into the following clip. An [`<adjustmentLayer>`](./adjustment-layer.md) inside a sequence acts on what sits below the *sequence*, not on the clip before it inside one.diff --git a/reference/jsx/shader-paint.md b/reference/jsx/shader-paint.mdindex 0125ab60..965ca2a0 100644--- a/reference/jsx/shader-paint.md+++ b/reference/jsx/shader-paint.md@@ -13,7 +13,7 @@ const INVERT = /* wgsl */ `}`;-<video src="/Movies/clip.mp4" width={1920} height={1080}>+<video src="b-roll/clip.mp4" width={1920} height={1080}><shaderPaint wgsl={INVERT} /></video>```@@ -78,27 +78,25 @@ Value mapping: a `number` binds to `f32`, an array of 2-4 numbers to `vec2f`/`ve| ---- | ---- | ------- | ------- || `wgsl` | `string` | **required** | Fragment-stage WGSL source (entry point `main`). || `uniforms` | `Record<string, number \| number[] \| string>` | `{}` | Values for the shader's `@group(1)` uniforms, by name. |-| `opacity` | `Animatable<number>` | `1` | Paint opacity, `0`-`1`. |+| `opacity` | `number` | `1` | Paint opacity, `0`–`1`. |Like all paints it stacks with siblings in document order; `<shaderPaint>` takes no children.-## Patching+## Changing a shader live-Shader paints are live entities: find the paint id under the element with `dapi node tree`, then patch `dapi node patch`:+Shader paints are live entities, and a project stays mounted, so a `uniforms` value driven by a signal is a hot update — no recompile, no reload:-```bash-# tweak parameters (hot update, no recompile)-dapi node patch '[{ "id": 42, "uniforms": { "strength": 2 } }]'+```tsx+const [strength, setStrength] = createSignal(0.5);-# swap the shader (async recompile; the media shows unshaded until it lands)-dapi node patch '[{ "id": 42, "wgsl": "..." }]'+<shaderPaint wgsl={TINT} uniforms={{ strength: strength(), tint: "#FF0055" }} />```-Attach one to an existing video with `dapi node insert` (`node insert <videoId> '<shaderPaint wgsl={...} />'`).+Swapping `wgsl` recompiles the pipeline asynchronously; the media shows unshaded until the new one lands. Editing the file itself remounts the project, which is the same thing at a coarser grain.## Errors and limitations-- WGSL compile errors are reported on the app console (`dapi logs`) with line numbers relative to your source; the paint renders as passthrough until a fix lands.+- WGSL compile errors are reported on the app console ([`dapi logs`](../logs.md)) with line numbers relative to your source; the paint renders as passthrough until a fix lands.- Pipeline compilation is asynchronous. Live playback may show the first frames unshaded; exports wait for compilation, so rendered output is always shaded.- One shader reads one media paint; shaders do not chain and do not read solid/gradient/html/surface paints or the composited stack (over those the shader runs procedurally and stacks on top).- For full custom pipelines (own vertex stage, WebGL, three.js) use [`<surface>`](./surface-paint.md), which owns its canvas outright.diff --git a/reference/jsx/stage.md b/reference/jsx/stage.mdnew file mode 100644index 00000000..68d1e3b5--- /dev/null+++ b/reference/jsx/stage.md@@ -0,0 +1,35 @@+# `<stage>`++The infinite canvas every project renders into: the **root element**, and the only thing that may be one. It holds [`<scene>`](./scene.md) children — one per frame you cut in — and, alongside them, loose nodes parked on the canvas.++```tsx+export default function Project() {+ return (+ <stage background="#161616">+ <scene name="Intro" width={1920} height={1080} fill="black">{/* ... */}</scene>+ <scene name="Outro" x={2120} width={1920} height={1080} fill="black">{/* ... */}</scene>+ </stage>+ );+}+```++A node at root level is material rather than composition: a generated clip that has not been cut into a scene yet, a reference still lying about. It draws on the canvas and can be dragged, selected and inspected, but it has no scene's clock to be placed against, so it plays nothing and exports nowhere — that is what moving it into a scene is for. It is where the editor puts what it generates.++The stage is a **singleton**: it is the canvas already on screen rather than something the project creates, so a project spelling `<stage>` addresses the one that is there. One mount per world — a save disposes the running mount before the new one takes the stage, and the scenes it owned go with it.++## Props++| Prop | Type | Default | Meaning |+| ---- | ---- | ------- | ------- |+| `background` | `string` | `#161616` | Canvas color behind the scenes, any CSS color. Not part of a render: it is what surrounds the frame, not what is in it. |+| `camera` | `[a, b, c, d, e, f]` | `[1, 0, 0, 1, 0, 0]` | The editor's viewport when the project is opened, as a 2D affine matrix in the order CSS `matrix()` and canvas `setTransform` take: `a`/`d` scale, `b`/`c` skew, `e`/`f` translate. |++Both are editor state rather than composition: nothing rendered or exported depends on either, but the source is the document, so a panned canvas has nowhere else to be written back to. A project that never says where to look opens at the origin, at 100%.++The stage takes no timing, no transform and no paints — it is not a node, it is where the nodes are.++## Canvas placement++A root's place on the canvas is its own `x`/`y`, in the same document space the camera matrix moves through. Roots that do not say where they sit all sit at the origin, on top of each other; give each after the first an `x` clear of the ones before it, as the example above does.++Which scene the playhead, the timeline and [`dapi capture`](../capture.md) are pointed at is a scene's `active`, not the stage's business. At most one scene carries it, and only a direct child of `<stage>` can.diff --git a/reference/jsx/styles.md b/reference/jsx/styles.mdnew file mode 100644index 00000000..4e10e161--- /dev/null+++ b/reference/jsx/styles.md@@ -0,0 +1,69 @@+# Strokes, shadows and effects++Three sub-entity children a node takes alongside its [paints](./paints.md): an outline of its shape, a shadow beneath it, and a filter over what it drew. Each stacks in document order, several of a kind are allowed, and each carries an `id` of its own — the editor writes a changed value back to the element that spelled it, and it is copied with its node.++```tsx+<text fontSize={140} fontWeight="bold" color="#FFFFFF" width={1920} textAlign="center">+ Headline+ <stroke color="#000000" width={6} join="round" />+ <shadow color="#000000" blur={24} offsetY={8} opacity={0.6} />+</text>+```++## `<stroke>`++An outline of the parent's box — or of its glyphs, on a `<text>` or a `<textRange>`. `color`/`opacity` are its paint, the rest its line style.++| Prop | Type | Default | Meaning |+| ---- | ---- | ------- | ------- |+| `color` | `string` | **required** | Any CSS color; alpha is ignored (use `opacity`). |+| `width` | `number` | `1` | Line width, px. A `width` [keyframe track](./keyframes.md) under a stroke drives this, not a box. |+| `join` | `"miter" \| "round" \| "bevel"` | `"miter"` | How the stroke turns corners. |+| `cap` | `"butt" \| "round" \| "square"` | `"butt"` | How the stroke ends open paths (text glyphs). |+| `miterLimit` | `number` | `10` | Miter length limit, as a ratio of the width. |+| `opacity` | `number` | `1` | `0`–`1`. |+| `blendMode` | `BlendMode` | `"sourceOver"` | How the stroke composites. |+| `hidden` | `boolean` | absent | Excludes the stroke without removing it. |++## `<shadow>`++A drop shadow beneath the parent's silhouette: a blurred, offset copy of it in `color`.++| Prop | Type | Default | Meaning |+| ---- | ---- | ------- | ------- |+| `color` | `string` | **required** | Any CSS color. |+| `blur` | `number` | `0` | Blur radius, px. |+| `offsetX`, `offsetY` | `number` | `0` | Where the shadow sits relative to the silhouette, px. |+| `opacity` | `number` | `1` | `0`–`1`. |+| `hidden` | `boolean` | absent | Excludes the shadow without removing it. |++## `<effect>`++A filter over the parent's **rendered pixels** — its fills, strokes and children together. On a [`<group>`](./group.md) that is the group as a whole; on a [`<video>`](./video.md) it is the frame after the media is drawn.++| Prop | Type | Default | Meaning |+| ---- | ---- | ------- | ------- |+| `type` | `EffectType` | **required** | Which filter to apply, see below. |+| `value` | `number` | **required** | The amount. |+| `hidden` | `boolean` | absent | Excludes the effect without removing it. |++| `type` | `value` means |+| ------ | ------------- |+| `"blur"` | Radius in px. |+| `"hueRotate"` | Degrees. |+| `"brightness"`, `"contrast"`, `"grayscale"`, `"invert"`, `"saturate"`, `"sepia"` | Amount, `0`–`1`. |++```tsx+<image src="stills/photo.jpg" width={1920} height={1080}>+ <effect type="blur" value={0}>+ <keyframeTrack property="value">+ <keyframe time={0} value={40} easing="easeOut" />+ <keyframe time={1.5} value={0} />+ </keyframeTrack>+ </effect>+</image>+```++## Animating them++All three take [`<keyframeTrack>`](./keyframes.md) children, and the track's `property` is read against its holder: `width` under a `<stroke>` is the line width, `blur` / `offsetX` / `offsetY` under a `<shadow>` are the shadow's, `value` under an `<effect>` is its amount, and `color` / `opacity` are whatever the holder's are.diff --git a/reference/jsx/surface-paint.md b/reference/jsx/surface-paint.mdindex 8c2f41ee..123e7039 100644--- a/reference/jsx/surface-paint.md+++ b/reference/jsx/surface-paint.md@@ -1,45 +1,55 @@# `<surface>`-An element backed by a **canvas you draw yourself**. The `ref` callback receives a detached `HTMLCanvasElement`; draw into it with any context type — 2d, webgl, webgpu — and the engine samples the bitmap every frame, stretching it into the parent geometry's box. Use it for procedural graphics and for external renderers (three.js, p5, chart libraries) that want to own a canvas.+An element backed by a **canvas you draw yourself**. The `ref` receives the element's `SceneNode`, whose `element` is that canvas; draw into it with any context type — 2d, webgl, webgpu — and the engine samples the bitmap every frame, stretching it into the parent geometry's box. Use it for procedural graphics and for external renderers (three.js, p5, chart libraries) that want to own a canvas.```tsx-<surface x={40} y={40} width={640} height={360} cornerRadius={24}- ref={(el) => {- const ctx = el.getContext("2d")!;- ctx.fillStyle = "#111";- ctx.fillRect(0, 0, el.width, el.height);- ctx.strokeStyle = "#7c9cff";- ctx.lineWidth = 6;- ctx.strokeRect(40, 40, el.width - 80, el.height - 80);- }} />+let surfaceRef: SceneNode | undefined;++onMount(() => {+ const el = surfaceRef!.element!;+ const ctx = el.getContext("2d")!;+ ctx.fillStyle = "#111";+ ctx.fillRect(0, 0, el.width, el.height);+ ctx.strokeStyle = "#7c9cff";+ ctx.lineWidth = 6;+ ctx.strokeRect(40, 40, el.width - 80, el.height - 80);+});++<surface x={40} y={40} width={640} height={360} cornerRadius={24} ref={surfaceRef} />````<surfacePaint ref={...}>` is the paint child form, valid inside any filled visual element; `<surface>` is a rectangle carrying one, with all [common props](./elements.md#common-props).-## The ref and the bitmap+## The ref and the canvas-- The ref runs **once**, when the paint materializes, inside the mount's reactive owner — `createEffect`, `onCleanup`, and [`useTicker`](./lifecycle.md) all work inside it.-- **Callback form only** (`ref={(el) => ...}`). Variable refs (`let el; <surface ref={el} />`) receive a renderer-internal node, not the canvas.-- The bitmap is allocated at the element's box size (in composition pixels) **before the ref runs**; after that the engine never touches it — the bitmap belongs to your code. Resize it yourself (`el.width = ...`, or an external renderer's own API) for higher resolution; the bitmap is stretched into the box every frame either way, so an animated box scales pixels rather than re-rasterizing.+```ts+import type { SceneNode } from "@diffusionstudio/jsx";+// { readonly element: HTMLCanvasElement | null, tag, props, parent, children }+```++- The ref receives the element's **`SceneNode`**, as every ref does. `element` is the paint's backing canvas: on the geometry for a `<surface>` (whose surface is its intrinsic paint), on the paint sub-entity for a `<surfacePaint>`; null where the host has no DOM.+- **Both SolidJS ref forms work.** The variable form `let surfaceRef: SceneNode | undefined;` + `ref={surfaceRef}` assigns the node when the element is created — read it in `onMount` or an effect, which run after the (synchronous) mount. The callback form `ref={(surface) => …}` runs **once**, when the element is created, inside the mount's reactive owner — `createEffect`, `onCleanup`, and [`useTicker`](./lifecycle.md#useticker) all work inside it.+- The canvas is allocated with the element and **sized to the holder's `width`/`height`** in composition pixels. A same-size set is a no-op, so a `renderer.setSize` of your own is not clobbered; resize the bitmap yourself for higher resolution, since it is stretched into the box every frame either way, and an animated box scales pixels rather than re-rasterizing.- Unlike [`<html>`](./html.md) no flagged browser API is needed, and the sampled pixels render in exports.## Reactivity-The engine samples the canvas every frame, so anything you draw shows up on the next frame. A `dapi mount` stays live, so the reactive graph keeps running: create effects in the ref to redraw from signals, or drive frame-accurate motion from the ticker's composition time:+The engine samples the canvas every frame, so anything you draw shows up on the next frame. A mount stays live, so the reactive graph keeps running: redraw from signals inside effects, or drive frame-accurate motion from the ticker's composition time:```tsx-<surface width={400} height={400}- ref={(el) => {- const ctx = el.getContext("2d")!;- const { time } = useTicker();- createEffect(() => {- ctx.clearRect(0, 0, el.width, el.height);- ctx.beginPath();- ctx.arc(200, 200, 60 + 40 * Math.sin(time() * Math.PI), 0, Math.PI * 2);- ctx.fillStyle = "#44dd88";- ctx.fill();- });- }} />+const { time } = useTicker();+let surfaceRef: SceneNode | undefined;++createEffect(() => {+ const ctx = surfaceRef!.element!.getContext("2d")!;+ ctx.clearRect(0, 0, 400, 400);+ ctx.beginPath();+ ctx.arc(200, 200, 60 + 40 * Math.sin(time() * Math.PI), 0, Math.PI * 2);+ ctx.fillStyle = "#44dd88";+ ctx.fill();+});++<surface width={400} height={400} ref={surfaceRef} />```Because the ticker follows the playhead, ticker-driven drawing stays frame-accurate in exports too; wall-clock timers (`setInterval`, `requestAnimationFrame`) render live but ignore the playhead.@@ -49,21 +59,25 @@ Because the ticker follows the playhead, ticker-driven drawing stays frame-accurAnything that accepts an existing canvas plugs in directly; a detached canvas is fine for WebGL:```tsx-<surface width={1280} height={720}- ref={(el) => {- const renderer = new THREE.WebGLRenderer({- canvas: el,- preserveDrawingBuffer: true,- alpha: true,- });- renderer.setSize(el.width, el.height, false);- const { time } = useTicker();- createEffect(() => {- mesh.rotation.y = time() * 0.5;- renderer.render(scene, camera);- });- onCleanup(() => renderer.dispose());- }} />+const { time } = useTicker();+let surfaceRef: SceneNode | undefined;++onMount(() => {+ const el = surfaceRef!.element!;+ const renderer = new THREE.WebGLRenderer({+ canvas: el,+ preserveDrawingBuffer: true,+ alpha: true,+ });+ renderer.setSize(el.width, el.height, false);+ createEffect(() => {+ mesh.rotation.y = time() * 0.5;+ renderer.render(scene, camera);+ });+ onCleanup(() => renderer.dispose());+});++<surface width={1280} height={720} ref={surfaceRef} />```- **`preserveDrawingBuffer: true` is effectively required for WebGL** — by default the drawing buffer may be cleared after presentation, so the engine's per-frame sample can read back blank.@@ -74,17 +88,17 @@ Anything that accepts an existing canvas plugs in directly; a detached canvas is| Prop | Type | Default | Meaning || ---- | ---- | ------- | ------- |-| `ref` | `(canvas: HTMLCanvasElement) => void` | **required** | Receives the backing canvas at materialization. |-| `opacity` | `Animatable<number>` | `1` | Paint opacity, `0`-`1`. |+| `ref` | `SceneNode` variable or `(surface: SceneNode) => void` | none | The [common `ref`](./elements.md#common-props); `element` on the received node is the backing canvas. |+| `opacity` | `number` | `1` | Paint opacity, `0`–`1`. |Like all paints it stacks with siblings in document order and clips to the parent's box (including `cornerRadius`). `<surfacePaint>` takes no children.## Persistence and export-The compiled module is persisted with the document, so the drawing is reproducible, not ephemeral: on reload, export, and `dapi capture` the engine re-executes it and redraws into a fresh canvas driven by that context's playhead, so ticker surfaces animate in exports. The bitmap itself is not stored; your code reproduces it. This assumes the module's structure is deterministic (`Math.random()`/`Date.now()` must not decide the shape of the tree; using them inside a draw effect is fine).+The module is re-executed in every context, so the drawing is reproducible rather than ephemeral: on reload, export, and [`dapi capture`](../capture.md) the engine re-runs your drawing code against a fresh canvas driven by that context's playhead, so ticker surfaces animate in exports. The bitmap itself is not stored; your code reproduces it. This assumes the module's structure is deterministic (`Math.random()`/`Date.now()` must not decide the shape of the tree; using them inside a draw effect is fine).## Requirements and limitations- Duplicating or copy-pasting a mounted surface yields a static copy (the drawing does not re-run for the copy); re-mount to get a fresh animated instance.- Only the `ref` attribute form on the element itself is routed; refs inside spread props are not.-- A real DOM `<canvas>` is not available inside [`<html>`](./html.md) content — its pixels don't survive the html-in-canvas rasterization. Use `<surface>` for hand-drawn graphics instead.+- A real DOM `<canvas>` is not available inside [`<html>`](./html.md) content — its pixels don't survive the html-in-canvas rasterization, and the tag is rejected. Use `<surface>` for hand-drawn graphics instead.diff --git a/reference/jsx/text.md b/reference/jsx/text.mdindex a5931db9..b93ed70e 100644--- a/reference/jsx/text.md+++ b/reference/jsx/text.md@@ -1,13 +1,15 @@# `<text>`-A text node; children become editable glyphs. Because the box defaults to the parent's box, a centered full-frame title is simply `<text textAlign="center" textBaseline="middle">…</text>`.+A text node; its children are the glyphs.```tsx-<text color="#FFFFFF" fontSize={128} fontWeight="bold" textAlign="center" textBaseline="middle">+<text color="#FFFFFF" fontSize={128} fontWeight="bold" width={1920} textAlign="center">Hello World</text>```+A `<text>` given neither `width` nor `height` **sizes itself to what it says**; giving it either fixes the box, wraps into it, and makes `textAlign` / `textBaseline` mean something. A centered full-frame title is `<text width={1920} height={1080} textAlign="center" textBaseline="middle">…</text>`.+## PropsAll [common props](./elements.md#common-props), plus:@@ -15,10 +17,10 @@ All [common props](./elements.md#common-props), plus:| Prop | Type | Default | Meaning || ---- | ---- | ------- | ------- || children | `string` (or expressions resolving to strings) | **required** | The text content, alongside any `<textRange>`, paint, `<stroke>`, `<shadow>`, `<effect>`, `<animation>` and `<keyframeTrack>` children. |-| `color` | `string` | white | The glyph color; any CSS color, alpha ignored (use `opacity`). Drawn beneath any paint children (see [paints.md](./paints.md)); animate it with a `color` [keyframe track](./keyframes.md). |-| `fontFamily` | `string` | editor default | A family available on the machine ([`dapi fonts`](../fonts.md)); see [fonts.md](./fonts.md). |-| `fontSize` | `number` | editor default | Px. |-| `fontWeight` | `number \| "normal" \| "bold"` | `"normal"` | CSS weights `100`-`900`. |+| `color` | `string` | none | The glyph color; any CSS color, alpha ignored (use `opacity`). Drawn beneath any paint children (see [paints.md](./paints.md)); animate it with a `color` [keyframe track](./keyframes.md). A text with neither `color` nor a paint child draws no glyphs. |+| `fontFamily` | `string` | `Inter` | A family available on the machine ([`dapi fonts`](../fonts.md)); see [fonts.md](./fonts.md). |+| `fontSize` | `number` | `16` | Px. |+| `fontWeight` | `number \| "normal" \| "bold"` | `"normal"` | CSS weights `100`–`900`. || `fontStyle` | `"normal" \| "italic" \| "oblique"` | `"normal"` | || `letterSpacing` | `number` | `0` | Extra space between glyphs, px; negative tightens. || `textCase` | `"original" \| "upper" \| "lower"` | `"original"` | Casing applied when drawing; the text itself stays as written. |@@ -33,7 +35,7 @@ The text-only [animation types](./animations.md) (`"appearWord"`, `"appearChar"`A style override for a run of the glyphs, a sub-entity like a paint: `start`/`end` address the run by character index into the text as written (before `textCase`), and the rest is what changes inside it. An unset font prop inherits the text's; its own `color`, paints, strokes and shadows replace the text's for those glyphs. Several stack in document order, later ones winning where they overlap. Layout (`textAlign`, `textBaseline`, `leading`) stays the text's.```tsx-<text fontSize={96} color="#FFFFFF" textAlign="center" textBaseline="middle">+<text fontSize={96} color="#FFFFFF" width={1920} textAlign="center">Ship it today<textRange start={5} end={7} color="#F43F5E" fontWeight="bold" /><textRange start={8} fontStyle="italic" letterSpacing={2}>diff --git a/reference/jsx/timing.md b/reference/jsx/timing.mdindex 3ebd0e8c..adbed9f6 100644--- a/reference/jsx/timing.md+++ b/reference/jsx/timing.md@@ -8,23 +8,45 @@ Timing splits the two independent questions a clip answers: **where it sits on t| `end` | Parent-timeline time at which the clip ends. Alternative to `sourceOut`. || `sourceIn` | Source in point: the time within the source where playback begins. Default 0; trims the head. || `sourceOut` | Source out point: the time within the source where playback ends. Defaults to the source's natural end. Alternative to `end`. |+| `playbackRate` | Speed multiplier for the node's local time, 1 = normal. See [below](#playback-rate). |++Times are **parent-relative**: a clip inside a [`<group>`](./group.md) or a [`<sequence>`](./sequences.md) is placed against that container's start, and a clip directly in a [`<scene>`](./scene.md) against the scene's timeline. Nothing outside a scene has a clock to be placed against.## Semantics-- `start` / `end` place the clip on the parent timeline. `sourceIn` / `sourceOut` select which part of the source plays. On-timeline duration always equals the played source length, so `end - start == sourceOut - sourceIn`.+- `start` / `end` place the clip on the parent timeline. `sourceIn` / `sourceOut` select which part of the source plays. The trimmed window opens at `start`, so at rate 1 the on-timeline duration equals the played source length: `end - start == sourceOut - sourceIn`.- **Trimming the source is not the same as moving the clip.** To drop part of the source you must move `sourceIn` / `sourceOut`; changing `start` alone only slides the clip along the timeline while the full source keeps playing. If the source is meant to stay aligned with something else in the scene (synced audio, a transcript, another track), advance `start` and `sourceIn` **together** — moving one without the other offsets the content instead of trimming it.-- **`end` and `sourceOut` are two spellings of the same out edge** — the clip's end in timeline time (`end`) versus source time (`sourceOut`). Set one; the last one set wins.-- Sourceless nodes (`<rect>`, `<group>`, `<text>`, `<html>`, `<surface>`) have no footage to trim, so you place them with `start` / `end` alone.+- **`end` and `sourceOut` are two spellings of the same out edge** — the clip's end in timeline time (`end`) versus source time (`sourceOut`). Set one. Set both and **the one that closes first wins**: each is a cap on the window rather than an override of the other, so a clip never runs past either.+- A source is a cap of its own: a trim past the end of the footage runs out of frames rather than holding.+- Sourceless nodes (`<rect>`, `<text>`, `<html>`, `<surface>`, `<adjustmentLayer>`) have no footage to trim, so you place them with `start` / `end` alone.- Instead of setting `start`, a media node can derive its placement from another node's audio with `syncTo` (see [audio-sync.md](./audio-sync.md)).-- If timing is omitted, a media node fits its natural duration at `start` 0, and a group auto-fits its children. A [`<sequence>`](./sequences.md) does not position its children for you: give each an explicit `start` (the next clip's `start` is the previous clip's end).-- **A sourceless _leaf_ node with no `end` defaults to a fixed 16-second duration**+- **Containers span their children.** A `<group>` or a `<sequence>` with no `end` of its own begins where its earliest child begins and ends where its last one ends, and follows them as they move. Give it an `end` and it trims them instead.+- **A media node with no timing fits its natural duration** at `start` 0.+- **A sourceless node with no `end` gets a fixed 16-second duration** — as does a still image, which has no duration of its own, and an empty container, which has nothing to span.+- A [`<sequence>`](./sequences.md) does not position its children for you: give each an explicit `start` (the next clip's `start` is the previous clip's end).> Examples:> - `<rect start={2} end={5} width={200} height={120} fill="red" />` — a rectangle on screen from timeline second 2 to 5.> - `<video start={5} sourceIn={10} sourceOut={20} />` — plays source seconds 10–20 (a 10-second clip) beginning at timeline second 5.-> - `<video start={2} end={5} sourceIn={10} />` — the same source starting at 10 s, stretched to fill the timeline window 2–5 (so it plays source 10–13).+> - `<video start={2} end={5} sourceIn={10} />` — the same source starting at 10 s, over the timeline window 2–5 (so it plays source 10–13).> - `<video start={0} sourceIn={1} />` — trims the first second off the head and places the clip at the top of the timeline.+## Playback rate++`playbackRate` scales the node's local time against its parent's: at `2`, twice as much source plays in the same stretch of timeline; at `0.5`, half. Default `1`.++It scales the window rather than replacing it, so the two spellings keep their meanings and stay consistent with each other:++```tsx+// 10 seconds of source (2–12) over 5 seconds of timeline (0–5).+<video src="b-roll/drone.mp4" start={0} sourceIn={2} sourceOut={12} playbackRate={2} />++// The same thing from the other side: the timeline window and the rate imply the out point.+<video src="b-roll/drone.mp4" start={0} end={5} sourceIn={2} playbackRate={2} />+```++Audio is retimed with the picture. Everything the node holds — its children, its keyframes, its animations — runs on the node's local clock and is retimed with it.+## Time formats```ts@@ -40,4 +62,4 @@ The canonical internal unit is frames at **30 fps**; all formats are converted o| `"MM:SS"` | `"02:30"` | Minutes and seconds. || `"HH:MM:SS"` | `"01:02:30"` | Hours, minutes, seconds. |-CLI flags documented as taking a `Time` value (e.g. `--time` on [`capture`](../capture.md) and [`media grab`](../media/grab.md)) accept the same formats.+CLI flags documented as taking a `Time` value (e.g. `--time` on [`capture`](../capture.md) and [`media grab`](../media/grab.md)) accept the same formats. Times in command **output** are plain seconds.diff --git a/reference/jsx/transitions.md b/reference/jsx/transitions.mdindex f1810402..e66ad795 100644--- a/reference/jsx/transitions.md+++ b/reference/jsx/transitions.md@@ -34,4 +34,4 @@ The editor's transition inspector options:- `duration` takes any [time format](./timing.md#time-formats) and is centered on the cut: half plays before it, half after.- A **partial value merges** into the clip's existing transition: `transition={{ duration: 2 }}` keeps the current type; `transition={{}}` applies the defaults.- **`null` removes** the clip's transition.-- Part of the shared property table: `dapi node patch` accepts `transition` with identical semantics, e.g. `--json '[{ "id": 42, "transition": { "type": "dissolve" } }]'`.+- A transition is not an element of its own: it is a prop of the outgoing clip, so it moves, trims and copies with it.diff --git a/reference/jsx/video.md b/reference/jsx/video.mdindex 54a4b834..794fa368 100644--- a/reference/jsx/video.md+++ b/reference/jsx/video.md@@ -1,9 +1,9 @@# `<video>`-A video clip. `src` resolves to a video asset (see [media.md](./media.md)); when timing is omitted, the node fits its natural duration (see [timing.md](./timing.md)).+A video clip: a rect whose intrinsic paint is the media `src` names (see [media.md](./media.md)). When timing is omitted, the node fits its natural duration (see [timing.md](./timing.md)).```tsx-<video src="/Movies/main.mp4" width={1920} height={1080} start={0} sourceIn={1} sourceOut={13} volume={-3} />+<video src="b-roll/drone.mp4" width={1920} height={1080} start={0} sourceIn={1} sourceOut={13} volume={-3} />```## Props@@ -14,10 +14,14 @@ All [common props](./elements.md#common-props), plus:| ---- | ---- | ------- | ------- || `src` | `string \| AssetRef` | **required** | See [media.md](./media.md). || `objectFit` | `"cover" \| "contain" \| "fill"` | `"cover"` | How the source maps into the box. |-| `volume` | `Animatable<number>` | `0` | Decibels: `0` = unity, negative attenuates (`-6` ≈ half as loud), `-Infinity` = silence. Not linear. |+| `frameRate` | `number` | `30` | Frames per second for a `src` naming a directory of numbered frames — the only thing that says how long such a clip runs. Nothing for encoded video to read: a file carries its own rate (see [media.md](./media.md#image-sequences)). |+| `volume` | `number` | `0` | Decibels: `0` = unity, negative attenuates (`-6` ≈ half as loud), `-Infinity` = silence. Not linear. || `muted` | `boolean` | `false` | Excludes the node's audio from the mix; independent of `volume`. |-| `syncTo` | `string` | none | Key of another element carrying audio; derives `start` by audio alignment (see [audio-sync.md](./audio-sync.md)). Mutually exclusive with `start`. |+| `syncTo` | `string` | none | `id` of another element carrying audio; derives `start` by audio alignment (see [audio-sync.md](./audio-sync.md)). Mutually exclusive with `start`. || `upscale` | `number` | `1` | Resolution multiplier; enlarges the source, not the box (see [media.md](./media.md#source-modifiers)). || `addAudio` | `boolean` | `false` | Scores footage that has no sound (see [media.md](./media.md#source-modifiers)). |+| `error` | `string` | none | Why this element's source never became an asset (see [errors.md](./errors.md#failed-sources)). |-A paint child draws over the media paint created by `src` (see [paints.md](./paints.md)); a [`<shaderPaint>`](./shader-paint.md) child instead post-processes it, so the frame renders through the shader.+Without `width`/`height` the box is 1920×1080.++A paint child draws over the media paint created by `src` (see [paints.md](./paints.md)); a [`<shaderPaint>`](./shader-paint.md) child instead post-processes it, so the frame renders through the shader. `<stroke>`, `<shadow>`, `<effect>`, `<animation>` and `<keyframeTrack>` children are valid too.