The VS Code of video editing, built for agents.
TypeScript
Refactor stage and scene components to include camera and active properties
konstantin-paulusfb241b98514c
diff --git a/apps/desktop/src/projects.ts b/apps/desktop/src/projects.tsindex 62a8f100..9621c454 100644--- a/apps/desktop/src/projects.ts+++ b/apps/desktop/src/projects.ts@@ -588,8 +588,8 @@ as a prop on the element it was authored as.\`\`\`tsxexport default function Project() {return (- <stage background="#161616">- <scene name="Intro" width={1920} height={1080} fill="black">+ <stage background="#161616" camera={[0.3, 0, 0, 0.3, 85, 150]}>+ <scene name="Intro" width={1920} height={1080} fill="black" active><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@@ -605,6 +605,12 @@ export default function Project() {- \`<stage>\` is the root, and holds one \`<scene>\` per frame you cut in. A sceneowns the timeline its children sit on; nothing outside a scene has a clock tobe placed against.+- One scene carries \`active\` — the one the playhead, the timeline and an export+ are pointed at — and the stage carries the \`camera\` the canvas opens on, a+ \`[scale, 0, 0, scale, x, y]\` matrix (\`0.3\` fits a 1920×1080 frame). Both are+ editor state: the app writes them back as the view is panned or a scene is+ clicked, but a project that ships without them opens on an empty timeline,+ looking at the corner of nothing.- Position and size are explicit, in pixels. There is no layout pass and no CSS.- \`start\` / \`end\` place a clip on that timeline, \`sourceIn\` / \`sourceOut\` choosethe part of the media that plays. Times are seconds (\`1.5\`), frames (\`45f\`) or@@ -701,6 +707,9 @@ never edit it, and trust it over memory.- Verify visually with \`npm run capture -- <id>\`: it renders a node exactlyas the viewer gets it. Do not export a video to check work.- Position and size are explicit, in pixels. There is no layout pass and no CSS.+- A composition you author from scratch marks one scene \`active\` and gives+ \`<stage>\` a \`camera\` framing it, or the project opens on an empty timeline+ with the frame off screen.- Times are seconds (\`1.5\`), frames (\`"45f"\`), or \`"MM:SS"\`.- Types are stripped at compile time, never checked: run \`npx tsc --noEmit\`.`;diff --git a/examples/01-basics.tsx b/examples/01-basics.tsxindex 43668f87..b5761d27 100644--- a/examples/01-basics.tsx+++ b/examples/01-basics.tsx@@ -48,8 +48,8 @@ function Title(props: { text: string; start: Time; end: Time }) {export default function Basics() {return (- <stage>- <scene name="Basics" width={1920} height={1080} fill="black">+ <stage camera={[0.3, 0, 0, 0.3, 85, 150]}>+ <scene name="Basics" width={1920} height={1080} fill="black" active><sequence name="A-roll"><videosrc={`${VIDEOS}/sintel-short.mp4`}diff --git a/examples/02-genai.tsx b/examples/02-genai.tsxindex dd403587..1bd95863 100644--- a/examples/02-genai.tsx+++ b/examples/02-genai.tsx@@ -57,8 +57,8 @@ const ambience = generate.audio({export default function GenAi() {return (- <stage>- <scene name="GenAI" width={1920} height={1080} fill="black">+ <stage camera={[0.3, 0, 0, 0.3, 85, 150]}>+ <scene name="GenAI" width={1920} height={1080} fill="black" active><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} />diff --git a/examples/03-ticker.tsx b/examples/03-ticker.tsxindex 059be215..dbff834b 100644--- a/examples/03-ticker.tsx+++ b/examples/03-ticker.tsx@@ -26,8 +26,8 @@ export default function Ticker() {const eased = createMemo(() => 0.5 - Math.cos(angle()) / 2); // 0..1..0, smoothreturn (- <stage>- <scene name="Ticker" width={1920} height={1080} fill="#101014">+ <stage camera={[0.3, 0, 0, 0.3, 85, 150]}>+ <scene name="Ticker" width={1920} height={1080} fill="#101014" active>{/* center square: rotation and corner radius both derive from progress */}<rectx={860}diff --git a/examples/04-html-in-canvas.tsx b/examples/04-html-in-canvas.tsxindex d50f2529..13772c1c 100644--- a/examples/04-html-in-canvas.tsx+++ b/examples/04-html-in-canvas.tsx@@ -25,8 +25,8 @@ export default function PromptBox() {const cursorOn = createMemo(() => Math.floor(time() * 2) % 2 === 0);return (- <stage>- <scene name="Prompt box" width={1920} height={1080} fill="#0b0d12">+ <stage camera={[0.3, 0, 0, 0.3, 85, 150]}>+ <scene name="Prompt box" width={1920} height={1080} fill="#0b0d12" active>{/* An <html> box takes DOM children only, so the animation — acomposition element — goes on a rect carrying the same paint the<html> shorthand carries. */}diff --git a/examples/05-anime-timeline.tsx b/examples/05-anime-timeline.tsxindex c66e4a7c..d7aa0cd5 100644--- a/examples/05-anime-timeline.tsx+++ b/examples/05-anime-timeline.tsx@@ -41,8 +41,8 @@ export default function AnimeTimeline() {const hue = () => Math.round(v.card.hue);return (- <stage>- <scene name="Anime timeline" width={960} height={540} fill="#101014">+ <stage camera={[0.6, 0, 0, 0.6, 85, 150]}>+ <scene name="Anime timeline" width={960} height={540} fill="#101014" active><rectx={v.chip.x}y={v.chip.y}diff --git a/examples/06-three.tsx b/examples/06-three.tsxindex 36c7bc01..748febcd 100644--- a/examples/06-three.tsx+++ b/examples/06-three.tsx@@ -111,8 +111,8 @@ export default function ThreeHelmet() {});return (- <stage>- <scene name="Three helmet" width={960} height={540} fill="#0b0d12">+ <stage camera={[0.6, 0, 0, 0.6, 85, 150]}>+ <scene name="Three helmet" width={960} height={540} fill="#0b0d12" active><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 c2872b05..0714b5bb 100644--- a/examples/07-webgpu.tsx+++ b/examples/07-webgpu.tsx@@ -124,8 +124,8 @@ export default function WebgpuTriangle() {onCleanup(() => gpu()?.device.destroy());return (- <stage>- <scene name="WebGPU triangle" width={960} height={540} fill="#0b0d12">+ <stage camera={[0.6, 0, 0, 0.6, 85, 150]}>+ <scene name="WebGPU triangle" width={960} height={540} fill="#0b0d12" active><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 2ec976c3..534893b2 100644--- a/examples/08-shader-paint.tsx+++ b/examples/08-shader-paint.tsx@@ -37,8 +37,8 @@ const ABERRATION = /* wgsl */ `export default function ShaderPaintExample() {return (- <stage>- <scene name="Shader paint" width={1920} height={1080} fill="#000000">+ <stage camera={[0.3, 0, 0, 0.3, 85, 150]}>+ <scene name="Shader paint" width={1920} height={1080} fill="#000000" active><video src={`${VIDEOS}/sintel-short.mp4`} width={1920} height={1080}><shaderPaint wgsl={ABERRATION} uniforms={{ strength: 1.5, vignette: 0.6 }} /></video>diff --git a/packages/jsx/src/types.ts b/packages/jsx/src/types.tsindex 06b40c0f..e275667f 100644--- a/packages/jsx/src/types.ts+++ b/packages/jsx/src/types.ts@@ -420,7 +420,13 @@ export type StageProps = {* The editor's viewport when the project is opened: `[1, 0, 0, 1, 0, 0]` is* the origin at 100%. Not part of the composition — nothing rendered or* exported depends on it — so a project that never says where to look opens- * at the origin.+ * at the origin, with most of the frame off screen.+ *+ * Give every authored project one, so it opens framed on its composition:+ * `[s, 0, 0, s, x, y]` for a scene at the origin, `s` sized to fit the frame+ * in roughly 580×330 screen pixels — `[0.3, 0, 0, 0.3, 85, 150]` for+ * 1920×1080, `[0.6, 0, 0, 0.6, 85, 150]` for 960×540. The first pan or zoom+ * overwrites it, so the exact numbers do not matter.*/camera?: CameraMatrix;children?: SolidJSX.Element;@@ -446,6 +452,10 @@ export type SceneProps = IdentityProps & PositionProps & Required<SizeProps> & F* rules the runtime holds: at most one element is active, and only a root* (a direct child of `<stage>`) can be; a nested `active` is dropped. When* a file names more than one, the last one rendered wins.+ *+ * Nothing activates on its own: mark one scene of every authored project+ * `active` — with several, the one it should open on — or it opens on an+ * empty timeline, with no playhead and no scene to export.*/active?: boolean;/**diff --git a/reference/jsx/README.md b/reference/jsx/README.mdindex 63b73a5e..8c5fe5d5 100644--- a/reference/jsx/README.md+++ b/reference/jsx/README.md@@ -11,8 +11,8 @@ The markup is **pseudo-SVG**: elements like `<rect>`, `<text>`, `<linearGradient```tsxexport default function Project() {return (- <stage background="#161616">- <scene name="Intro" width={1920} height={1080} fill="black">+ <stage background="#161616" camera={[0.3, 0, 0, 0.3, 85, 150]}>+ <scene name="Intro" width={1920} height={1080} fill="black" active><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}>Hellodiff --git a/reference/jsx/generate.md b/reference/jsx/generate.mdindex fbffedbc..70e24003 100644--- a/reference/jsx/generate.md+++ b/reference/jsx/generate.md@@ -22,8 +22,8 @@ const heroMotion = generate.video({export default function Project() {return (- <stage background="#161616">- <scene name="Intro" width={1920} height={1080}>+ <stage background="#161616" camera={[0.3, 0, 0, 0.3, 85, 150]}>+ <scene name="Intro" width={1920} height={1080} active><video src={heroMotion} width={1920} height={1080} start={0} end={5} /><image src={hero} x={40} y={40} width={200} height={112} /></scene>diff --git a/reference/jsx/html.md b/reference/jsx/html.mdindex b17ecd20..cf2ad017 100644--- a/reference/jsx/html.md+++ b/reference/jsx/html.md@@ -26,8 +26,8 @@ export default function Intro() {createEffect(() => tl.seek(time()));return (- <stage>- <scene name="Intro" width={800} height={120}>+ <stage camera={[0.7, 0, 0, 0.7, 90, 270]}>+ <scene name="Intro" width={800} height={120} active><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;`}>diff --git a/reference/jsx/lifecycle.md b/reference/jsx/lifecycle.mdindex 20ba91a0..02154e09 100644--- a/reference/jsx/lifecycle.md+++ b/reference/jsx/lifecycle.md@@ -26,8 +26,8 @@ import { useTicker } from "@diffusionstudio/jsx";export default function Project() {const { time, frame } = useTicker();return (- <stage>- <scene name="HUD" width={1920} height={1080}>+ <stage camera={[0.3, 0, 0, 0.3, 85, 150]}>+ <scene name="HUD" width={1920} height={1080} active><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>diff --git a/reference/jsx/module.md b/reference/jsx/module.mdindex 8b7eb58a..079c438d 100644--- a/reference/jsx/module.md+++ b/reference/jsx/module.md@@ -5,8 +5,8 @@ A project is a folder: a real npm package whose entry file (`package.json` `main```tsxexport default function Project() {return (- <stage background="#161616">- <scene name="Intro" width={1920} height={1080} fill="black">+ <stage background="#161616" camera={[0.3, 0, 0, 0.3, 85, 150]}>+ <scene name="Intro" width={1920} height={1080} fill="black" active>{/* ... */}</scene></stage>diff --git a/reference/jsx/scene.md b/reference/jsx/scene.mdindex 9f535e6e..cbf5bd51 100644--- a/reference/jsx/scene.md+++ b/reference/jsx/scene.md@@ -3,7 +3,7 @@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-<scene name="Intro" width={1920} height={1080} fill="black">+<scene name="Intro" width={1920} height={1080} fill="black" active>{/* children, placed on this scene's timeline */}</scene>```@@ -29,6 +29,8 @@ A scene also takes paints as children, exactly as a `<rect>` does (see [paints.mTwo 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.+**Mark one scene `active` in every project you author.** Nothing activates on its own, and a project that opens with no active scene opens on an empty timeline: there is no playhead to scrub, `dapi capture` has nothing pointed at it, and an export has no scene to render. One scene, one `active`; with several, the one the project should open on — pair it with the [`<stage>`](./stage.md) `camera` that frames it.+`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.```tsxdiff --git a/reference/jsx/stage.md b/reference/jsx/stage.mdindex 68d1e3b5..7e2c1634 100644--- a/reference/jsx/stage.md+++ b/reference/jsx/stage.md@@ -5,8 +5,8 @@ The infinite canvas every project renders into: the **root element**, and the on```tsxexport default function Project() {return (- <stage background="#161616">- <scene name="Intro" width={1920} height={1080} fill="black">{/* ... */}</scene>+ <stage background="#161616" camera={[0.16, 0, 0, 0.16, 50, 230]}>+ <scene name="Intro" width={1920} height={1080} fill="black" active>{/* ... */}</scene><scene name="Outro" x={2120} width={1920} height={1080} fill="black">{/* ... */}</scene></stage>);@@ -24,7 +24,17 @@ The stage is a **singleton**: it is the canvas already on screen rather than som| `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%.+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 frame's top-left corner in the canvas's top-left corner, most of it off screen. **Write a camera into every project you author**, so the first open is already framed on the composition.++The matrix that frames a scene sitting at the origin is `[s, 0, 0, s, x, y]`: `s` scales the frame to fit the canvas — roughly 750×620 CSS pixels in a default window — and `x`/`y` inset it from the corner. A landscape frame around 580 px wide, a portrait one around 480 px tall, leaves room for the scene's label above it and the floating toolbar below:++| Scene | Camera |+| ----- | ------ |+| 1920×1080 | `[0.3, 0, 0, 0.3, 85, 150]` |+| 1080×1920 | `[0.25, 0, 0, 0.25, 235, 70]` |+| 960×540 | `[0.6, 0, 0, 0.6, 85, 150]` |++Nothing depends on the exact numbers — the viewport is whatever size the window is, and the first pan or zoom overwrites them. They only have to open on the composition rather than beside it. With more than one scene on the canvas, scale to span them all (see the example above) or frame the [active](./scene.md) one.The stage takes no timing, no transform and no paints — it is not a node, it is where the nodes are.