Skip to content

The VS Code of video editing, built for agents.

TypeScript

Enhance documentation on common JSX errors and update GSAP usage in examples

konstantin-paulus8aebb7dd9cca
diff --git a/reference/jsx/errors.md b/reference/jsx/errors.md
index f3bdbc0e..613ea6ae 100644
--- a/reference/jsx/errors.md
+++ b/reference/jsx/errors.md
@@ -10,3 +10,12 @@ Where each [pipeline](./README.md#pipeline) stage fails, and with what effect:
| 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. |
Runtime errors are mapped back to the source via inline sourcemaps produced at compile time.
+
+## 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:
+
+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.
+3. **Fractional `opacity` nested under fractional `opacity`.** The rasterizer drops the ancestor's whole subtree while its opacity is between 0 and 1 if any descendant carries its own `opacity` < 1 (see [html.md limitations](./html.md#requirements-and-limitations)). Symptom: an element blank at every time its entrance/exit fade is mid-flight, rendering normally the moment the animated opacity reaches exactly 1 — deterministic per time and independent of sampling order. Fix: animate `opacity` on one level only; dim children with `rgba()`/`hsl()` alpha colors.
+4. **`Error drawing <HtmlPaint> content: … No cached paint record for element`** in `dapi logs`, or html content missing from the first sampled frame(s) of a capture while later frames render: the offline draw raced the browser's paint snapshot for a freshly mounted host. Engine-side, not a composition bug — until the `whenReady` paint-snapshot fix ships, re-request the affected time or lead the capture with a throwaway frame.
diff --git a/reference/jsx/html.md b/reference/jsx/html.md
index 61485632..58941d70 100644
--- a/reference/jsx/html.md
+++ b/reference/jsx/html.md
@@ -2,23 +2,28 @@
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>`.
-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.
+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.
```tsx
-import { createTimeline } from "animejs";
+import { gsap } from "gsap";
import { useTicker } from "@diffusionstudio/jsx";
-import { createEffect } from "solid-js";
+import { createEffect, onMount } from "solid-js";
export default function Intro() {
const { time } = useTicker();
let index!: HTMLSpanElement;
let label!: HTMLSpanElement;
+ let tl!: gsap.core.Timeline;
- 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");
+ // GSAP resolves targets at tween creation and refs are only assigned during
+ // render, so build the timeline in onMount — it runs before the effect below.
+ onMount(() => {
+ tl = gsap.timeline({ paused: true })
+ .fromTo(index, { opacity: 0, x: -24 }, { opacity: 1, x: 0, ease: "power1.out", duration: 0.4 })
+ .fromTo(label, { opacity: 0 }, { opacity: 1, ease: "power1.out", duration: 0.4 }, "-=0.2");
+ });
- createEffect(() => tl.seek(time() * 1000));
+ createEffect(() => tl.seek(time()));
return (
<rect scene="intro" width={800} height={120}>
@@ -34,7 +39,7 @@ export default function Intro() {
}
```
-Prefer this timeline over hand-animating styles: keep the markup static and let the paused anime.js timeline own every moving value, so one `seek` keeps the whole host frame-accurate. A static `style` may be a plain string, but one spanning multiple lines has to be a template literal in braces (`style={`…`}`), as above. Reach for a derived style only for values the timeline does not drive, and write it as a **style object** (`style={{ color: c() }}`) rather than interpolating the signal into a style string, so each property updates independently.
+Prefer this timeline over hand-animating styles: keep the markup static and let the paused GSAP timeline own every moving value, so one `seek` keeps the whole host frame-accurate. A static `style` may be a plain string, but one spanning multiple lines has to be a template literal in braces (`style={`…`}`), as above. Reach for a derived style only for values the timeline does not drive, and write it as a **style object** (`style={{ color: c() }}`) rather than interpolating the signal into a style string, so each property updates independently.
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.
@@ -73,3 +78,5 @@ The compiled module is persisted with the document: on reload, export, and `dapi
- `<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.
- **`<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`.