Skip to content

The VS Code of video editing, built for agents.

TypeScript

Update JSX documentation for `<group>` and `<html>` elements to enhance clarity and consistency

konstantin-paulus69628905f262
diff --git a/reference/jsx/elements.md b/reference/jsx/elements.md
index c53323b5..e84a2c5b 100644
--- a/reference/jsx/elements.md
+++ b/reference/jsx/elements.md
@@ -4,7 +4,7 @@ camelCase composition elements map 1:1 onto internal node types. Lowercase DOM v
| Element | Internal node | Notes |
| ------- | ------------- | ----- |
-| [`<group>`](./group.md) | **Geometry with Group tag** | Container with a transform; auto-fits its size from its children. Takes no `fill` or explicit size. |
+| [`<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. |
| [`<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. |
@@ -18,7 +18,7 @@ camelCase composition elements map 1:1 onto internal node types. Lowercase DOM v
| [`<html>`](./html-paint.md) | **Geometry with Html paint** | Children are real, reactive HTML drawn into the box by the browser (html-in-canvas, flagged Chromium API). `<htmlPaint>` is the paint child form. |
| [`<surface>`](./surface-paint.md) | **Geometry with Surface paint** | `ref` hands you a canvas to draw with any context type (2d, webgl, webgpu); sampled every frame. `<surfacePaint>` is the paint child form. |
-Any rectangle geometry above (`<rect>`, `<group>`, `<video>`, `<image>`, `<html>`, `<surface>`) becomes a **scene** (the composition root) when given a `scene` identity: it then clips its children to `width`×`height` and is valid only at the document top level. See [scene.md](./scene.md).
+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).
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/reference/jsx/html-paint.md b/reference/jsx/html-paint.md
index 53e7e7a5..7fc05592 100644
--- a/reference/jsx/html-paint.md
+++ b/reference/jsx/html-paint.md
@@ -3,12 +3,14 @@
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
-<html x={40} y={40} width={800} height={120} 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 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:
@@ -24,7 +26,7 @@ An element whose children are **real HTML**: the browser lays them out at the el
## As a scene (full-frame HTML)
-Give `<html>` a [`scene`](./scene.md) identity and it becomes the mount root: the browser lays the DOM out at the full composition size and the whole frame is HTML, with no wrapper and no repeated dimensions. A scene root is not timed by a parent, so the 16-second sourceless cutoff below does not apply here.
+Give `<html>` a [`scene`](./scene.md) identity and it becomes the mount root:
```tsx
<html scene="landing" name="Landing" width={1920} height={1080}>
@@ -35,6 +37,8 @@ Give `<html>` a [`scene`](./scene.md) identity and it becomes the mount root: th
</html>
```
+This also works for other rectangular geometry tags.
+
## 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`](../mount.md) stays live, so the graph keeps running and `useTicker` or timers can drive the markup:
diff --git a/reference/jsx/scene.md b/reference/jsx/scene.md
index 2a9fb502..f4bfe049 100644
--- a/reference/jsx/scene.md
+++ b/reference/jsx/scene.md
@@ -1,6 +1,6 @@
# Scenes (the `scene` property)
-A scene is the composition root: it clips its children to `width`×`height`. The **`scene` property promotes a rectangle geometry** (`<rect>`,`<html>`, `<surface>`) to a mount root. The property's value is the scene's identity across mounts. Scenes are valid **only** at the document top level and do not nest; the first rendered root becomes the active scene (see [roots.md](./roots.md)).
+A scene is the composition root: it clips its children to `width`×`height`. The **`scene` property promotes a rectangle geometry** (`<rect>`,`<html>`, `<surface>`) to a mount root. The property's value is the scene's identity across mounts. Scenes are valid **only** at the document top level; the first rendered root becomes the active scene (see [roots.md](./roots.md)).
```tsx
// A plain scene: a rectangle promoted to the root.
@@ -28,9 +28,9 @@ Alongside it a scene uses the ordinary geometry props:
| ---- | ---- | ------- | ------- |
| `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). On `<rect>`/`<group>`; an `<html>` scene paints its own background in CSS. |
+| `fill` | `string` | none | Background fill, any CSS color (alpha is ignored) |
## Constraints
- **Rectangle geometry only.** `scene` on a `<text>`, paint, or other non-rectangle element is an error.
-- **No placement or timing.** A scene root is not positioned or timed by a parent, so `x`/`y`/`start`/`end`/`transition`/`animations` are rejected on it. Canvas position is an editor concern.
+- **No placement.** A scene root will be auto positioned