Skip to content

The VS Code of video editing, built for agents.

TypeScript

Update documentation for `<Html>` and `<Surface>` elements to clarify usage and improve descriptions

konstantin-paulusca796b49a95e
diff --git a/apps/cli/reference/jsx/elements.md b/apps/cli/reference/jsx/elements.md
index 4a667269..7ff4d57e 100644
--- a/apps/cli/reference/jsx/elements.md
+++ b/apps/cli/reference/jsx/elements.md
@@ -16,8 +16,8 @@ PascalCase composition elements map 1:1 onto internal node types (lowercase tags
| [`<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) (long form `<HtmlPaint>`) | **Html paint** | Paint child whose children are real, reactive HTML drawn by the browser (html-in-canvas, flagged Chromium API). |
-| [`<Surface>`](./surface-paint.md) (long form `<SurfacePaint>`) | **Surface paint** | Paint child whose `ref` hands you a canvas to draw with any context type (2d, webgl, webgpu); sampled every frame. |
+| [`<Html>`](./html-paint.md) | **Geometry with Html paint** | Children are real, reactive HTML drawn into the box by the browser (html-in-canvas, flagged Chromium API). `<HtmlPaint>` is the paint child form. |
+| [`<Surface>`](./surface-paint.md) | **Geometry with Surface paint** | `ref` hands you a canvas to draw with any context type (2d, webgl, webgpu); sampled every frame. `<SurfacePaint>` is the paint child form. |
User-defined components are ordinary Solid components; they compose the elements above and carry no runtime cost. Only the elements above produce entities.
diff --git a/apps/cli/reference/jsx/html-paint.md b/apps/cli/reference/jsx/html-paint.md
index be065e84..94dcb6af 100644
--- a/apps/cli/reference/jsx/html-paint.md
+++ b/apps/cli/reference/jsx/html-paint.md
@@ -1,19 +1,27 @@
# `<Html>`
-A paint whose children are **real HTML** (long form: `<HtmlPaint>`). The browser lays them out at the parent geometry's box size and the result is drawn into the box via the [html-in-canvas](https://github.com/WICG/html-in-canvas) API. Use it for content that is painful to build from `<Rect>` and `<Text>`: styled cards, tables, code blocks, flex/grid layouts.
+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. Use it for content that is painful to build from `<Rect>` and `<Text>`: styled cards, tables, code blocks, flex/grid layouts.
```tsx
-<Rect x={40} y={40} width={800} height={120} cornerRadius={24}>
- <Html>
- <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>
+<Html x={40} y={40} width={800} height={120} cornerRadius={24}>
+ <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>
+```
+
+`<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:
+
+```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>
```
-Inside `<Html>`, every lowercase tag is a DOM element — the case decides the environment: PascalCase tags are composition elements, lowercase tags are HTML/SVG. Lowercase tags remain invalid outside `<Html>` content.
+Inside the HTML children, the tag's case decides the environment: PascalCase tags are composition elements, lowercase tags are HTML/SVG DOM elements. Lowercase tags remain invalid outside `<Html>`/`<HtmlPaint>` content.
## Reactivity
@@ -23,26 +31,30 @@ The children are part of the project's Solid graph: signals in attributes and te
const [count, setCount] = createSignal(0);
setInterval(() => setCount((c) => c + 1), 1000);
-<Rect width={400} height={200}>
- <Html>
- <div style="font:700 96px Inter;color:#fff;">{count()}</div>
- </Html>
-</Rect>
+<Html width={400} height={200}>
+ <div style="font:700 96px Inter;color:#fff;">{count()}</div>
+</Html>
```
## Props
+`<Html>` takes all [common props](./elements.md#common-props). `<HtmlPaint>` takes:
+
| Prop | Type | Default | Meaning |
| ---- | ---- | ------- | ------- |
| `opacity` | `Animatable<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`).
+Like all paints, `<HtmlPaint>` stacks with siblings in document order and clips to the parent's box (including `cornerRadius`).
+
+## Persistence and export
+
+The compiled module is persisted with the document: on reload, export, and `dapi node 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).
## Requirements and limitations
-- Requires Chromium's html-in-canvas API, currently behind `chrome://flags/#canvas-draw-element`. Mounting `<Html>` fails with an explicit error when the API is unavailable.
-- Markup renders with the page's fonts and full CSS. Event handlers are dropped — the content is painted, not interactive.
-- The content lives only as long as its mount: it is not persisted and does not render in exports yet.
-- CSS animations in the markup play on the wall clock, not the composition playhead. Animate the parent element's props with [keyframes](./keyframes.md) for frame-accurate motion.
+- Requires Chromium's html-in-canvas API, currently behind `chrome://flags/#canvas-draw-element`. Mounting `<Html>` or `<HtmlPaint>` fails with an explicit error when the API is unavailable.
+- 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.
diff --git a/apps/cli/reference/jsx/surface-paint.md b/apps/cli/reference/jsx/surface-paint.md
index f0837675..f50f8354 100644
--- a/apps/cli/reference/jsx/surface-paint.md
+++ b/apps/cli/reference/jsx/surface-paint.md
@@ -1,6 +1,6 @@
# `<Surface>`
-A paint backed by a **canvas you draw yourself** (long form: `<SurfacePaint>`). 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` 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.
```tsx
<Surface x={40} y={40} width={640} height={360} cornerRadius={24}