Skip to content

The VS Code of video editing, built for agents.

TypeScript

Add documentation for font usage in JSX and update HTML styling guidance

konstantin-pauluse105e5a0278b
diff --git a/reference/jsx/README.md b/reference/jsx/README.md
index 18cc8629..2f56b717 100644
--- a/reference/jsx/README.md
+++ b/reference/jsx/README.md
@@ -16,6 +16,7 @@ The pipeline is driven by two commands: [`dapi mount`](../mount.md) renders the
| [roots.md](./roots.md) | Root elements, `key` identity, canvas placement |
| [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 |
+| [fonts.md](./fonts.md) | Fonts for `<text>` and HTML: local families, `dapi fonts` |
| [paints.md](./paints.md) | `<solidPaint>`, gradients, `<colorStop>` |
| [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 |
diff --git a/reference/jsx/fonts.md b/reference/jsx/fonts.md
new file mode 100644
index 00000000..79a84227
--- /dev/null
+++ b/reference/jsx/fonts.md
@@ -0,0 +1,40 @@
+# Fonts
+
+Both text paths draw with fonts **installed on the machine**. Discover what is available with [`dapi fonts`](../fonts.md) (filter by family, weight, or style); the active project's families are also on [`dapi context`](../context.md) as `fontFamilies`. macOS resolves these families for both the native renderer and the browser, so there is nothing to bundle or load.
+
+## Native `<text>`
+
+Name a family on the [`<text>`](./text.md) element with `fontFamily`; pick the variant with `fontWeight` and `fontStyle`. The value must be a family present in `dapi fonts`; an unknown family falls back to the editor default.
+
+```tsx
+<text fontFamily="Inter" fontWeight={700} fontSize={128} textAlign="center" textBaseline="middle">
+ Hello World
+</text>
+```
+
+## HTML
+
+In [`<html>`](./html.md) you style text with ordinary CSS, so **use a locally installed font** and name it directly. The browser resolves the family from the OS:
+
+```tsx
+<html width={700} height={110}>
+ <div style="font:500 40px Inter;color:#fff;">Introduction</div>
+</html>
+```
+
+Remote web fonts do not work: a Google Fonts `<link>` or an `@font-face` with a `url()` source is a cross-origin subresource, and those are excluded from the painted read-back (the same rule that drops remote images, see [html.md](./html.md#requirements-and-limitations)). The glyphs would render on screen but come out blank in `dapi node capture` and exports. Stay on families from [`dapi fonts`](../fonts.md).
+
+If you want to pin an exact variant, declare an `@font-face` whose source is the CSS `local()` string that `dapi fonts` reports for that variant (never a `url()`):
+
+```tsx
+<html width={700} height={110}>
+ <style>{`
+ @font-face {
+ font-family: "Inter Display";
+ font-weight: 700;
+ src: local('Inter Display Bold'), local('Inter-DisplayBold');
+ }
+ `}</style>
+ <div style="font:700 40px 'Inter Display';color:#fff;">Introduction</div>
+</html>
+```
diff --git a/reference/jsx/html.md b/reference/jsx/html.md
index b79752d0..a5c22d7f 100644
--- a/reference/jsx/html.md
+++ b/reference/jsx/html.md
@@ -23,8 +23,8 @@ export default function Intro() {
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;">
+ <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>
@@ -34,6 +34,8 @@ 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.
+
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)
@@ -42,8 +44,8 @@ Give `<html>` a [`scene`](./scene.md) identity and it becomes the mount root:
```tsx
<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;">
+ <div style={`width:100%;height:100%;display:flex;align-items:center;justify-content:center;
+ background:#0b0d12;color:#fff;font:800 120px Inter;`}>
Hello
</div>
</html>
@@ -51,18 +53,9 @@ Give `<html>` a [`scene`](./scene.md) identity and it becomes the mount root:
This also works for other rectangular geometry tags.
-## Minimize hosts
-
-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
-// Avoid this
-<html …>…header…</html>
-<html …>…body…</html>
-<html …>…footer…</html>
-```
+Each `<html>` is a separate dom layout and read-back per frame, so prefer fewer, larger hosts. When pieces share a span, it is usually nicer to lay them out with CSS inside one `<html>` than to reach for a separate host per piece.
-Split into separate hosts only when the pieces differ meaningful in timing, or must interleave in draw order with non-HTML elements.
## Reactivity
@@ -94,5 +87,5 @@ The compiled module is persisted with the document: on reload, export, and `dapi
## Requirements and limitations
- `<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.
-- Cross-origin subresources (e.g. remote images) are excluded from the painted output by the browser's read-back rules; use local assets.
+- Cross-origin subresources (e.g. remote images, remote web fonts) are excluded from the painted output by the browser's read-back rules; use local assets and locally installed fonts (see [fonts.md](./fonts.md)).
- **`<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/text.md b/reference/jsx/text.md
index 6803248c..a75e6db5 100644
--- a/reference/jsx/text.md
+++ b/reference/jsx/text.md
@@ -15,7 +15,7 @@ All [common props](./elements.md#common-props), plus:
| Prop | Type | Default | Meaning |
| ---- | ---- | ------- | ------- |
| children | `string` (or expressions resolving to strings) | **required** | The text content. |
-| `fontFamily` | `string` | editor default | A family available on the machine ([`dapi fonts`](../fonts.md)). |
+| `fontFamily` | `string` | editor default | A family available on the machine ([`dapi fonts`](../fonts.md)); see [fonts.md](./fonts.md). |
| `fontSize` | `number` | editor default | Px. |
| `fontWeight` | `number \| "normal" \| "bold"` | `"normal"` | CSS weights `100`-`900`. |
| `fontStyle` | `"normal" \| "italic"` | `"normal"` | |