The VS Code of video editing, built for agents.
TypeScript
Update JSX documentation to correct references to `<html>` and improve clarity
konstantin-paulusd0dcd7b4455d
diff --git a/reference/jsx/README.md b/reference/jsx/README.mdindex dd5650f2..18cc8629 100644--- a/reference/jsx/README.md+++ b/reference/jsx/README.md@@ -17,7 +17,7 @@ The pipeline is driven by two commands: [`dapi mount`](../mount.md) renders the| [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 || [paints.md](./paints.md) | `<solidPaint>`, gradients, `<colorStop>` |-| [html-paint.md](./html-paint.md) | `<html>`: reactive HTML children drawn into the box |+| [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`) |diff --git a/reference/jsx/elements.md b/reference/jsx/elements.mdindex e84a2c5b..26949068 100644--- a/reference/jsx/elements.md+++ b/reference/jsx/elements.md@@ -1,6 +1,6 @@# Element reference-camelCase composition elements map 1:1 onto internal node types. Lowercase DOM vocabulary is valid only inside [`<html>`](./html-paint.md) content.+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 || ------- | ------------- | ----- |@@ -15,7 +15,7 @@ camelCase composition elements map 1:1 onto internal node types. Lowercase DOM v| [`<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-paint.md) | **Geometry with Html paint** | Children are real, reactive HTML drawn into the box by the browser (html-in-canvas, flagged Chromium API). `<htmlPaint>` is the paint child form. |+| [`<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. |Any rectangle geometry above (`<rect>`, `<video>`, `<image>`, `<html>`, `<surface>`) becomes a **scene** (the composition root) when given a `scene` identity: it then clips its children to `width`×`height` and is valid only at the document top level. See [scene.md](./scene.md).diff --git a/reference/jsx/html-paint.md b/reference/jsx/html.mdsimilarity index 50%rename from reference/jsx/html-paint.mdrename to reference/jsx/html.mdindex 69ea13eb..b79752d0 100644--- a/reference/jsx/html-paint.md+++ b/reference/jsx/html.md@@ -2,34 +2,46 @@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>`.-```tsx-<rect scene="my-scene" 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 style="color:#7c9cff;">01</span> Introduction- </div>- </html>-</rect>-```--`<htmlPaint>` is the paint child form, valid inside any filled visual element; `<html>` is a rectangle carrying one, with all [common props](./elements.md#common-props). Use the paint form to draw HTML onto an existing geometry:+Drive the markup with an [anime.js](https://animejs.com) timeline and it stays 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.```tsx-<rect x={40} y={40} width={800} height={120} cornerRadius={24} fill="#111">- <htmlPaint>- <div style="font:500 40px Inter;color:#fff;">Introduction</div>- </htmlPaint>-</rect>+import { createTimeline } from "animejs";+import { useTicker } from "@diffusionstudio/jsx";+import { createEffect } from "solid-js";++export default function Intro() {+ const { time } = useTicker();+ let index!: HTMLSpanElement;+ let label!: HTMLSpanElement;++ const tl = createTimeline({ autoplay: false })+ .add(index, { opacity: [0, 1], x: [-24, 0], ease: "outQuad", duration: 400 })+ .add(label, { opacity: [0, 1], ease: "outQuad", duration: 400 }, "-=200");++ createEffect(() => tl.seek(time() * 1000));++ 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>+ );+}```+The `<html>` box carries all [common props](./elements.md#common-props). Its paint child form, [`<htmlPaint>`](./paints.md), draws the same reactive HTML onto any existing filled geometry; `<html>` is just a `<rect>` that carries one.## As a scene (full-frame HTML)Give `<html>` a [`scene`](./scene.md) identity and it becomes the mount root:```tsx-<html scene="landing" name="Landing" width={1920} height={1080}>+<html scene="landing" name="Landing" width={1920} height={1080} end={5}><div style="width:100%;height:100%;display:flex;align-items:center;justify-content:center;background:#0b0d12;color:#fff;font:800 120px Inter;">Hello@@ -41,26 +53,16 @@ This also works for other rectangular geometry tags.## Minimize hosts-Each `<html>` is a separate browser layout and read-back — cheap enough to reach for liberally, but every host is real work per frame. **Keep the number of `<html>` hosts to a minimum: when several pieces of HTML temporally align (they are on screen over the same span), author them as one host, not many.** Lay the pieces out with CSS *inside* a single `<html>` instead of scattering them across sibling `<html>` elements:+Each `<html>` is a separate dom layout and read-back per frame. **When pieces share a span, author them as one host, laid out with CSS inside a single `<html>`, not scattered across siblings:**```tsx-// Prefer: one host, internal layout-<html width={1920} height={1080} end={TOTAL}>- <div style="width:100%;height:100%;display:grid;- grid-template-rows:auto 1fr auto;font:500 40px Inter;color:#fff;">- <header style="padding:32px;">Title</header>- <main style="display:flex;align-items:center;justify-content:center;">Body</main>- <footer style="padding:32px;">Footer</footer>- </div>-</html>--// Avoid: three hosts that all live over the same span+// Avoid this<html …>…header…</html><html …>…body…</html><html …>…footer…</html>```-Reach for separate hosts only when the pieces genuinely differ in timing (different `start`/`end`), need independent keyframed props (position, opacity), or must interleave in draw order with non-HTML elements. Content that enters and exits together belongs in one host.+Split into separate hosts only when the pieces differ meaningful in timing, or must interleave in draw order with non-HTML elements.## Reactivity@@ -91,10 +93,6 @@ The compiled module is persisted with the document: on reload, export, and `dapi## Requirements and limitations-- Relies on Chromium's html-in-canvas API. The Diffusion Studio Electron app that `dapi` drives ships with this API enabled, so it is always available in this environment — do not avoid `<html>` out of availability concerns.-- Markup renders with the page's fonts and full CSS. Event handlers are dropped: the content is painted, not interactive.-- CSS animations in the markup play on the wall clock, not the composition playhead. Animate the element's props with [keyframes](./keyframes.md) for frame-accurate motion.-- Cross-origin subresources (e.g. remote images) are excluded from the painted output by the browser's read-back rules; use local assets.- `<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.-- A DOM `<canvas>` is likewise unavailable: its pixels don't survive the html-in-canvas rasterization. Use [`<surface>`](./surface-paint.md) for hand-drawn graphics.-- **`<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. A ticker-driven motion-graphics `<html>` that must span the whole composition needs an explicit `end` (`<html start={0} end={TOTAL}>…`). See [timing.md](./timing.md#semantics).+- Cross-origin subresources (e.g. remote images) are excluded from the painted output by the browser's read-back rules; use local assets.+- **`<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.diff --git a/reference/jsx/paints.md b/reference/jsx/paints.mdindex 8cf95ce8..7f180456 100644--- a/reference/jsx/paints.md+++ b/reference/jsx/paints.md@@ -19,7 +19,7 @@ Paint elements are valid inside any filled visual element (`<rect>`, `<text>`, `| `<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. |-| [`<htmlPaint>`](./html-paint.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. |+| [`<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. |diff --git a/reference/jsx/surface-paint.md b/reference/jsx/surface-paint.mdindex 873be13b..c9fecdd1 100644--- a/reference/jsx/surface-paint.md+++ b/reference/jsx/surface-paint.md@@ -21,7 +21,7 @@ An element backed by a **canvas you draw yourself**. The `ref` callback receives- 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.-- Unlike [`<html>`](./html-paint.md) no flagged browser API is needed, and the sampled pixels render in exports.+- Unlike [`<html>`](./html.md) no flagged browser API is needed, and the sampled pixels render in exports.## Reactivity@@ -87,4 +87,4 @@ The compiled module is persisted with the document, so the drawing is reproducib- 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-paint.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. Use `<surface>` for hand-drawn graphics instead.diff --git a/reference/mount.md b/reference/mount.mdindex 5de8afb8..b91a3d79 100644--- a/reference/mount.md+++ b/reference/mount.md@@ -13,7 +13,7 @@ Exactly one of:## Lifecycle-A mount stays live: its reactive graph keeps running after the command returns, so signals, effects, timers, and [`useTicker`](./jsx/lifecycle.md#useticker) keep driving the mounted entities. The compiled module is persisted with the document and re-executed in every context, so the mount is restored on reload and its ticker-driven [`<surface>`](./jsx/surface-paint.md)/[`<html>`](./jsx/html-paint.md) animate in exports and captures (the module's structure must be deterministic). See [jsx/lifecycle.md](./jsx/lifecycle.md).+A mount stays live: its reactive graph keeps running after the command returns, so signals, effects, timers, and [`useTicker`](./jsx/lifecycle.md#useticker) keep driving the mounted entities. The compiled module is persisted with the document and re-executed in every context, so the mount is restored on reload and its ticker-driven [`<surface>`](./jsx/surface-paint.md)/[`<html>`](./jsx/html.md) animate in exports and captures (the module's structure must be deterministic). See [jsx/lifecycle.md](./jsx/lifecycle.md).## Output