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.mdindex 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.mdindex 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`.