The VS Code of video editing, built for agents.
TypeScript
Refactor JSX elements to use lowercase tags for consistency
konstantin-paulus5e42ec208425
diff --git a/README.md b/README.mdindex 73aac13b..3fa9f518 100644--- a/README.md+++ b/README.md@@ -28,12 +28,12 @@ const TITLES = [export default function Project() {return (- <Scene key="intro" name="Intro" width={1920} height={1080} fill="black">- <Video src={motion} width={1920} height={1080} />- <Sequence>+ <scene key="intro" name="Intro" width={1920} height={1080} fill="black">+ <video src={motion} width={1920} height={1080} />+ <sequence><For each={TITLES}>{(t) => (- <Text+ <texttextAlign="center"textBaseline="middle"fontSize={128}@@ -44,11 +44,11 @@ export default function Project() {end={t.end}>{t.text}- </Text>+ </text>)}</For>- </Sequence>- </Scene>+ </sequence>+ </scene>);}```diff --git a/apps/cli/reference/README.md b/apps/cli/reference/README.mdindex fde58918..7ee2053f 100644--- a/apps/cli/reference/README.md+++ b/apps/cli/reference/README.md@@ -19,7 +19,7 @@ Each feature command has its own file (linked below). The JSX code syntax consumHow the surface is divided:- Declarative composition happens through `mount`, which renders a Solid JSX project into the canvas (see [jsx/](./jsx/README.md)); `node insert` runs the same pipeline but inserts the rendered nodes into an existing parent entity instead of mounting document roots.-- Scenes are created declaratively via `mount` (`<Scene key="...">`); there is no imperative scene command.+- Scenes are created declaratively via `mount` (`<scene key="...">`); there is no imperative scene command.- AI asset generation (image / video / speech / audio) is declared in the project module (`generate.*`, see [jsx/generate.md](./jsx/generate.md)) and produced on mount. `models` and `voices` list what those declarations can reference.- Inspecting an existing asset (probe / transcribe / listen / filmstrip / waveform / grab) lives under `media`; writing an asset's original file back to disk is `asset export`.- Organizing the library lives under `folder`; moving assets between folders is `asset mv`.diff --git a/apps/cli/reference/fonts.md b/apps/cli/reference/fonts.mdindex a6299282..34b96b4e 100644--- a/apps/cli/reference/fonts.md+++ b/apps/cli/reference/fonts.md@@ -1,6 +1,6 @@# `dapi fonts`-Lists local fonts available on this machine. macOS only. Does not require the app to be running. Font families listed here are valid `fontFamily` values on [`<Text>`](./jsx/text.md).+Lists local fonts available on this machine. macOS only. Does not require the app to be running. Font families listed here are valid `fontFamily` values on [`<text>`](./jsx/text.md).## Optionsdiff --git a/apps/cli/reference/jsx/README.md b/apps/cli/reference/jsx/README.mdindex 105657a6..7858dcbc 100644--- a/apps/cli/reference/jsx/README.md+++ b/apps/cli/reference/jsx/README.md@@ -2,9 +2,9 @@The JSX API defines the code contract for injecting content into the editor via the CLI. Compositions are authored as **Solid components** that a custom renderer (built on `solid-js/universal`, Solid's equivalent of React's reconciler) mounts **directly into the editor's ECS**. Every JSX element becomes an entity; every prop is a component write. There is no hidden DOM, no CSS resolution, and no measuring pass.-A project is structured like a SolidJS app: a **root** is established on the canvas (typically a Scene, identified by its key and created if absent) and the project's component tree renders into it. **All positioning is explicit** (`x`, `y`, `width`, `height` in pixels).+A project is structured like a SolidJS app: a **root** is established on the canvas (typically a scene, identified by its key and created if absent) and the project's component tree renders into it. **All positioning is explicit** (`x`, `y`, `width`, `height` in pixels).-The markup is **pseudo-SVG**: elements like `<Rect>`, `<Text>`, `<LinearGradientPaint>`, and `<ColorStop>` mirror SVG's shape-and-paint model, but the tags and props are the editor's own (see [elements.md](./elements.md)), not the SVG spec.+The markup is **pseudo-SVG**: elements like `<rect>`, `<text>`, `<linearGradientPaint>`, and `<colorStop>` mirror SVG's shape-and-paint model, but the tags and props are the editor's own (see [elements.md](./elements.md)), not the SVG spec.The pipeline is driven by two commands: [`dapi mount`](../mount.md) renders the project's roots into the document, and [`dapi node insert`](../node/insert.md) runs the same pipeline into an existing parent entity. [`dapi node patch`](../node/patch.md) assigns the same props on existing nodes.@@ -16,17 +16,17 @@ 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 |-| [paints.md](./paints.md) | `<SolidPaint>`, gradients, `<ColorStop>` |-| [html-paint.md](./html-paint.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 |+| [paints.md](./paints.md) | `<solidPaint>`, gradients, `<colorStop>` |+| [html-paint.md](./html-paint.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 || [media.md](./media.md) | `src` resolution (paths, URLs, asset ids, `AssetRef`) || [timing.md](./timing.md) | `start` / `end` / `sourceIn` / `sourceOut`, time formats || [keyframes.md](./keyframes.md) | Keyframe animation and easing || [animations.md](./animations.md) | The `animations` prop: preset in/out animations || [transitions.md](./transitions.md) | The `transition` prop on sequence clips |-| [sequences.md](./sequences.md) | `<Sequence>` sequential placement |+| [sequences.md](./sequences.md) | `<sequence>` sequential placement || [audio-sync.md](./audio-sync.md) | `syncTo` audio alignment |-| [captions.md](./captions.md) | `<Captions>` and style presets |+| [captions.md](./captions.md) | `<captions>` and style presets || [generate.md](./generate.md) | Declarative AI asset generation (`generate.*`) || [lifecycle.md](./lifecycle.md) | Mount lifecycle: always live, persisted + re-executed, `useTicker` || [errors.md](./errors.md) | Where each pipeline stage fails and with what effect |@@ -66,7 +66,7 @@ const TITLES = [function Title(props: { text: string; start: Time; end: Time }) {return (- <Text+ <texttextAlign="center"textBaseline="middle"fill="#FFFFFF"@@ -78,31 +78,31 @@ function Title(props: { text: string; start: Time; end: Time }) {end={props.end}>{props.text}- </Text>+ </text>);}export default function Project() {return (- <Scene key="my-first-scene" name="MyFirstScene" fill="black" width={1920} height={1080}>- <Sequence>- <Video src={heroMotion} start={0} end={5} transition={{ type: "dissolve" }} />- <Video src="/Movies/video.mp4" start={5} end={10} sourceIn={12} />- </Sequence>+ <scene key="my-first-scene" name="MyFirstScene" fill="black" width={1920} height={1080}>+ <sequence>+ <video src={heroMotion} start={0} end={5} transition={{ type: "dissolve" }} />+ <video src="/Movies/video.mp4" start={5} end={10} sourceIn={12} />+ </sequence>- <Image src={hero} x={40} y={40} width={200} height={112} />+ <image src={hero} x={40} y={40} width={200} height={112} /><For each={TITLES}>{(t) => <Title {...t} />}</For>- <Audio+ <audiosrc="https://my.videoarchive.com/audio/video-xyz.wav"sourceIn={6}sourceOut={16}volume={-6}/>- <Captions />- </Scene>+ <captions />+ </scene>);}```diff --git a/apps/cli/reference/jsx/animations.md b/apps/cli/reference/jsx/animations.mdindex 791dfed2..97fdd000 100644--- a/apps/cli/reference/jsx/animations.md+++ b/apps/cli/reference/jsx/animations.md@@ -3,7 +3,7 @@`animations` declares **preset in/out animations** on a clip: each entry plays over the clip's head (`"in"`) or tail (`"out"`), between the node's static state and the preset's start/end state. For hand-authored motion on individual props, use [keyframes](./keyframes.md); the two compose on distinct properties.```tsx-<Video+<videosrc="/Movies/intro.mp4"start={0} end={8}animations={[@@ -40,7 +40,7 @@ The editor's animations inspector options:| `"scramble"` | Text only: resolves scrambled characters into the text. || `"gain"` | Audio only: volume ramp (fade-in/fade-out of the mix). No visual effect. |-Text types apply only to [`<Text>`](./text.md) and [`<Captions>`](./captions.md); a mount that puts them elsewhere fails validation.+Text types apply only to [`<text>`](./text.md) and [`<captions>`](./captions.md); a mount that puts them elsewhere fails validation.## Semanticsdiff --git a/apps/cli/reference/jsx/audio-sync.md b/apps/cli/reference/jsx/audio-sync.mdindex f867c9c4..b5b3a2ef 100644--- a/apps/cli/reference/jsx/audio-sync.md+++ b/apps/cli/reference/jsx/audio-sync.md@@ -3,10 +3,10 @@`syncTo` places a node in time by listening instead of arithmetic: the node's audio is cross-correlated against another node's audio, and its `start` is computed so the two recordings coincide on the timeline. It replaces manual offset measurement for multi-recorder material: a lav or voice track against camera audio, two cameras on the same take, two microphones in one room.```tsx-<Scene key="talk" width={1920} height={1080}>- <Video key="camera" src="/Movies/take-3.mp4" sourceOut={45} muted />- <Audio src="/Movies/lav.wav" syncTo="camera" />-</Scene>+<scene key="talk" width={1920} height={1080}>+ <video key="camera" src="/Movies/take-3.mp4" sourceOut={45} muted />+ <audio src="/Movies/lav.wav" syncTo="camera" />+</scene>```## Semanticsdiff --git a/apps/cli/reference/jsx/audio.md b/apps/cli/reference/jsx/audio.mdindex ed0095cb..f9146c55 100644--- a/apps/cli/reference/jsx/audio.md+++ b/apps/cli/reference/jsx/audio.md@@ -1,9 +1,9 @@-# `<Audio>`+# `<audio>`An audio clip: no visual output, no spatial props; carries volume. When timing is omitted, the node fits its natural duration (see [timing.md](./timing.md)).```tsx-<Audio src="https://my.videoarchive.com/audio/clip.wav" start={2.2} sourceOut={16} volume={-6} />+<audio src="https://my.videoarchive.com/audio/clip.wav" start={2.2} sourceOut={16} volume={-6} />```## Propsdiff --git a/apps/cli/reference/jsx/captions.md b/apps/cli/reference/jsx/captions.mdindex e0f2b291..3a3e60b4 100644--- a/apps/cli/reference/jsx/captions.md+++ b/apps/cli/reference/jsx/captions.md@@ -1,9 +1,9 @@# Captions-`<Captions />` inside a scene transcribes that scene's audio into a caption node: a styled, timed transcript, produced on import. To caption an already-open scene, insert one with [`dapi node insert`](../node/insert.md).+`<captions />` inside a scene transcribes that scene's audio into a caption node: a styled, timed transcript, produced on import. To caption an already-open scene, insert one with [`dapi node insert`](../node/insert.md).```tsx-<Captions preset="spotlight" colors={["#FF0055"]} verticalAlign="bottom" />+<captions preset="spotlight" colors={["#FF0055"]} verticalAlign="bottom" />```Transcription is **asynchronous and non-blocking**: the caption node is inserted at commit and its transcript attaches once ready. Because it reads the scene's audio, it runs **after** any generated assets in the scene have landed and after [audio sync](./audio-sync.md) has resolved; captioning a generated `voice`/`audio` track transcribes the finished audio at its final placement. The scene must contain an unmuted audio or video source; otherwise the caption node is left empty.diff --git a/apps/cli/reference/jsx/elements.md b/apps/cli/reference/jsx/elements.mdindex 507d975d..17ffa798 100644--- a/apps/cli/reference/jsx/elements.md+++ b/apps/cli/reference/jsx/elements.md@@ -1,23 +1,23 @@# Element reference-PascalCase composition elements map 1:1 onto internal node types (lowercase tags are DOM vocabulary, valid only inside [`<Html>`](./html-paint.md) content):+camelCase composition elements map 1:1 onto internal node types. Lowercase DOM vocabulary is valid only inside [`<html>`](./html-paint.md) content.| Element | Internal node | Notes || ------- | ------------- | ----- |-| [`<Scene>`](./scene.md) | **Geometry with Scene tag** | Clips its children to `width`×`height`. Document root only. |-| [`<Group>`](./group.md) | **Geometry 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. |-| [`<Audio>`](./audio.md) | **Geometry with Audio component and a hidden Waveform paint** | No visual output; carries volume. |-| [`<Text>`](./text.md) | **Geometry with Text component** | Children become editable glyphs. |-| [`<Sequence>`](./sequences.md) | **Sequential group** | Track container for back-to-back clips; positions are explicit. |-| [`<Captions>`](./captions.md) | **Caption node** | Transcribes the enclosing scene's audio. |-| [`<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) | **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. |+| [`<scene>`](./scene.md) | **Geometry with Scene tag** | Clips its children to `width`×`height`. Document root only. |+| [`<group>`](./group.md) | **Geometry 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. |+| [`<audio>`](./audio.md) | **Geometry with Audio component and a hidden Waveform paint** | No visual output; carries volume. |+| [`<text>`](./text.md) | **Geometry with Text component** | Children become editable glyphs. |+| [`<sequence>`](./sequences.md) | **Sequential group** | Track container for back-to-back clips; positions are explicit. |+| [`<captions>`](./captions.md) | **Caption node** | Transcribes the enclosing scene's audio. |+| [`<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) | **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.@@ -42,7 +42,7 @@ All visual elements accept:| `opacity` | `Animatable<number>` | `1` | `0`-`1`. || `cornerRadius` | `Animatable<number>` | `0` | Uniform corner radius, px. || `start`, `end`, `sourceIn`, `sourceOut` | `Time` | see [timing.md](./timing.md) | Temporal placement. |-| `transition` | `TransitionSpec \| null` | none | Transition into the next clip; direct children of `<Sequence>` only (see [transitions.md](./transitions.md)). |+| `transition` | `TransitionSpec \| null` | none | Transition into the next clip; direct children of `<sequence>` only (see [transitions.md](./transitions.md)). || `animations` | `AnimationSpec[]` | none | Preset in/out animations over the clip's head and tail (see [animations.md](./animations.md)). |`Animatable` props also take a keyframe list; see [keyframes.md](./keyframes.md).diff --git a/apps/cli/reference/jsx/errors.md b/apps/cli/reference/jsx/errors.mdindex 95583112..121a5cda 100644--- a/apps/cli/reference/jsx/errors.md+++ b/apps/cli/reference/jsx/errors.md@@ -5,7 +5,7 @@ Where each [pipeline](./README.md#pipeline) stage fails, and with what effect:| Stage | Where it surfaces | Effect || ----- | ----------------- | ------ || Compile (syntax/type-stripping/bundling) | CLI stderr, exit 1 | App never contacted. |-| Evaluate / mount (thrown errors, invalid props, invalid root: e.g. nested `<Scene>`, a root element without `key`, missing `src`, malformed `Time`, an unknown or cyclic `syncTo` key, `syncTo` combined with `start`) | CLI stderr, exit 1 | Staging root discarded; **nothing inserted**. |+| Evaluate / mount (thrown errors, invalid props, invalid root: e.g. nested `<scene>`, a root element without `key`, missing `src`, malformed `Time`, an unknown or cyclic `syncTo` key, `syncTo` combined with `start`) | CLI stderr, exit 1 | Staging root discarded; **nothing inserted**. || Generation (per-model constraints: `aspectRatio`, `duration`, feature flags) | CLI stderr, exit 1, after every generation settled | No rollback; the mounted tree stays committed. The affected placeholder stops showing its generating state and is left without a paint. || 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. |diff --git a/apps/cli/reference/jsx/generate.md b/apps/cli/reference/jsx/generate.mdindex 3df5cf90..febe3c00 100644--- a/apps/cli/reference/jsx/generate.md+++ b/apps/cli/reference/jsx/generate.md@@ -22,10 +22,10 @@ const heroMotion = generate.video({export default function Project() {return (- <Scene key="intro" name="Intro" width={1920} height={1080}>- <Video src={heroMotion} start={0} end={5} />- <Image src={hero} x={40} y={40} width={200} height={112} />- </Scene>+ <scene key="intro" name="Intro" width={1920} height={1080}>+ <video src={heroMotion} start={0} end={5} />+ <image src={hero} x={40} y={40} width={200} height={112} />+ </scene>);}```diff --git a/apps/cli/reference/jsx/group.md b/apps/cli/reference/jsx/group.mdindex 3a6147d6..cf80c4cb 100644--- a/apps/cli/reference/jsx/group.md+++ b/apps/cli/reference/jsx/group.md@@ -1,11 +1,11 @@-# `<Group>`+# `<group>`A container with a transform but no dimensions of its own: a group derives its box from its children, and they are positioned relative to it.```tsx-<Group x={100} y={100}>+<group x={100} y={100}>{/* children */}-</Group>+</group>```## Propsdiff --git a/apps/cli/reference/jsx/html-paint.md b/apps/cli/reference/jsx/html-paint.mdindex 94dcb6af..cc4db7bc 100644--- a/apps/cli/reference/jsx/html-paint.md+++ b/apps/cli/reference/jsx/html-paint.md@@ -1,27 +1,26 @@-# `<Html>`+# `<html>`-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.+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-<Html x={40} y={40} width={800} height={120} cornerRadius={24}>+<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>+</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:+`<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>+<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>+ </htmlPaint>+</rect>```-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@@ -31,20 +30,20 @@ The children are part of the project's Solid graph: signals in attributes and teconst [count, setCount] = createSignal(0);setInterval(() => setCount((c) => c + 1), 1000);-<Html width={400} height={200}>+<html width={400} height={200}><div style="font:700 96px Inter;color:#fff;">{count()}</div>-</Html>+</html>```## Props-`<Html>` takes all [common props](./elements.md#common-props). `<HtmlPaint>` takes:+`<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, `<HtmlPaint>` 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@@ -52,9 +51,9 @@ The compiled module is persisted with the document: on reload, export, and `dapi## Requirements and limitations-- 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.+- 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.+- `<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/image.md b/apps/cli/reference/jsx/image.mdindex 39b9547b..8d36b50c 100644--- a/apps/cli/reference/jsx/image.md+++ b/apps/cli/reference/jsx/image.md@@ -1,9 +1,9 @@-# `<Image>`+# `<image>`An image. `src` resolves to an image asset (see [media.md](./media.md)).```tsx-<Image src="/photo.jpg" x={40} y={40} width={200} height={112} />+<image src="/photo.jpg" x={40} y={40} width={200} height={112} />```## Propsdiff --git a/apps/cli/reference/jsx/keyframes.md b/apps/cli/reference/jsx/keyframes.mdindex 35dc2ba9..e6142907 100644--- a/apps/cli/reference/jsx/keyframes.md+++ b/apps/cli/reference/jsx/keyframes.md@@ -3,7 +3,7 @@Animatable props accept a keyframe list in place of a static value:```tsx-<Image+<imagesrc="/photo.jpg"start={0} end={5}x={[diff --git a/apps/cli/reference/jsx/lifecycle.md b/apps/cli/reference/jsx/lifecycle.mdindex 7cbc8d69..69f7ff57 100644--- a/apps/cli/reference/jsx/lifecycle.md+++ b/apps/cli/reference/jsx/lifecycle.md@@ -2,9 +2,9 @@## A mount stays live-After `dapi mount` returns, its reactive graph keeps running: signals, effects, timers, and [`useTicker`](#useticker) keep driving the mounted entities. Updates land in the document immediately (not as undo steps) — prop writes, conditional inserts and removals (`<Show>`, `<For>`), text, and reactive `src` swaps including `generate.*`. The materialized nodes are ordinary editable entities; asset generation is owned by the engine. `syncTo` and new `<Captions>` are mount-only and throw if changed after commit. A run ends when a later `mount` claims one of its root keys (swapping the entities and disposing the old graph) or the project closes.+After `dapi mount` returns, its reactive graph keeps running: signals, effects, timers, and [`useTicker`](#useticker) keep driving the mounted entities. Updates land in the document immediately (not as undo steps) — prop writes, conditional inserts and removals (`<Show>`, `<For>`), text, and reactive `src` swaps including `generate.*`. The materialized nodes are ordinary editable entities; asset generation is owned by the engine. `syncTo` and new `<captions>` are mount-only and throw if changed after commit. A run ends when a later `mount` claims one of its root keys (swapping the entities and disposing the old graph) or the project closes.-The compiled module is persisted with the document and re-executed in every context: reload rebuilds the graph and its runtime hosts (`<Surface>`/`<Html>`), and export and capture drive the ticker across the frames they render. Re-execution binds to the existing entities rather than re-authoring them, so hand-edits survive; it rewrites only the props your effects animate. This requires the module's structure to be deterministic: `Math.random()` and `Date.now()` must not decide element counts or `<Show>`/`<For>` branches (using them inside an effect is fine).+The compiled module is persisted with the document and re-executed in every context: reload rebuilds the graph and its runtime hosts (`<surface>`/`<html>`), and export and capture drive the ticker across the frames they render. Re-execution binds to the existing entities rather than re-authoring them, so hand-edits survive; it rewrites only the props your effects animate. This requires the module's structure to be deterministic: `Math.random()` and `Date.now()` must not decide element counts or `<Show>`/`<For>` branches (using them inside an effect is fine).`node insert` renders into an existing parent and is not persisted or kept live.@@ -18,10 +18,10 @@ import { useTicker } from "@diffusionstudio/jsx";export default function Project() {const { time, frame } = useTicker();return (- <Scene key="hud" width={1920} height={1080}>- <Text fontSize={80}>{`frame ${frame()}`}</Text>- <Rect x={860 + Math.sin(time() * 4) * 200} y={490} width={100} height={100} fill="#f43" />- </Scene>+ <scene key="hud" width={1920} height={1080}>+ <text fontSize={80}>{`frame ${frame()}`}</text>+ <rect x={860 + Math.sin(time() * 4) * 200} y={490} width={100} height={100} fill="#f43" />+ </scene>);}```@@ -39,7 +39,7 @@ The values respect play, pause, scrubbing, looping, and playback speed, which wa## `useFile`-Resolves a [`src`](./media.md) (path, asset id, URL, or a `generate.*` ref) to its `File`, so effects can read the raw bytes: draw a library image onto a [`<Surface>`](./surface-paint.md), parse a data file, decode audio. The module is sandboxed and can't fetch a path or asset id itself, so resolution goes through the host, exactly as `src` does.+Resolves a [`src`](./media.md) (path, asset id, URL, or a `generate.*` ref) to its `File`, so effects can read the raw bytes: draw a library image onto a [`<surface>`](./surface-paint.md), parse a data file, decode audio. The module is sandboxed and can't fetch a path or asset id itself, so resolution goes through the host, exactly as `src` does.```tsximport { createSignal, createEffect } from "solid-js";@@ -57,7 +57,7 @@ function Logo() {ctx.drawImage(await createImageBitmap(f), 0, 0, el.width, el.height);});- return <Surface ref={setCanvas} width={640} height={360} />;+ return <surface ref={setCanvas} width={640} height={360} />;}```diff --git a/apps/cli/reference/jsx/media.md b/apps/cli/reference/jsx/media.mdindex 7d11bb7e..06a827c0 100644--- a/apps/cli/reference/jsx/media.md+++ b/apps/cli/reference/jsx/media.md@@ -1,6 +1,6 @@# Media source resolution-`src` (on [`<Video>`](./video.md), [`<Image>`](./image.md), [`<Audio>`](./audio.md)) accepts:+`src` (on [`<video>`](./video.md), [`<image>`](./image.md), [`<audio>`](./audio.md)) accepts:- **Global path**: e.g. `"/Movies/video.mp4"`, resolved against the user's OS.- **Remote URL**: e.g. `"https://my.videoarchive.com/audio/clip.wav"`, registered as a remote asset.diff --git a/apps/cli/reference/jsx/module.md b/apps/cli/reference/jsx/module.mdindex 50096d60..de9bf08b 100644--- a/apps/cli/reference/jsx/module.md+++ b/apps/cli/reference/jsx/module.md@@ -3,18 +3,15 @@The entry file is a standard Solid component module:```tsx-import { Scene } from "@diffusionstudio/jsx";-export default function Project() {return (- <Scene key="intro" name="Intro" fill="black" width={1920} height={1080}>+ <scene key="intro" name="Intro" fill="black" width={1920} height={1080}>{/* ... */}- </Scene>+ </scene>);}```-The element import is optional at runtime — the compiler auto-imports PascalCase elements — but it makes the file typecheck (see [Types and tooling](#types-and-tooling)).The component receives no props; which document node each rendered root maps onto is declared in the JSX itself via `key` (see [roots.md](./roots.md)).@@ -46,7 +43,7 @@ A `dapi.config.json` in the working directory pins versions or redirects userlan## Types and tooling-`@diffusionstudio/jsx` ships the composition elements and their prop types, the JSX namespace, `Time`, `AssetRef`, and the `generate` namespace. The PascalCase elements auto-import at compile time, so project files use them without import statements. For editor IntelliSense and typechecking in a project folder:+`@diffusionstudio/jsx` ships the JSX namespace (which types the camelCase composition tags), for editor IntelliSense and typechecking in a project folder:```json{@@ -57,6 +54,6 @@ A `dapi.config.json` in the working directory pins versions or redirects userlan}```-The CLI does not typecheck; types are stripped at compile time. Run `tsc --noEmit` in the project folder for type safety. The compile-time auto-import is invisible to TypeScript, so for typechecking import the elements you use explicitly (`import { Scene, Text } from "@diffusionstudio/jsx"`) — explicit imports and the auto-import behave identically at runtime.+The CLI does not typecheck; types are stripped at compile time. Run `tsc --noEmit` in the project folder for type safety.Userland packages resolve from a CDN at runtime, so they need no runtime install, but the editor still wants their type declarations. For IntelliSense on a library, install it (or its `@types/…`) as a **dev-only** dependency (`npm i -D three`); it is used purely for typechecking and never bundled or shipped.diff --git a/apps/cli/reference/jsx/paints.md b/apps/cli/reference/jsx/paints.mdindex 642f1da8..7a8ded57 100644--- a/apps/cli/reference/jsx/paints.md+++ b/apps/cli/reference/jsx/paints.md@@ -3,25 +3,25 @@Internally a node's fill is not a property but a **paint child**: a sub-entity appended to the geometry, exactly like the editor's fill list. The `fill` prop is shorthand for a solid paint; declaring paints as JSX children exposes the full model, including gradients:```tsx-<Rect width={640} height={360} cornerRadius={24}>- <LinearGradientPaint rotation={90}>- <ColorStop offset={0} color="#FF0055" />- <ColorStop offset={1} color="#0055FF" />- </LinearGradientPaint>-</Rect>+<rect width={640} height={360} cornerRadius={24}>+ <linearGradientPaint rotation={90}>+ <colorStop offset={0} color="#FF0055" />+ <colorStop offset={1} color="#0055FF" />+ </linearGradientPaint>+</rect>```-Paint elements are valid inside any filled visual element (`<Rect>`, `<Scene>`, `<Text>`, `<Video>`, `<Image>`); a `<Group>` has no fill of its own, so it takes none. Multiple paints stack in document order; later paints render on top, and a paint child on a `<Video>`/`<Image>` draws over the media paint created by `src`.+Paint elements are valid inside any filled visual element (`<rect>`, `<scene>`, `<text>`, `<video>`, `<image>`); a `<group>` has no fill of its own, so it takes none. Multiple paints stack in document order; later paints render on top, and a paint child on a `<video>`/`<image>` draws over the media paint created by `src`.| Element | Props | Meaning || ------- | ----- | ------- |-| `<SolidPaint>` | `color` (**required**), `opacity` | Solid fill; equivalent to the `fill` prop. |-| `<LinearGradientPaint>` | `rotation`, `opacity` | Linear gradient across the parent's box; `rotation` in degrees, `0` = left to right. |-| `<RadialGradientPaint>` | `rotation`, `opacity` | Radial gradient centered in the parent's box. |-| `<ColorStop>` | `offset` (**required**, `0`-`1`), `color` (**required**), `opacity` | Gradient color stop. Valid only inside gradient paints, which take no other children. |-| [`<HtmlPaint>`](./html-paint.md) | `opacity`, HTML children | Reactive HTML laid out and drawn into the parent's box (flagged Chromium API). `<Html>` is shorthand for a `<Rect>` carrying one. |-| [`<SurfacePaint>`](./surface-paint.md) | `opacity`, `ref` (**required**) | A canvas your `ref` callback draws into (any context type), sampled into the parent's box every frame. `<Surface>` is shorthand for a `<Rect>` carrying one. |+| `<solidPaint>` | `color` (**required**), `opacity` | Solid fill; equivalent to the `fill` prop. |+| `<linearGradientPaint>` | `rotation`, `opacity` | Linear gradient across the parent's box; `rotation` in degrees, `0` = left to right. |+| `<radialGradientPaint>` | `rotation`, `opacity` | Radial gradient centered in the parent's box. |+| `<colorStop>` | `offset` (**required**, `0`-`1`), `color` (**required**), `opacity` | Gradient color stop. Valid only inside gradient paints, which take no other children. |+| [`<htmlPaint>`](./html-paint.md) | `opacity`, HTML children | Reactive HTML laid out and drawn into the parent's box (flagged Chromium API). `<html>` is shorthand for a `<rect>` carrying one. |+| [`<surfacePaint>`](./surface-paint.md) | `opacity`, `ref` (**required**) | A canvas your `ref` callback draws into (any context type), sampled into the parent's box every frame. `<surface>` is shorthand for a `<rect>` carrying one. |Colors accept any CSS color; alpha is ignored (use `opacity`). `color`, `opacity`, and `offset` are animatable (see [keyframes.md](./keyframes.md)), so gradients can animate. Paints have no spatial or timing props and cannot be document roots.-Paints are live entities like any other: patch them with [`dapi node patch`](../node/patch.md), and add a stop to an existing gradient with [`dapi node insert`](../node/insert.md) (`node insert <paintId> '<ColorStop offset={0.5} color="#FF0055" />'`).+Paints are live entities like any other: patch them with [`dapi node patch`](../node/patch.md), and add a stop to an existing gradient with [`dapi node insert`](../node/insert.md) (`node insert <paintId> '<colorStop offset={0.5} color="#FF0055" />'`).diff --git a/apps/cli/reference/jsx/rect.md b/apps/cli/reference/jsx/rect.mdindex a0f7a253..919a4014 100644--- a/apps/cli/reference/jsx/rect.md+++ b/apps/cli/reference/jsx/rect.md@@ -1,9 +1,9 @@-# `<Rect>`+# `<rect>`A filled rectangle. Takes only [paint children](./paints.md); use `cornerRadius` for rounded corners.```tsx-<Rect x={40} y={40} width={640} height={360} cornerRadius={24} fill="#FF0055" />+<rect x={40} y={40} width={640} height={360} cornerRadius={24} fill="#FF0055" />```## Propsdiff --git a/apps/cli/reference/jsx/roots.md b/apps/cli/reference/jsx/roots.mdindex 64dab56c..580dd57f 100644--- a/apps/cli/reference/jsx/roots.md+++ b/apps/cli/reference/jsx/roots.md@@ -1,20 +1,20 @@# Roots-A mount renders one or more root elements (a fragment of roots is allowed) and **refreshes the document**: like reloading a webpage, re-running a mount rebuilds its roots in place instead of accumulating copies; a rendered root with no existing node to replace is created. Roots are typically [`<Scene>`](./scene.md) elements, but any element can be a root (e.g. a bare `<Rect>`). Every top-level element must declare its identity with a `key`:+A mount renders one or more root elements (a fragment of roots is allowed) and **refreshes the document**: like reloading a webpage, re-running a mount rebuilds its roots in place instead of accumulating copies; a rendered root with no existing node to replace is created. Roots are typically [`<scene>`](./scene.md) elements, but any element can be a root (e.g. a bare `<rect>`). Every top-level element must declare its identity with a `key`:| Identity | Contract || -------- | -------- |-| `<Scene key="intro">` | Rebuilds the existing node carrying the same key, or creates it (storing the key) if none does. Keyed nodes in the document that the render no longer produces are **deleted**; the mount owns its keyed roots. |+| `<scene key="intro">` | Rebuilds the existing node carrying the same key, or creates it (storing the key) if none does. Keyed nodes in the document that the render no longer produces are **deleted**; the mount owns its keyed roots. |-Keys must be unique within a render, and rebuilding keeps the node's entity id and canvas position. Nodes without a key (e.g. hand-made scratch scenes) are never touched. The **first** rendered root becomes the active scene. Assigning a `name` alongside the key (e.g. `<Scene key="intro" name="Intro">`) is recommended: the key identifies the node across mounts, the name labels it in the editor.+Keys must be unique within a render, and rebuilding keeps the node's entity id and canvas position. Nodes without a key (e.g. hand-made scratch scenes) are never touched. The **first** rendered root becomes the active scene. Assigning a `name` alongside the key (e.g. `<scene key="intro" name="Intro">`) is recommended: the key identifies the node across mounts, the name labels it in the editor.-`<Scene>` is valid **only** at the document root; scenes do not nest.+`<scene>` is valid **only** at the document root; scenes do not nest.[`dapi node insert`](../node/insert.md) skips this reconciliation entirely: its roots take no `key` and every run inserts fresh entities.## Canvas placement-The canvas holds many roots, but a root's position on the canvas is an **editor concern, not part of the composition**: `<Scene>` has no `x`/`y`, and a project describes content, not canvas arrangement.+The canvas holds many roots, but a root's position on the canvas is an **editor concern, not part of the composition**: `<scene>` has no `x`/`y`, and a project describes content, not canvas arrangement.- **Rebuilt roots** (matched by `key`) keep their existing canvas position.- **New roots** are placed automatically: in the nearest empty space around the current viewport center, gapped so they never overlap existing content (the same auto-placement the editor uses when generating onto the canvas). A mount that creates multiple roots places them side by side in render order.diff --git a/apps/cli/reference/jsx/scene.md b/apps/cli/reference/jsx/scene.mdindex b7002a84..4c9bc7ba 100644--- a/apps/cli/reference/jsx/scene.md+++ b/apps/cli/reference/jsx/scene.md@@ -1,11 +1,11 @@-# `<Scene>`+# `<scene>`The composition root: clips its children to `width`×`height`. Valid **only** at the document top level; scenes do not nest. The first rendered root becomes the active scene (see [roots.md](./roots.md)).```tsx-<Scene key="intro" name="Intro" fill="black" width={1920} height={1080}>+<scene key="intro" name="Intro" fill="black" width={1920} height={1080}>{/* children */}-</Scene>+</scene>```## Props@@ -17,4 +17,4 @@ The composition root: clips its children to `width`×`height`. Valid **only** at| `name` | `string` | none | Scene name (recommended). || `fill` | `string` | none | Background fill, any CSS color (alpha is ignored). |-No timing or transform props. Canvas position is an editor concern; `<Scene>` has no `x`/`y`.+No timing or transform props. Canvas position is an editor concern; `<scene>` has no `x`/`y`.diff --git a/apps/cli/reference/jsx/sequences.md b/apps/cli/reference/jsx/sequences.mdindex 5bce9f65..1ef441da 100644--- a/apps/cli/reference/jsx/sequences.md+++ b/apps/cli/reference/jsx/sequences.md@@ -1,13 +1,13 @@# Sequences-`<Sequence>` is a track-like container for back-to-back clips. It carries no timing of its own and **does not position its children at mount** — give each child an explicit `start` (see [timing.md](./timing.md)). What it adds is clip-to-clip [transitions](./transitions.md) on direct children, and, in the editor, a non-overlapping invariant: dragging or regrouping clips trims or removes whatever they land on.+`<sequence>` is a track-like container for back-to-back clips. It carries no timing of its own and **does not position its children at mount** — give each child an explicit `start` (see [timing.md](./timing.md)). What it adds is clip-to-clip [transitions](./transitions.md) on direct children, and, in the editor, a non-overlapping invariant: dragging or regrouping clips trims or removes whatever they land on.```tsx-<Sequence>- <Video src="/Movies/intro.mp4" start={0} end={12} /> {/* timeline 0–12 */}- <Video src="/Movies/main.mp4" start={12} end="02:30" sourceIn={5} /> {/* timeline 12–2:30, source from 5 s */}- <Video src="/Movies/outro.mp4" start="02:30" /> {/* from 2:30, plays to its natural end */}-</Sequence>+<sequence>+ <video src="/Movies/intro.mp4" start={0} end={12} /> {/* timeline 0–12 */}+ <video src="/Movies/main.mp4" start={12} end="02:30" sourceIn={5} /> {/* timeline 12–2:30, source from 5 s */}+ <video src="/Movies/outro.mp4" start="02:30" /> {/* from 2:30, plays to its natural end */}+</sequence>```The next clip's `start` must match the previous clip's on-timeline end — its `end`, or from the source side `start + (sourceOut - sourceIn)`. Here `main` ends at `02:30`, so `outro` starts there. Giving `main` an `end` places the next cut at a round timeline mark without computing source lengths.diff --git a/apps/cli/reference/jsx/surface-paint.md b/apps/cli/reference/jsx/surface-paint.mdindex f50f8354..873be13b 100644--- a/apps/cli/reference/jsx/surface-paint.md+++ b/apps/cli/reference/jsx/surface-paint.md@@ -1,9 +1,9 @@-# `<Surface>`+# `<surface>`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}+<surface x={40} y={40} width={640} height={360} cornerRadius={24}ref={(el) => {const ctx = el.getContext("2d")!;ctx.fillStyle = "#111";@@ -14,21 +14,21 @@ An element backed by a **canvas you draw yourself**. The `ref` callback receives}} />```-`<SurfacePaint ref={...}>` is the paint child form, valid inside any filled visual element; `<Surface>` is a rectangle carrying one, with all [common props](./elements.md#common-props).+`<surfacePaint ref={...}>` is the paint child form, valid inside any filled visual element; `<surface>` is a rectangle carrying one, with all [common props](./elements.md#common-props).## The ref and the bitmap- The ref runs **once**, when the paint materializes, inside the mount's reactive owner — `createEffect`, `onCleanup`, and [`useTicker`](./lifecycle.md) all work inside it.-- **Callback form only** (`ref={(el) => ...}`). Variable refs (`let el; <Surface ref={el} />`) receive a renderer-internal node, not the canvas.+- **Callback form only** (`ref={(el) => ...}`). Variable refs (`let el; <surface ref={el} />`) receive a renderer-internal node, not the canvas.- The bitmap is allocated at the element's box size (in composition pixels) **before the ref runs**; after that the engine never touches it — the bitmap belongs to your code. Resize it yourself (`el.width = ...`, or an external renderer's own API) for higher resolution; the bitmap is stretched into the box every frame either way, so an animated box scales pixels rather than re-rasterizing.-- Unlike [`<Html>`](./html-paint.md) no flagged browser API is needed, and the sampled pixels render in exports.+- Unlike [`<html>`](./html-paint.md) no flagged browser API is needed, and the sampled pixels render in exports.## ReactivityThe engine samples the canvas every frame, so anything you draw shows up on the next frame. A [`dapi mount`](../mount.md) stays live, so the reactive graph keeps running: create effects in the ref to redraw from signals, or drive frame-accurate motion from the ticker's composition time:```tsx-<Surface width={400} height={400}+<surface width={400} height={400}ref={(el) => {const ctx = el.getContext("2d")!;const { time } = useTicker();@@ -49,7 +49,7 @@ Because the ticker follows the playhead, ticker-driven drawing stays frame-accurAnything that accepts an existing canvas plugs in directly; a detached canvas is fine for WebGL:```tsx-<Surface width={1280} height={720}+<surface width={1280} height={720}ref={(el) => {const renderer = new THREE.WebGLRenderer({canvas: el,@@ -77,7 +77,7 @@ Anything that accepts an existing canvas plugs in directly; a detached canvas is| `ref` | `(canvas: HTMLCanvasElement) => void` | **required** | Receives the backing canvas at materialization. || `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`). `<SurfacePaint>` takes no children.+Like all paints it stacks with siblings in document order and clips to the parent's box (including `cornerRadius`). `<surfacePaint>` takes no children.## Persistence and export@@ -87,4 +87,4 @@ The compiled module is persisted with the document, so the drawing is reproducib- Duplicating or copy-pasting a mounted surface yields a static copy (the drawing does not re-run for the copy); re-mount to get a fresh animated instance.- Only the `ref` attribute form on the element itself is routed; refs inside spread props are not.-- A real DOM `<canvas>` is not available inside [`<Html>`](./html-paint.md) content — its pixels don't survive the html-in-canvas rasterization. Use `<Surface>` for hand-drawn graphics instead.+- A real DOM `<canvas>` is not available inside [`<html>`](./html-paint.md) content — its pixels don't survive the html-in-canvas rasterization. Use `<surface>` for hand-drawn graphics instead.diff --git a/apps/cli/reference/jsx/text.md b/apps/cli/reference/jsx/text.mdindex debc1ea7..6803248c 100644--- a/apps/cli/reference/jsx/text.md+++ b/apps/cli/reference/jsx/text.md@@ -1,11 +1,11 @@-# `<Text>`+# `<text>`-A text node; children become editable glyphs. Because the box defaults to the parent's box, a centered full-frame title is simply `<Text textAlign="center" textBaseline="middle">…</Text>`.+A text node; children become editable glyphs. Because the box defaults to the parent's box, a centered full-frame title is simply `<text textAlign="center" textBaseline="middle">…</text>`.```tsx-<Text fill="#FFFFFF" fontSize={128} fontWeight="bold" textAlign="center" textBaseline="middle">+<text fill="#FFFFFF" fontSize={128} fontWeight="bold" textAlign="center" textBaseline="middle">Hello World-</Text>+</text>```## Propsdiff --git a/apps/cli/reference/jsx/timing.md b/apps/cli/reference/jsx/timing.mdindex d7d065b5..de47d2d7 100644--- a/apps/cli/reference/jsx/timing.md+++ b/apps/cli/reference/jsx/timing.md@@ -13,15 +13,15 @@ Timing splits the two independent questions a clip answers: **where it sits on t- `start` / `end` place the clip on the parent timeline. `sourceIn` / `sourceOut` select which part of the source plays. On-timeline duration always equals the played source length, so `end - start == sourceOut - sourceIn`.- **`end` and `sourceOut` are two spellings of the same out edge** — the clip's end in timeline time (`end`) versus source time (`sourceOut`). Set one; the last one set wins.-- Sourceless nodes (`<Rect>`, `<Group>`, `<Text>`) have no footage to trim, so you place them with `start` / `end` alone.+- Sourceless nodes (`<rect>`, `<group>`, `<text>`) have no footage to trim, so you place them with `start` / `end` alone.- Instead of setting `start`, a media node can derive its placement from another node's audio with `syncTo` (see [audio-sync.md](./audio-sync.md)).-- If timing is omitted, a media node fits its natural duration at `start` 0, and a group auto-fits its children. A [`<Sequence>`](./sequences.md) does not position its children for you: give each an explicit `start` (the next clip's `start` is the previous clip's end).+- If timing is omitted, a media node fits its natural duration at `start` 0, and a group auto-fits its children. A [`<sequence>`](./sequences.md) does not position its children for you: give each an explicit `start` (the next clip's `start` is the previous clip's end).> Examples:-> - `<Rect start={2} end={5} fill="red" />` — a rectangle on screen from timeline second 2 to 5.-> - `<Video start={5} sourceIn={10} sourceOut={20} />` — plays source seconds 10–20 (a 10-second clip) beginning at timeline second 5.-> - `<Video start={2} end={5} sourceIn={10} />` — the same source starting at 10 s, stretched to fill the timeline window 2–5 (so it plays source 10–13).-> - `<Video start={0} sourceIn={1} />` — trims the first second off the head and places the clip at the top of the timeline.+> - `<rect start={2} end={5} fill="red" />` — a rectangle on screen from timeline second 2 to 5.+> - `<video start={5} sourceIn={10} sourceOut={20} />` — plays source seconds 10–20 (a 10-second clip) beginning at timeline second 5.+> - `<video start={2} end={5} sourceIn={10} />` — the same source starting at 10 s, stretched to fill the timeline window 2–5 (so it plays source 10–13).+> - `<video start={0} sourceIn={1} />` — trims the first second off the head and places the clip at the top of the timeline.## Time formatsdiff --git a/apps/cli/reference/jsx/transitions.md b/apps/cli/reference/jsx/transitions.mdindex 7b9bddb3..1017929e 100644--- a/apps/cli/reference/jsx/transitions.md+++ b/apps/cli/reference/jsx/transitions.md@@ -1,13 +1,13 @@# Transitions-`transition` declares a transition **into the next clip**, set on the **outgoing** clip and rendered centered on the cut. It is valid only on direct children of [`<Sequence>`](./sequences.md).+`transition` declares a transition **into the next clip**, set on the **outgoing** clip and rendered centered on the cut. It is valid only on direct children of [`<sequence>`](./sequences.md).```tsx-<Sequence>- <Video src="/Movies/intro.mp4" start={0} end={12} transition={{ type: "fadeToBlack", duration: "20f" }} />- <Video src="/Movies/main.mp4" start={12} end={24} transition={{}} /> {/* dissolve, 1s */}- <Video src="/Movies/outro.mp4" start={24} end={30} />-</Sequence>+<sequence>+ <video src="/Movies/intro.mp4" start={0} end={12} transition={{ type: "fadeToBlack", duration: "20f" }} />+ <video src="/Movies/main.mp4" start={12} end={24} transition={{}} /> {/* dissolve, 1s */}+ <video src="/Movies/outro.mp4" start={24} end={30} />+</sequence>``````tsdiff --git a/apps/cli/reference/jsx/video.md b/apps/cli/reference/jsx/video.mdindex 4b5baab2..2b7e26f9 100644--- a/apps/cli/reference/jsx/video.md+++ b/apps/cli/reference/jsx/video.md@@ -1,9 +1,9 @@-# `<Video>`+# `<video>`A video clip. `src` resolves to a video asset (see [media.md](./media.md)); when timing is omitted, the node fits its natural duration (see [timing.md](./timing.md)).```tsx-<Video src="/Movies/main.mp4" start={0} sourceIn={1} sourceOut={13} volume={-3} />+<video src="/Movies/main.mp4" start={0} sourceIn={1} sourceOut={13} volume={-3} />```## Propsdiff --git a/apps/cli/reference/mount.md b/apps/cli/reference/mount.mdindex 999d6ff3..1386591d 100644--- a/apps/cli/reference/mount.md+++ b/apps/cli/reference/mount.md@@ -1,6 +1,6 @@# `dapi mount (<path> | --code <str>)`-Compiles a Solid JSX project module and executes it in the app, mounting the rendered roots into the document. Like reloading a webpage, re-mounting rebuilds the roots in place instead of adding copies: every top-level element declares its identity in the JSX with a `key`, and `<Scene key="intro">` replaces the node carrying that key (or creates it).+Compiles a Solid JSX project module and executes it in the app, mounting the rendered roots into the document. Like reloading a webpage, re-mounting rebuilds the roots in place instead of adding copies: every top-level element declares its identity in the JSX with a `key`, and `<scene key="intro">` replaces the node carrying that key (or creates it).The full JSX code syntax lives in [jsx/](./jsx/README.md); start with the [pipeline](./jsx/README.md#pipeline) and [roots](./jsx/roots.md).@@ -13,7 +13,7 @@ Exactly one of:## Lifecycle-A mount stays live: its reactive graph keeps running after the command returns, so signals, effects, timers, and [`useTicker`](./jsx/lifecycle.md#useticker) keep driving the mounted entities. The compiled module is persisted with the document and re-executed in every context, so the mount is restored on reload and its ticker-driven [`<Surface>`](./jsx/surface-paint.md)/[`<Html>`](./jsx/html-paint.md) animate in exports and captures (the module's structure must be deterministic). See [jsx/lifecycle.md](./jsx/lifecycle.md).+A mount stays live: its reactive graph keeps running after the command returns, so signals, effects, timers, and [`useTicker`](./jsx/lifecycle.md#useticker) keep driving the mounted entities. The compiled module is persisted with the document and re-executed in every context, so the mount is restored on reload and its ticker-driven [`<surface>`](./jsx/surface-paint.md)/[`<html>`](./jsx/html-paint.md) animate in exports and captures (the module's structure must be deterministic). See [jsx/lifecycle.md](./jsx/lifecycle.md).## Outputdiff --git a/apps/cli/reference/node/insert.md b/apps/cli/reference/node/insert.mdindex 0fe66ee8..ed79e398 100644--- a/apps/cli/reference/node/insert.md+++ b/apps/cli/reference/node/insert.md@@ -4,12 +4,12 @@ Compiles an inline JSX fragment and inserts its rendered roots as children of anThe payload is **bare JSX tags** — no `export default`, no file path. Unlike `mount`, an insert renders once and is then discarded: it is never persisted, restored, or kept live, so a component that relies on reactivity (signals, effects, `useTicker`) has nothing to drive it. Reach for [`mount`](../mount.md) when you want a live, reproducible program. The full JSX syntax lives in [jsx/](../jsx/README.md).-The rendered roots must be valid as children of the target parent, following the JSX containment rules: a node parent takes any element or paint root except `<Scene>` (scenes only exist at the document top level) and `<ColorStop>`; a gradient paint parent takes only `<ColorStop>` roots. That is how a stop is added to an existing gradient (`node insert <paintId> '<ColorStop offset={0.5} color="#FF0055" />'`); other sub-entities take no children.+The rendered roots must be valid as children of the target parent, following the JSX containment rules: a node parent takes any element or paint root except `<scene>` (scenes only exist at the document top level) and `<colorStop>`; a gradient paint parent takes only `<colorStop>` roots. That is how a stop is added to an existing gradient (`node insert <paintId> '<colorStop offset={0.5} color="#FF0055" />'`); other sub-entities take no children.## Input- `<parentId>`: entity id of the parent to insert into (required)-- `<code>`: inline JSX tags to insert, e.g. `'<Rect width={100} height={100} />'` (required). Bare tags only — the source is rejected before contacting the app if it contains `export default` or doesn't look like JSX.+- `<code>`: inline JSX tags to insert, e.g. `'<rect width={100} height={100} />'` (required). Bare tags only — the source is rejected before contacting the app if it contains `export default` or doesn't look like JSX.- `-i, --index <N>`: the inserted node's 0-based position among the parent's children, a non-negative integer (optional; default = append after the last child; values past the end are clamped). Node roots only: paints stack in insertion order and color stops render sorted by `offset`, so `--index` is rejected for them.## Output@@ -18,4 +18,4 @@ None.## Errors-Exits non-zero if `<code>` is not a bare JSX fragment (contains `export default`, or has no tags), if `<parentId>` doesn't resolve to a live entity, if compilation or evaluation fails, if a rendered root is invalid as a child of the parent (e.g. a `<Scene>`, or a non-`<ColorStop>` in a gradient paint), or if `--index` is given for a paint or color stop root. On any of these, **nothing is inserted**.+Exits non-zero if `<code>` is not a bare JSX fragment (contains `export default`, or has no tags), if `<parentId>` doesn't resolve to a live entity, if compilation or evaluation fails, if a rendered root is invalid as a child of the parent (e.g. a `<scene>`, or a non-`<colorStop>` in a gradient paint), or if `--index` is given for a paint or color stop root. On any of these, **nothing is inserted**.diff --git a/apps/cli/src/compile-project.ts b/apps/cli/src/compile-project.tsindex 65745387..fda7ee2e 100644--- a/apps/cli/src/compile-project.ts+++ b/apps/cli/src/compile-project.ts@@ -7,6 +7,7 @@ import { readFile } from "node:fs/promises";import { isAbsolute, resolve } from "node:path";import { transformAsync } from "@babel/core";import { build } from "esbuild";+import type { NodePath, PluginObj, types as BabelTypes } from "@babel/core";import type { Plugin } from "esbuild";import presetSolid from "babel-preset-solid";import presetTypescript from "@babel/preset-typescript";@@ -92,24 +93,121 @@ function resolveBareSpecifier(spec: string, { cdnBase, importMap }: ResolverConfreturn `${cdnBase}/${spec}`;}-// Identifiers babel auto-imports from `moduleName` when used as JSX tags-// without an in-scope binding: Solid's control-flow defaults plus the-// PascalCase composition elements, so project files need no imports for tags.-// Element names must match the components in packages/jsx/src/elements.ts.-const BUILT_INS = [- "For", "Show", "Switch", "Match", "Suspense", "SuspenseList", "Portal", "Index", "Dynamic", "ErrorBoundary",- "Scene", "Group", "Rect", "Video", "Image", "Audio", "Text", "Sequence", "Captions",- "SolidPaint", "LinearGradientPaint", "RadialGradientPaint", "ColorStop",- "HtmlPaint", "Html", "SurfacePaint", "Surface",-];+// The camelCase composition vocabulary, canonicalized to the PascalCase+// components in packages/jsx/src/elements.ts before babel-preset-solid runs.+// Project files write `<rect>`; the renderer keeps receiving `Rect`, so a+// tag's case still decides its environment at runtime.+const BUILT_IN_TAGS: Record<string, string> = {+ scene: "Scene", group: "Group", rect: "Rect", video: "Video", image: "Image",+ audio: "Audio", text: "Text", sequence: "Sequence", captions: "Captions",+ solidPaint: "SolidPaint", linearGradientPaint: "LinearGradientPaint",+ radialGradientPaint: "RadialGradientPaint", colorStop: "ColorStop",+ htmlPaint: "HtmlPaint", html: "Html", surfacePaint: "SurfacePaint", surface: "Surface",+};++// Tags that exist in both vocabularies. Every collision is SVG-only (HTML has+// no <rect>/<text>/<image>), and SVG content always sits under an SVG-only+// container, so lexical ancestry resolves them: inside one of the containers+// below the tag is SVG content, everywhere else it's a composition element.+// SVG fragments split into their own components must keep an <svg> or <g>+// wrapper; a bare fragment compiles as composition and the mount rejects it.+const AMBIGUOUS_TAGS = new Set(["rect", "text", "image"]);++const SVG_CONTAINERS = new Set([+ "svg", "g", "defs", "symbol", "marker", "mask", "clipPath", "pattern",+ "filter", "linearGradient", "radialGradient", "textPath", "tspan", "switch",+]);++// Recognized-but-wrong capitalized tags fail at compile time with a pointed+// message; anything else unbound is left for the bundler/runtime as usual.+const PASCAL_ELEMENTS = new Map(Object.entries(BUILT_IN_TAGS).map(([camel, pascal]) => [pascal, camel]));++const SOLID_CONTROL_FLOW = new Set([+ "For", "Show", "Switch", "Match", "Suspense", "SuspenseList", "Index", "ErrorBoundary",+]);++/**+ * Rewrites camelCase composition tags to aliased imports of their PascalCase+ * components. Aliases (rather than the component names themselves) keep a+ * user binding that happens to be called `Text` or `Rect` from capturing a+ * lowercase tag.+ */+function canonicalizeTags({ types: t }: { types: typeof BabelTypes }): PluginObj {+ const hasSvgAncestor = (path: NodePath): boolean =>+ path.findParent(+ (p) =>+ p.isJSXElement() &&+ t.isJSXIdentifier(p.node.openingElement.name) &&+ SVG_CONTAINERS.has(p.node.openingElement.name.name),+ ) !== null;++ return {+ visitor: {+ // The whole rewrite runs up front in Program enter: babel merges plugin+ // and preset visitors into one traversal, and babel-preset-solid+ // consumes an entire JSX tree on its first visit, so a JSXElement-level+ // visitor here would lose the race for every non-root tag.+ Program(path) {+ // PascalCase name -> local alias, per file.+ const aliases = new Map<string, string>();++ path.traverse({+ JSXElement(elementPath) {+ const name = elementPath.node.openingElement.name;+ if (!t.isJSXIdentifier(name)) return;++ if (/^[A-Z]/.test(name.name) && !elementPath.scope.hasBinding(name.name)) {+ const camel = PASCAL_ELEMENTS.get(name.name);+ if (camel !== undefined) {+ throw elementPath.buildCodeFrameError(+ `<${name.name}> is not a tag; write the composition element as <${camel}>`,+ );+ }+ if (SOLID_CONTROL_FLOW.has(name.name)) {+ throw elementPath.buildCodeFrameError(+ `<${name.name}> needs an import: add \`import { ${name.name} } from "solid-js"\``,+ );+ }+ return;+ }++ const pascal = BUILT_IN_TAGS[name.name];+ if (pascal === undefined) return;+ if (AMBIGUOUS_TAGS.has(name.name) && hasSvgAncestor(elementPath)) return;++ let alias = aliases.get(pascal);+ if (alias === undefined) {+ alias = `_$${pascal}`;+ aliases.set(pascal, alias);+ }+ elementPath.node.openingElement.name = t.jsxIdentifier(alias);+ if (elementPath.node.closingElement) {+ elementPath.node.closingElement.name = t.jsxIdentifier(alias);+ }+ },+ });++ if (aliases.size === 0) return;+ const specifiers = [...aliases].map(([name, alias]) =>+ t.importSpecifier(t.identifier(alias), t.identifier(name)),+ );+ path.unshiftContainer(+ "body",+ t.importDeclaration(specifiers, t.stringLiteral("@diffusionstudio/jsx")),+ );+ },+ },+ };+}async function transformSolidJsx(source: string, filename: string): Promise<string> {const result = await transformAsync(source, {filename,babelrc: false,configFile: false,+ plugins: [canonicalizeTags],presets: [- [presetSolid, { generate: "universal", moduleName: "@diffusionstudio/jsx", builtIns: BUILT_INS }],+ [presetSolid, { generate: "universal", moduleName: "@diffusionstudio/jsx" }],[presetTypescript, {}],],sourceMaps: "inline",@@ -159,7 +257,7 @@ function resolverPlugin(config: ResolverConfig): Plugin {export type CompileInput = { path: string } | { code: string };// `--code` ergonomics: a bare JSX expression (no `export default`) is wrapped-// into a component module, so one-liners like `--code '<Rect width={10} />'`+// into a component module, so one-liners like `--code '<rect width={10} />'`function wrapBareJsx(code: string): string {if (/\bexport\s+default\b/.test(code)) return code;return `export default () => (\n${code.trim().replace(/;+\s*$/, "")}\n);`;diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.tsindex ab6db483..725ae9e2 100644--- a/apps/cli/src/index.ts+++ b/apps/cli/src/index.ts@@ -739,7 +739,7 @@ async function nodeInsert(parentId: string, source: string, opts: NodeInsertOptiprocess.exit(1);}if (!/<\s*[A-Za-z]/.test(source)) {- console.error("`dapi node insert` expects JSX tags, e.g. '<Rect width={10} height={10} />'.");+ console.error("`dapi node insert` expects JSX tags, e.g. '<rect width={10} height={10} />'.");process.exit(1);}@@ -1136,7 +1136,7 @@ programprogram.command("mount").description(- `Compile a Solid JSX project module and mount its roots into the canvas. Re-mounting reconciles rather than duplicates: each top-level element carries a \`key\`, and a root replaces the node with that key or creates it (a new <Scene key> becomes the active scene and the camera focuses it). A mount stays live: its reactive graph keeps running (signals, effects, timers, \`useTicker\`), and the persisted module is re-executed in every context, so the mount is restored on reload and ticker-driven <Surface>/<Html> animate in exports and captures (structure must be deterministic). Long-running when the module declares AI assets (blocks until generation finishes). Compile errors fail before the app is contacted; inspect the result with \`dapi context\` or \`dapi node tree\`.`,+ `Compile a Solid JSX project module and mount its roots into the canvas. Re-mounting reconciles rather than duplicates: each top-level element carries a \`key\`, and a root replaces the node with that key or creates it (a new <scene key> becomes the active scene and the camera focuses it). A mount stays live: its reactive graph keeps running (signals, effects, timers, \`useTicker\`), and the persisted module is re-executed in every context, so the mount is restored on reload and ticker-driven <surface>/<html> animate in exports and captures (structure must be deterministic). Long-running when the module declares AI assets (blocks until generation finishes). Compile errors fail before the app is contacted; inspect the result with \`dapi context\` or \`dapi node tree\`.`,).argument("[path]", "path to a .tsx / .jsx / .ts / .js entry module").option("--code <str>", "inline module source; export default wrapper optional for bare JSX")@@ -1401,10 +1401,10 @@ nodenode.command("insert").description(- `Insert JSX tags as children of an existing entity. The payload is an inline JSX fragment, e.g. \`'<Rect width={10} height={10} />'\` — bare tags, no \`export default\`: an insert renders once and is discarded, so there is no live graph to drive (use \`dapi mount\` for anything reactive). Otherwise it shares the \`mount\` pipeline, including AI asset generation, but inserts fresh entities every run rather than reconciling by key, and deletes nothing. Roots must be valid children of the parent (a node takes any element or paint except <Scene> and <ColorStop>; a gradient paint takes only <ColorStop> roots, which is how you add a stop to a gradient).`,+ `Insert JSX tags as children of an existing entity. The payload is an inline JSX fragment, e.g. \`'<rect width={10} height={10} />'\` — bare tags, no \`export default\`: an insert renders once and is discarded, so there is no live graph to drive (use \`dapi mount\` for anything reactive). Otherwise it shares the \`mount\` pipeline, including AI asset generation, but inserts fresh entities every run rather than reconciling by key, and deletes nothing. Roots must be valid children of the parent (a node takes any element or paint except <scene> and <colorStop>; a gradient paint takes only <colorStop> roots, which is how you add a stop to a gradient).`,)- .argument("<parentId>", "entity id of the parent to insert into — a node, or a gradient paint for <ColorStop> roots")- .argument("<code>", "JSX tags to insert, e.g. '<Rect width={10} height={10} />' (no export default)")+ .argument("<parentId>", "entity id of the parent to insert into — a node, or a gradient paint for <colorStop> roots")+ .argument("<code>", "JSX tags to insert, e.g. '<rect width={10} height={10} />' (no export default)").option("-i, --index <n>", "0-based position among the parent's existing children (node roots only; default: append at the end)").action((parentId: string, code: string, opts: NodeInsertOptions) => nodeInsert(parentId, code, opts));@@ -1516,7 +1516,7 @@ programprogram.command("fonts").description(- `List the local fonts available on this machine (macOS only; does not require the app). These family names are valid \`fontFamily\` values on <Text>; each family lists its variants.`,+ `List the local fonts available on this machine (macOS only; does not require the app). These family names are valid \`fontFamily\` values on <text>; each family lists its variants.`,).option("-f, --family <pattern>", "filter to families whose name contains <pattern> (case-insensitive)").option("-w, --weight <weights...>", "filter to variants with the given CSS weight(s), e.g. -w 400 700")diff --git a/apps/web/src/utils/jsx.ts b/apps/web/src/utils/jsx.tsindex 63389a50..7ec2bf1f 100644--- a/apps/web/src/utils/jsx.ts+++ b/apps/web/src/utils/jsx.ts@@ -61,7 +61,10 @@ export class EntityNode {* content — the ECS world and the DOM are the scene graph, with no shadow* tree in between. A tag's case decides which side a node lands on at* creation (PascalCase composition elements mint entities, lowercase tags- * mint DOM nodes), so `setProperty` always has a live target.+ * mint DOM nodes), so `setProperty` always has a live target. Project files+ * author camelCase tags; the CLI compile canonicalizes them to the PascalCase+ * components (SVG ancestry keeps the shared rect/text/image names DOM-side),+ * so the case split holds by the time tags reach this document.*/type HostNode = EntityNode | Element | Text;@@ -624,7 +627,7 @@ export class WorldDocument implements ProjectDocument<HostNode> {// belong to the composition elements.assert(tag !== "audio" && tag !== "video",- `<${tag}> is not supported as html content; use the <${tag === "audio" ? "Audio" : "Video"}> composition element instead`,+ `<${tag}> is not supported as html content; media plays through the <${tag}> composition element outside the html subtree`,);return SVGElements.has(tag)? document.createElementNS(SVG_NS, tag)@@ -1312,7 +1315,10 @@ export class WorldDocument implements ProjectDocument<HostNode> {const c = world.components;if (parent instanceof Element) {- assert(node instanceof Element || node instanceof Text, "a composition element cannot be <Html> content");+ assert(+ node instanceof Element || node instanceof Text,+ "a composition element cannot be <html> content; an SVG fragment (<rect>/<text>/<image>) compiles as SVG only inside <svg> or <g>; wrap it",+ );parent.insertBefore(node, anchor instanceof Node ? anchor : null);return;}@@ -1354,7 +1360,10 @@ export class WorldDocument implements ProjectDocument<HostNode> {}if (parent !== STAGE) {- assert(!this.htmlHosts.has(parent.eid), "a composition element cannot be <Html> content");+ assert(+ !this.htmlHosts.has(parent.eid),+ "a composition element cannot be <html> content; an SVG fragment (<rect>/<text>/<image>) compiles as SVG only inside <svg> or <g>; wrap it",+ );// Adopted entities already sit under their persisted parent, so this// no-ops for them on the initial adopt render; afterwards it moves and// resurrects them like any other entity (e.g. a <For> shuffling rows).diff --git a/docs/cli.md b/docs/cli.mdindex 51ea8ed4..e464c434 100644--- a/docs/cli.md+++ b/docs/cli.md@@ -60,7 +60,7 @@ dapi node insert <parentId> (<path> | --code <str>) [-i, --index <N>]Same pipeline as `mount`, but inserts the rendered roots as children of an existing entity instead of mounting document roots. Roots take no `key`; every run inserts fresh nodes. `--index` sets the position among the parent's children (node roots only). Also how you extend sub-entities, e.g. adding a stop to a gradient:```sh-dapi node insert <paintId> --code '<ColorStop offset={0.5} color="#FF0055" />'+dapi node insert <paintId> --code '<colorStop offset={0.5} color="#FF0055" />'```### `node patch`diff --git a/docs/composition.md b/docs/composition.mdindex 695297d6..88bad1ad 100644--- a/docs/composition.md+++ b/docs/composition.md@@ -3,18 +3,15 @@Compositions are **Solid JSX modules**. `dapi mount` compiles the module, runs it in the app, and renders every JSX element into an editable node in the document: no hidden DOM, no CSS, no layout pass. All positioning is explicit pixels.```tsx-import { Scene } from "@diffusionstudio/jsx";-export default function Project() {return (- <Scene key="intro" name="Intro" width={1920} height={1080} fill="black">+ <scene key="intro" name="Intro" width={1920} height={1080} fill="black">{/* ... */}- </Scene>+ </scene>);}```-The element import is optional at runtime — the compiler auto-imports PascalCase elements used without an in-scope binding — but explicit imports make the file typecheck (`tsc` doesn't see the auto-import).The module's default export is the project component. Solid's control flow (`<For>`, `<Show>`, …) and primitives (`createSignal`, `createMemo`, …) are available to *compose* the tree; the render is one-shot: after commit, the nodes belong to the document and signal changes no longer affect it. The update path is re-running the mount.@@ -28,25 +25,25 @@ Every top-level element declares its identity with a `key`:- Keyed nodes the render no longer produces are **deleted**; the mount owns its keyed roots. Unkeyed nodes (made by hand in the editor) are never touched.- Keys must be unique within a render. Give roots a `name` too: the key identifies, the name labels.-The first rendered root becomes the active scene. New roots are auto-placed on the canvas near the viewport center; `<Scene>` has no `x`/`y` because canvas arrangement is an editor concern, not part of the composition.+The first rendered root becomes the active scene. New roots are auto-placed on the canvas near the viewport center; `<scene>` has no `x`/`y` because canvas arrangement is an editor concern, not part of the composition.## Elements| Element | What it makes || --- | --- |-| `<Scene>` | A scene; clips children to its `width`×`height`. Document root only; scenes don't nest. |-| `<Group>` | Container with a transform; give it `fill` to draw a rectangle. |-| `<Rect>` | A filled rectangle. |-| `<Text>` | Editable text. |-| `<Video>` / `<Image>` | Media; `src` is required. |-| `<Audio>` | Sound only, no spatial props. |-| `<Sequence>` | Track container for back-to-back clips (positions are explicit); hosts transitions. |-| `<Captions>` | Styled captions: transcribes the scene's audio, or mounts a transcript given via `src`. |-| `<Html>` | A rectangle whose children are HTML/SVG, laid out by the browser at the node's box size and drawn into it. Equivalent to a `<Rect>` with an `<HtmlPaint>`. |-| `<Surface>` | A rectangle whose `ref` hands you a canvas to draw yourself (2d, webgl, webgpu); the bitmap is sampled into the box every frame. Equivalent to a `<Rect>` with a `<SurfacePaint>`. |-| `<SolidPaint>`, `<LinearGradientPaint>`, `<RadialGradientPaint>`, `<ColorStop>` | Fills, declared as children; see [Paints](#paints). |--User-defined components are ordinary Solid components; only the built-in PascalCase elements produce nodes.+| `<scene>` | A scene; clips children to its `width`×`height`. Document root only; scenes don't nest. |+| `<group>` | Container with a transform; give it `fill` to draw a rectangle. |+| `<rect>` | A filled rectangle. |+| `<text>` | Editable text. |+| `<video>` / `<image>` | Media; `src` is required. |+| `<audio>` | Sound only, no spatial props. |+| `<sequence>` | Track container for back-to-back clips (positions are explicit); hosts transitions. |+| `<captions>` | Styled captions: transcribes the scene's audio, or mounts a transcript given via `src`. |+| `<html>` | A rectangle whose children are HTML/SVG, laid out by the browser at the node's box size and drawn into it. Equivalent to a `<rect>` with an `<htmlPaint>`. |+| `<surface>` | A rectangle whose `ref` hands you a canvas to draw yourself (2d, webgl, webgpu); the bitmap is sampled into the box every frame. Equivalent to a `<rect>` with a `<surfacePaint>`. |+| `<solidPaint>`, `<linearGradientPaint>`, `<radialGradientPaint>`, `<colorStop>` | Fills, declared as children; see [Paints](#paints). |++User-defined components are ordinary Solid components; only the built-in camelCase elements produce nodes.### Common props@@ -60,26 +57,26 @@ User-defined components are ordinary Solid components; only the built-in PascalC| `opacity` | `1` | `0`–`1`. Animatable. || `cornerRadius` | `0` | Px. Animatable. || `start`, `end`, `sourceIn`, `sourceOut` | see [Timing](#timing) | Temporal placement. |-| `transition` | none | Cut into the next clip; `<Sequence>` children only. See [Transitions](#transitions). |+| `transition` | none | Cut into the next clip; `<sequence>` children only. See [Transitions](#transitions). |Animatable props also take a keyframe list — see [Animation](#animation).**Every box defaults to its parent's box**, the JSX analog of `position: absolute; inset: 0`. So a centered full-frame title is just:```tsx-<Text textAlign="center" textBaseline="middle" fontSize={128}>Hello</Text>+<text textAlign="center" textBaseline="middle" fontSize={128}>Hello</text>```### Per-element props-- **`<Scene>`**: `key`, `width`, `height` (all required), `name`, `fill`. No timing or transform props.-- **`<Rect>` / `<Group>`**: `fill` (any CSS color; alpha is ignored, use `opacity`).-- **`<Video>`**: `src` (required), `objectFit` (`"cover"` | `"contain"` | `"fill"`, default `"cover"`), `volume` (dB; `0` = unity, negative attenuates), `muted`, `syncTo` (see [Audio sync](#audio-sync)).-- **`<Image>`**: `src` (required), `objectFit` (default `"contain"`).-- **`<Audio>`**: `src` (required), `volume` (dB; `0` = unity, negative attenuates), `muted`, `syncTo`, timing props.-- **`<Text>`**: string children (required), `fontFamily` (see `dapi fonts`), `fontSize`, `fontWeight`, `fontStyle`, `fill`, `textAlign`, `textBaseline`.-- **`<Html>`**: HTML/SVG children. Fully reactive: signals in attributes, styles, and text update the drawn content. Event handlers are dropped (the content is painted, not interactive).-- **`<Surface>`**: `ref` (required, callback form) receives the backing `HTMLCanvasElement` once at materialization; draw with any context type, create effects inside the ref to redraw from signals or the ticker.+- **`<scene>`**: `key`, `width`, `height` (all required), `name`, `fill`. No timing or transform props.+- **`<rect>` / `<group>`**: `fill` (any CSS color; alpha is ignored, use `opacity`).+- **`<video>`**: `src` (required), `objectFit` (`"cover"` | `"contain"` | `"fill"`, default `"cover"`), `volume` (dB; `0` = unity, negative attenuates), `muted`, `syncTo` (see [Audio sync](#audio-sync)).+- **`<image>`**: `src` (required), `objectFit` (default `"contain"`).+- **`<audio>`**: `src` (required), `volume` (dB; `0` = unity, negative attenuates), `muted`, `syncTo`, timing props.+- **`<text>`**: string children (required), `fontFamily` (see `dapi fonts`), `fontSize`, `fontWeight`, `fontStyle`, `fill`, `textAlign`, `textBaseline`.+- **`<html>`**: HTML/SVG children. Fully reactive: signals in attributes, styles, and text update the drawn content. Event handlers are dropped (the content is painted, not interactive).+- **`<surface>`**: `ref` (required, callback form) receives the backing `HTMLCanvasElement` once at materialization; draw with any context type, create effects inside the ref to redraw from signals or the ticker.These same props are what `dapi node patch` assigns on existing nodes.@@ -92,7 +89,7 @@ These same props are what `dapi node patch` assigns on existing nodes.- an **asset id**: an imported library asset (see `dapi asset tree`)- an **`AssetRef`**: the value returned by a `generate.*` declaration-To read a source's raw bytes inside an effect instead of mounting it as a node, pass the same input to `useFile`, which resolves it to a `File`. It returns Solid's `createResource` tuple (`[file, { mutate, refetch }]`): the `file` accessor reads `undefined` until it resolves, then the `File`. Useful for drawing a library image onto a `<Surface>` or parsing a data file:+To read a source's raw bytes inside an effect instead of mounting it as a node, pass the same input to `useFile`, which resolves it to a `File`. It returns Solid's `createResource` tuple (`[file, { mutate, refetch }]`): the `file` accessor reads `undefined` until it resolves, then the `File`. Useful for drawing a library image onto a `<surface>` or parsing a data file:```tsximport { createSignal, createEffect } from "solid-js";@@ -108,7 +105,7 @@ createEffect(async () => {el.getContext("2d")!.drawImage(await createImageBitmap(f), 0, 0);});-// <Surface ref={setCanvas} width={640} height={360} />+// <surface ref={setCanvas} width={640} height={360} />```## Timing@@ -121,35 +118,35 @@ createEffect(async () => {| `sourceIn` / `sourceOut` | The source window to play. Default: the source's natural extent. `end` and `sourceOut` are the same out edge in timeline vs. source time. |```tsx-<Video src="/Movies/clip.mp4" start={5} sourceIn={10} sourceOut={20} />+<video src="/Movies/clip.mp4" start={5} sourceIn={10} sourceOut={20} />// plays source seconds 10-20 (a 10 s clip), beginning at timeline second 5-<Rect start={2} end={5} fill="red" />+<rect start={2} end={5} fill="red" />// a sourceless node placed straight on the timeline: on screen from 2 s to 5 s```-`<Sequence>` groups a track of back-to-back clips and hosts clip [transitions](#transitions). It does not position clips at mount — give each an explicit `start` (the next clip's `start` is the previous clip's end). In the editor it keeps children from overlapping as you drag or regroup them.+`<sequence>` groups a track of back-to-back clips and hosts clip [transitions](#transitions). It does not position clips at mount — give each an explicit `start` (the next clip's `start` is the previous clip's end). In the editor it keeps children from overlapping as you drag or regroup them.### Audio sync`syncTo` computes a node's `start` by cross-correlating its audio against another element's audio (named by `key`), so two recordings of the same take coincide on the timeline: a lav track against camera audio, two cameras, two microphones. Any pairing with audio tracks works (audio-to-video, audio-to-audio, video-to-video). `muted` silences the side that shouldn't be heard; alignment reads source content regardless of `muted` or `volume`.```tsx-<Video key="camera" src="/Movies/take-3.mp4" sourceOut={45} muted />-<Audio src="/Movies/lav.wav" syncTo="camera" />+<video key="camera" src="/Movies/take-3.mp4" sourceOut={45} muted />+<audio src="/Movies/lav.wav" syncTo="camera" />````syncTo` and `start` are mutually exclusive; `sourceIn`/`sourceOut` stay yours, and when omitted the window defaults to the overlap with the target's window. Alignment runs after generated assets land (either side may be generated), locally and cached, and blocks the mount; an alignment too weak to trust fails the mount and the node keeps its default placement.## Transitions-A clip inside a `<Sequence>` takes a `transition` prop rendering the cut into the clip that follows it:+A clip inside a `<sequence>` takes a `transition` prop rendering the cut into the clip that follows it:```tsx-<Sequence>- <Video src="/Movies/a.mp4" start={0} end={8} transition={{ type: "fadeToBlack", duration: 0.5 }} />- <Video src="/Movies/b.mp4" start={8} />-</Sequence>+<sequence>+ <video src="/Movies/a.mp4" start={0} end={8} transition={{ type: "fadeToBlack", duration: 0.5 }} />+ <video src="/Movies/b.mp4" start={8} />+</sequence>```| Type | Effect |@@ -161,7 +158,7 @@ A clip inside a `<Sequence>` takes a `transition` prop rendering the cut into th| `"fadeToWhite"` | Same, through white. |- `duration` takes any [time format](cli.md#time-values) (default 1 s) and runs centered on the cut. Timing is untouched: the clips stay back-to-back and the renderer overlaps them only while the transition runs.-- `transition` only renders on a direct child of `<Sequence>` that has a clip after it. On the last clip it waits until one follows, matching the editor's inspector; outside a sequence the engine drops it.+- `transition` only renders on a direct child of `<sequence>` that has a clip after it. On the last clip it waits until one follows, matching the editor's inspector; outside a sequence the engine drops it.- It's the same transition the inspector edits, and `dapi node patch` takes it like any other prop: a partial value merges into the clip's existing transition (`{ "id": 42, "transition": { "duration": 2 } }` keeps the type), and `"transition": null` removes it.## Animation@@ -169,7 +166,7 @@ A clip inside a `<Sequence>` takes a `transition` prop rendering the cut into thAnimatable props (`x`, `y`, `width`, `height`, `rotation`, `opacity`, `cornerRadius`, `volume`, `color`, `offset`) accept a keyframe list in place of a static value:```tsx-<Image+<imagesrc="/photo.jpg"start={0} end={5}x={[@@ -196,18 +193,18 @@ Animatable props (`x`, `y`, `width`, `height`, `rotation`, `opacity`, `cornerRad## Paints-A node's fill is a **paint child**; the `fill` prop is shorthand for a solid paint. Declaring paints as children unlocks gradients and stacking (later paints render on top, including over the media paint of a `<Video>` or `<Image>`):+A node's fill is a **paint child**; the `fill` prop is shorthand for a solid paint. Declaring paints as children unlocks gradients and stacking (later paints render on top, including over the media paint of a `<video>` or `<image>`):```tsx-<Rect width={640} height={360} cornerRadius={24}>- <LinearGradientPaint rotation={90}>- <ColorStop offset={0} color="#FF0055" />- <ColorStop offset={1} color="#0055FF" />- </LinearGradientPaint>-</Rect>+<rect width={640} height={360} cornerRadius={24}>+ <linearGradientPaint rotation={90}>+ <colorStop offset={0} color="#FF0055" />+ <colorStop offset={1} color="#0055FF" />+ </linearGradientPaint>+</rect>```-`<SolidPaint>` takes `color` (required) and `opacity`; gradient paints take `rotation` and `opacity` and only `<ColorStop>` children (`offset` and `color` required). Colors are any CSS color; alpha is ignored, use `opacity`. `<HtmlPaint>` draws browser-laid-out HTML/SVG children into the node's box; the `<Html>` element is shorthand for a `<Rect>` carrying one. `<SurfacePaint>` draws a canvas your `ref` callback owns into the node's box; the `<Surface>` element is likewise shorthand for a `<Rect>` carrying one.+`<solidPaint>` takes `color` (required) and `opacity`; gradient paints take `rotation` and `opacity` and only `<colorStop>` children (`offset` and `color` required). Colors are any CSS color; alpha is ignored, use `opacity`. `<htmlPaint>` draws browser-laid-out HTML/SVG children into the node's box; the `<html>` element is shorthand for a `<rect>` carrying one. `<surfacePaint>` draws a canvas your `ref` callback owns into the node's box; the `<surface>` element is likewise shorthand for a `<rect>` carrying one.## Generated assets@@ -234,10 +231,10 @@ Declarations are pure: nothing generates until the mount commits, and refs never## Captions-`<Captions />` inside a scene transcribes that scene's audio into a styled, timed caption node. It runs after generated assets land and [audio sync](#audio-sync) resolves (so it can caption generated voice-over at its final placement), attaches asynchronously, and is cached against the scene's audible mix, so re-mounting with unchanged audio doesn't re-transcribe.+`<captions />` inside a scene transcribes that scene's audio into a styled, timed caption node. It runs after generated assets land and [audio sync](#audio-sync) resolves (so it can caption generated voice-over at its final placement), attaches asynchronously, and is cached against the scene's audible mix, so re-mounting with unchanged audio doesn't re-transcribe.```tsx-<Captions preset="spotlight" colors={["#FF0055"]} />+<captions preset="spotlight" colors={["#FF0055"]} />```### Manual captions@@ -245,7 +242,7 @@ Declarations are pure: nothing generates until the mount commits, and refs never`src` supplies the transcript instead of transcribing: a path, URL, or asset id of an `.srt` or `.vtt` subtitle file, or a transcript `.json` (the `dapi transcribe` output format: `[{ text, words: [{ text, start, end }] }]`, times in seconds). Subtitle cues carry no word timings, so word-level presets highlight on timings synthesized within each cue.```tsx-<Captions src="./subtitles.srt" preset="classic" />+<captions src="./subtitles.srt" preset="classic" />```Times are scene-relative; set `start` to shift the whole caption track when the transcript was written against a clip that begins later in the scene.@@ -284,4 +281,4 @@ The CLI strips types without checking them; run `tsc --noEmit` for type safety.## Errors-Compile errors surface on stderr before the app is contacted. Evaluate/mount errors (invalid props, a root without `key`, nested `<Scene>`, an unknown or cyclic `syncTo` key, …) abort with **nothing inserted**. Generation errors surface after all generations settle; the mounted tree stays committed and the affected placeholder is left without media. Audio-sync failures (no decodable audio, no reliable alignment) surface the same way; the node keeps its default placement. Runtime errors map back to your source via sourcemaps.+Compile errors surface on stderr before the app is contacted. Evaluate/mount errors (invalid props, a root without `key`, nested `<scene>`, an unknown or cyclic `syncTo` key, …) abort with **nothing inserted**. Generation errors surface after all generations settle; the mounted tree stays committed and the affected placeholder is left without media. Audio-sync failures (no decodable audio, no reliable alignment) surface the same way; the node keeps its default placement. Runtime errors map back to your source via sourcemaps.diff --git a/docs/getting-started.md b/docs/getting-started.mdindex 906bb8dc..b9fd4d89 100644--- a/docs/getting-started.md+++ b/docs/getting-started.md@@ -50,9 +50,9 @@ dapi asset tree # the media library as a folder treeCompositions are Solid JSX modules rendered into the document with `dapi mount`. For a one-liner, pass code inline:```sh-dapi mount --code '<Scene key="hello" name="Hello" width={1920} height={1080} fill="black">- <Text textAlign="center" textBaseline="middle" fontSize={120} fill="white">Hello World</Text>-</Scene>'+dapi mount --code '<scene key="hello" name="Hello" width={1920} height={1080} fill="black">+ <text textAlign="center" textBaseline="middle" fontSize={120} fill="white">Hello World</text>+</scene>'```The `key` is the scene's stable identity: re-running the mount rebuilds that scene in place instead of adding a copy. For anything real, put the module in a file (`dapi mount hero.tsx`) and see [Writing compositions](composition.md).diff --git a/packages/jsx/README.md b/packages/jsx/README.mdindex 9ec52922..464cdbe2 100644--- a/packages/jsx/README.md+++ b/packages/jsx/README.md@@ -7,19 +7,19 @@ with `dapi mount`; every JSX element becomes an editable node in thecomposition — there is no hidden DOM, no CSS resolution, and no measuring pass.```tsx-import { Captions, Image, Scene, Text, generate } from "@diffusionstudio/jsx";+import { generate } from "@diffusionstudio/jsx";const hero = generate.image({ prompt: "A neon city at night, cinematic" });export default function Project() {return (- <Scene key="intro" name="Intro" width={1920} height={1080}>- <Image src={hero} />- <Text textAlign="center" textBaseline="middle" fontSize={128} fontWeight="bold">+ <scene key="intro" name="Intro" width={1920} height={1080}>+ <image src={hero} />+ <text textAlign="center" textBaseline="middle" fontSize={128} fontWeight="bold">Hello World- </Text>- <Captions />- </Scene>+ </text>+ <captions />+ </scene>);}```diff --git a/packages/jsx/src/elements.ts b/packages/jsx/src/elements.tsindex 7a6891f9..db6c8008 100644--- a/packages/jsx/src/elements.ts+++ b/packages/jsx/src/elements.ts@@ -3,12 +3,14 @@* file, You can obtain one at http://mozilla.org/MPL/2.0/. *//**- * The composition elements, as PascalCase components. A capitalized JSX tag- * compiles to a component reference, so hosts receive PascalCase tags for- * composition elements and lowercase tags only for DOM content under- * `<HtmlPaint>` — `createElement` can tell them apart by case alone. The- * compile step lists these names as babel `builtIns`, so project files use- * them without imports.+ * The composition elements, as PascalCase components: the canonical form the+ * CLI compile rewrites camelCase tags into (`<rect>` -> `Rect`, unless an SVG+ * container makes it SVG content). Hosts therefore receive PascalCase tags+ * for composition elements and lowercase tags only for DOM content under+ * `<htmlPaint>` — `createElement` can tell them apart by case alone. These+ * exports are the compile target and the ABI of persisted compiled bundles+ * (which import them by name via the host-module shim), not an authoring+ * surface.*/import { splitProps } from "solid-js";diff --git a/packages/jsx/src/jsx-runtime.ts b/packages/jsx/src/jsx-runtime.tsindex ba659101..62a9462f 100644--- a/packages/jsx/src/jsx-runtime.ts+++ b/packages/jsx/src/jsx-runtime.ts@@ -8,18 +8,45 @@* "./renderer", so this module carries no runtime — only the JSX namespace* TypeScript resolves element and prop types from.*- * Composition elements are the PascalCase components in "./elements";- * intrinsic (lowercase) tags are exclusively DOM vocabulary for `<HtmlPaint>`- * content, so the case of a tag decides its environment.+ * Composition elements are camelCase intrinsics (`<scene>`, `<rect>`, ...);+ * the compile step canonicalizes them to the PascalCase components in+ * "./elements", so at runtime a tag's case still decides its environment.+ * Lowercase DOM tags are the vocabulary for `<htmlPaint>` content. The three+ * names both vocabularies share (`rect`, `text`, `image`) are SVG-only on the+ * DOM side and resolve lexically at compile time: inside an SVG container+ * they are SVG content, everywhere else composition elements. Their prop+ * types are the union of both readings.*/import type { JSX as SolidJSX } from "solid-js";+import type {+ AudioProps,+ CaptionsProps,+ ColorStopProps,+ GradientPaintProps,+ GroupProps,+ HtmlPaintProps,+ HtmlProps,+ ImageProps,+ RectProps,+ SceneProps,+ SequenceProps,+ SolidPaintProps,+ SurfacePaintProps,+ SurfaceProps,+ TextProps,+ VideoProps,+} from "./types";// "canvas" is dropped: a DOM canvas's content doesn't survive// drawElementImage, so it is useless inside a paint host (draw with-// <Surface> instead). "audio" and "video" are dropped: media doesn't play-// under a paint host — use the <Audio>/<Video> composition elements.-type HtmlElementTags = Omit<SolidJSX.HTMLElementTags, "canvas" | "audio" | "video">;+// <surface> instead). "audio", "video", and "html" are dropped as DOM tags:+// media doesn't play under a paint host and a nested <html> is meaningless,+// so those names belong to the composition elements below.+type HtmlElementTags = Omit<SolidJSX.HTMLElementTags, "canvas" | "audio" | "video" | "html">;++// The shared names are re-declared below as unions with the composition props.+type SvgElementTags = Omit<SolidJSX.SVGElementTags, "rect" | "text" | "image">;export declare namespace JSX {// Solid's Element type keeps Solid's control flow (<For>, <Show>, …) and@@ -30,5 +57,23 @@ export declare namespace JSX {children: unknown;}- export interface IntrinsicElements extends HtmlElementTags, SolidJSX.SVGElementTags {}+ export interface IntrinsicElements extends HtmlElementTags, SvgElementTags {+ scene: SceneProps;+ group: GroupProps;+ rect: RectProps | SolidJSX.SVGElementTags["rect"];+ video: VideoProps;+ image: ImageProps | SolidJSX.SVGElementTags["image"];+ audio: AudioProps;+ text: TextProps | SolidJSX.SVGElementTags["text"];+ sequence: SequenceProps;+ captions: CaptionsProps;+ solidPaint: SolidPaintProps;+ linearGradientPaint: GradientPaintProps;+ radialGradientPaint: GradientPaintProps;+ colorStop: ColorStopProps;+ htmlPaint: HtmlPaintProps;+ html: HtmlProps;+ surfacePaint: SurfacePaintProps;+ surface: SurfaceProps;+ }}diff --git a/packages/jsx/src/renderer.ts b/packages/jsx/src/renderer.tsindex b4dbc20f..9ba4b9f6 100644--- a/packages/jsx/src/renderer.ts+++ b/packages/jsx/src/renderer.ts@@ -134,7 +134,7 @@ export function useTicker(): Ticker {* if (!el || !f) return;* el.getContext("2d")!.drawImage(await createImageBitmap(f), 0, 0);* });- * // <Surface ref={setCanvas} width={640} height={360} />+ * // <surface ref={setCanvas} width={640} height={360} />* ```*/export function useFile(src: AssetInput): ResourceReturn<File> {diff --git a/samples/reconciler/01-static-tree.tsx b/samples/reconciler/01-static-tree.tsxindex d0bab0a5..c0ec46ce 100644--- a/samples/reconciler/01-static-tree.tsx+++ b/samples/reconciler/01-static-tree.tsx@@ -11,25 +11,23 @@* Re-mounting replaces the scene in place (same key, same position).*/-import { ColorStop, Group, LinearGradientPaint, Rect, Scene, Text } from "@diffusionstudio/jsx";-export default () => (- <Scene key="sample-static" name="Static tree" width={960} height={540} fill="#101014">- <Group x={40} y={40}>- <Rect width={200} height={120} cornerRadius={16} fill="#ff4466" />- <Rect x={220} width={200} height={120} rotation={8} opacity={0.8}>- <LinearGradientPaint>- <ColorStop offset={0} color="#22ccff" />- <ColorStop offset={1} color="#7744ff" opacity={0.5} />- </LinearGradientPaint>- </Rect>- </Group>+ <scene key="sample-static" name="Static tree" width={960} height={540} fill="#101014">+ <group x={40} y={40}>+ <rect width={200} height={120} cornerRadius={16} fill="#ff4466" />+ <rect x={220} width={200} height={120} rotation={8} opacity={0.8}>+ <linearGradientPaint>+ <colorStop offset={0} color="#22ccff" />+ <colorStop offset={1} color="#7744ff" opacity={0.5} />+ </linearGradientPaint>+ </rect>+ </group>- <Text x={40} y={220} fontSize={48} fontFamily="Inter" fontWeight={700}>+ <text x={40} y={220} fontSize={48} fontFamily="Inter" fontWeight={700}>sum = {6 * 7}- </Text>+ </text>- <Rect+ <rectx={40}y={320}width={160}@@ -39,5 +37,5 @@ export default () => (end={3}animations={[{ type: "fade", phase: "in", duration: 0.5 }]}/>- </Scene>+ </scene>);diff --git a/samples/reconciler/02-live-signals.tsx b/samples/reconciler/02-live-signals.tsxindex 734283db..8a2b374f 100644--- a/samples/reconciler/02-live-signals.tsx+++ b/samples/reconciler/02-live-signals.tsx@@ -12,14 +12,13 @@*/import { Show, createSignal } from "solid-js";-import { Rect, Scene, Text } from "@diffusionstudio/jsx";const [n, setN] = createSignal(0);setInterval(() => setN(n() + 1), 400);export default () => (- <Scene key="sample-live" name="Live signals" width={960} height={540} fill="#101014">- <Rect+ <scene key="sample-live" name="Live signals" width={960} height={540} fill="#101014">+ <rectx={40 + (n() * 24) % 700}y={60}width={120}@@ -28,13 +27,13 @@ export default () => (fill={n() % 2 === 0 ? "#2288ff" : "#22ccff"}/>- <Text x={40} y={260} fontSize={64} fontFamily="Inter">+ <text x={40} y={260} fontSize={64} fontFamily="Inter">tick {n()}- </Text>+ </text><Show when={n() % 4 < 2}>- <Rect x={40} y={380} width={80} height={80} fill="#44dd88" />- <Text x={140} y={400} fontSize={36}>on air</Text>+ <rect x={40} y={380} width={80} height={80} fill="#44dd88" />+ <text x={140} y={400} fontSize={36}>on air</text></Show>- </Scene>+ </scene>);diff --git a/samples/reconciler/03-live-list.tsx b/samples/reconciler/03-live-list.tsxindex be84b4f2..6117379b 100644--- a/samples/reconciler/03-live-list.tsx+++ b/samples/reconciler/03-live-list.tsx@@ -10,7 +10,6 @@*/import { For, createSignal } from "solid-js";-import { Group, Rect, Scene, Text } from "@diffusionstudio/jsx";const COLORS: Record<string, string> = {A: "#ff4466",@@ -28,16 +27,16 @@ setInterval(() => {}, 4000);export default () => (- <Scene key="sample-list" name="Live list" width={960} height={540} fill="#101014">+ <scene key="sample-list" name="Live list" width={960} height={540} fill="#101014"><For each={items()}>{(label, i) => (- <Group x={40 + i() * 180} y={180}>- <Rect width={150} height={150} cornerRadius={16} fill={COLORS[label]} />- <Text x={55} y={45} fontSize={56} fontFamily="Inter" fontWeight={700}>+ <group x={40 + i() * 180} y={180}>+ <rect width={150} height={150} cornerRadius={16} fill={COLORS[label]} />+ <text x={55} y={45} fontSize={56} fontFamily="Inter" fontWeight={700}>{label}- </Text>- </Group>+ </text>+ </group>)}</For>- </Scene>+ </scene>);diff --git a/samples/reconciler/04-ticker.tsx b/samples/reconciler/04-ticker.tsxindex e82df504..0d09f044 100644--- a/samples/reconciler/04-ticker.tsx+++ b/samples/reconciler/04-ticker.tsx@@ -9,14 +9,14 @@*/import { Show } from "solid-js";-import { Rect, Scene, Text, useTicker } from "@diffusionstudio/jsx";+import { useTicker } from "@diffusionstudio/jsx";export default () => {const { time, frame, playing } = useTicker();return (- <Scene key="sample-ticker" name="Ticker" width={960} height={540} fill="#101014">- <Rect+ <scene key="sample-ticker" name="Ticker" width={960} height={540} fill="#101014">+ <rectx={420 + Math.round(Math.cos(time() * 2) * 300)}y={220 + Math.round(Math.sin(time() * 2) * 150)}width={100}@@ -25,13 +25,13 @@ export default () => {fill="#ffaa22"/>- <Text x={40} y={40} fontSize={40} fontFamily="Inter">+ <text x={40} y={40} fontSize={40} fontFamily="Inter">t = {time().toFixed(2)}s / frame {frame()}- </Text>+ </text><Show when={playing()}>- <Text x={40} y={460} fontSize={36} fontWeight={700}>PLAYING</Text>+ <text x={40} y={460} fontSize={36} fontWeight={700}>PLAYING</text></Show>- </Scene>+ </scene>);};diff --git a/samples/reconciler/05-html-paint.tsx b/samples/reconciler/05-html-paint.tsxindex ae8ed67d..d7c9b26f 100644--- a/samples/reconciler/05-html-paint.tsx+++ b/samples/reconciler/05-html-paint.tsx@@ -1,30 +1,30 @@/* @jsxImportSource @diffusionstudio/jsx */-/* Environment split: tag case decides the environment.+/* Environment split: the tag (and, for shared names, its SVG ancestry)+ * decides the environment.** dapi mount samples/reconciler/05-html-paint.tsx** Requires the html-in-canvas API (chrome://flags/#canvas-draw-element;* not available in Electron 35, so use a supporting build): without it the- * mount fails cleanly at <Html> materialization.+ * mount fails cleanly at <html> materialization.*- * The left <Rect> is an ECS entity. <Html> is a node too (a rect carrying an- * <HtmlPaint>), but its children are browser DOM: PascalCase tags are- * composition elements, lowercase tags are always DOM — the <rect> inside- * <svg> below is the SVG element, <div> is plain HTML, and the counter text- * updates reactively in the drawn DOM.+ * The left <rect> is an ECS entity. <html> is a node too (a rect carrying an+ * html paint), but its children are browser DOM. The names both vocabularies+ * share (rect/text/image) resolve lexically: the <rect> inside <svg> below is+ * the SVG element, <div> is plain HTML, and the counter text updates+ * reactively in the drawn DOM.*/import { createSignal } from "solid-js";-import { Html, Rect, Scene } from "@diffusionstudio/jsx";const [n, setN] = createSignal(0);setInterval(() => setN(n() + 1), 500);export default () => (- <Scene key="sample-html" name="HTML paint" width={960} height={540} fill="#101014">- <Rect x={40} y={120} width={200} height={300} cornerRadius={16} fill="#22ccff" />+ <scene key="sample-html" name="HTML paint" width={960} height={540} fill="#101014">+ <rect x={40} y={120} width={200} height={300} cornerRadius={16} fill="#22ccff" />- <Html x={280} y={60} width={640} height={420}>+ <html x={280} y={60} width={640} height={420}><div style={{ color: "white", "font-family": "Inter", "font-size": "28px", padding: "16px" }}>DOM counter: {n()}</div>@@ -33,6 +33,6 @@ export default () => (<circle cx={140 + (n() % 3) * 15} cy={35} r={20} fill="#44dd88" /><path d="M 10 80 H 190" stroke="#ffaa22" stroke-width={4} /></svg>- </Html>- </Scene>+ </html>+ </scene>);diff --git a/samples/reconciler/06-anime-timeline.tsx b/samples/reconciler/06-anime-timeline.tsxindex d4394945..275966de 100644--- a/samples/reconciler/06-anime-timeline.tsx+++ b/samples/reconciler/06-anime-timeline.tsx@@ -7,14 +7,14 @@* timeline tweens plain-object targets; a createEffect seeks it to the* scene playhead (looping over the timeline length) and mirrors the values* into a store. The same values drive an ECS chip on the canvas and a DOM- * card drawn via <Html>, so scrubbing or playing keeps both in lockstep,+ * card drawn via <html>, so scrubbing or playing keeps both in lockstep,* including the shared hue. Deterministic: same playhead, same picture.*/import { createEffect } from "solid-js";import { createStore } from "solid-js/store";import { createTimeline } from "animejs";-import { Html, Rect, Scene, useTicker } from "@diffusionstudio/jsx";+import { useTicker } from "@diffusionstudio/jsx";const chip = { x: -160, y: 190, rotation: -90, cornerRadius: 12, opacity: 0 };const card = { rise: 90, opacity: 0, progress: 0, hue: 210 };@@ -40,8 +40,8 @@ export default () => {const hue = () => Math.round(v.card.hue);return (- <Scene key="sample-anime" name="Anime timeline" width={960} height={540} fill="#101014">- <Rect+ <scene key="sample-anime" name="Anime timeline" width={960} height={540} fill="#101014">+ <rectx={v.chip.x}y={v.chip.y}width={160}@@ -52,7 +52,7 @@ export default () => {fill={`hsl(${hue()} 90% 60%)`}/>- <Html x={380} y={120} width={500} height={300}>+ <html x={380} y={120} width={500} height={300}><divstyle={{"font-family": "Inter",@@ -82,7 +82,7 @@ export default () => {{Math.round(v.card.progress)}% through the loop</div></div>- </Html>- </Scene>+ </html>+ </scene>);};diff --git a/samples/reconciler/07-anime-mini.tsx b/samples/reconciler/07-anime-mini.tsxindex 2788690a..a972a210 100644--- a/samples/reconciler/07-anime-mini.tsx+++ b/samples/reconciler/07-anime-mini.tsx@@ -4,7 +4,7 @@*/import { createEffect, createSignal } from "solid-js";import { createTimeline } from "animejs";-import { Html, Rect, Scene, useTicker } from "@diffusionstudio/jsx";+import { useTicker } from "@diffusionstudio/jsx";const box = { x: 60, spin: 0, pct: 0 };@@ -22,14 +22,14 @@ export default function HtmlInCanvasDemo() {});return (- <Scene key="sample-anime-mini" name="Anime mini" width={960} height={540} fill="#101014">- <Rect x={v().x} y={280} width={140} height={140} rotation={v().spin} cornerRadius={28} fill="#22ccff" />+ <scene key="sample-anime-mini" name="Anime mini" width={960} height={540} fill="#101014">+ <rect x={v().x} y={280} width={140} height={140} rotation={v().spin} cornerRadius={28} fill="#22ccff" />- <Html x={60} y={90} width={840} height={120} name="Live HTML">+ <html x={60} y={90} width={840} height={120} name="Live HTML"><div style="color: white; font-family: Inter; font-size: 60px; font-weight: 700">Timeline at <span style="color: #22ccff">{Math.round(v().pct)}%</span></div>- </Html>- </Scene>+ </html>+ </scene>);};diff --git a/samples/reconciler/08-surface-paint.tsx b/samples/reconciler/08-surface-paint.tsxindex b4a5dfd6..2dbbb0d8 100644--- a/samples/reconciler/08-surface-paint.tsx+++ b/samples/reconciler/08-surface-paint.tsx@@ -1,5 +1,5 @@/* @jsxImportSource @diffusionstudio/jsx */-/* Ref-provided canvas: the <Surface> element hands its backing bitmap to the+/* Ref-provided canvas: the <surface> element hands its backing bitmap to the* ref callback, which owns it from then on.** dapi mount samples/reconciler/08-surface-paint.tsx@@ -7,11 +7,11 @@* The ref runs once at materialization, inside the mount's reactive owner:* the effect below redraws from a signal and the playhead ticker, and the* engine samples the bitmap into the node's box every frame. The standalone- * <SurfacePaint> on the right stacks over a solid fill inside a plain <Rect>.+ * <surfacePaint> on the right stacks over a solid fill inside a plain <rect>.*/import { createEffect, createSignal } from "solid-js";-import { Scene, Surface, useTicker } from "@diffusionstudio/jsx";+import { useTicker } from "@diffusionstudio/jsx";export default () => {const { time } = useTicker();@@ -37,8 +37,8 @@ export default () => {});return (- <Scene key="sample-surface" name="Surface paint" width={960} height={540} fill="#101014">- <Surface+ <scene key="sample-surface" name="Surface paint" width={960} height={540} fill="#101014">+ <surfacex={40}y={60}width={520}@@ -46,6 +46,6 @@ export default () => {cornerRadius={16}ref={setCanvas}/>- </Scene>+ </scene>);};diff --git a/samples/reconciler/09-three-helmet.tsx b/samples/reconciler/09-three-helmet.tsxindex bfa155e8..3d1c28e7 100644--- a/samples/reconciler/09-three-helmet.tsx+++ b/samples/reconciler/09-three-helmet.tsx@@ -1,9 +1,9 @@/* @jsxImportSource @diffusionstudio/jsx */-/* Three.js owning a <Surface>: a glTF helmet spun by the playhead.+/* Three.js owning a <surface>: a glTF helmet spun by the playhead.** dapi mount samples/reconciler/09-three-helmet.tsx*- * The <Surface> ref hands three.js a detached HTMLCanvasElement to render into;+ * The <surface> ref hands three.js a detached HTMLCanvasElement to render into;* the engine samples that bitmap into the node's box every frame, so a WebGL* scene composites like any other paint (needs preserveDrawingBuffer so the* per-frame readback doesn't come back blank). One clock drives everything:@@ -17,7 +17,7 @@*/import { createEffect, createSignal, onCleanup } from "solid-js";-import { Scene, Surface, useTicker } from "@diffusionstudio/jsx";+import { useTicker } from "@diffusionstudio/jsx";import * as THREE from "three";import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";import { RoomEnvironment } from "three/examples/jsm/environments/RoomEnvironment.js";@@ -96,8 +96,8 @@ export default () => {};return (- <Scene key="sample-three" name="Three helmet" width={960} height={540} fill="#0b0d12">- <Surface x={0} y={0} width={960} height={540} ref={setup} />- </Scene>+ <scene key="sample-three" name="Three helmet" width={960} height={540} fill="#0b0d12">+ <surface x={0} y={0} width={960} height={540} ref={setup} />+ </scene>);};diff --git a/samples/reconciler/README.md b/samples/reconciler/README.mdindex 4fbd03f6..d21bd8e4 100644--- a/samples/reconciler/README.md+++ b/samples/reconciler/README.md@@ -9,11 +9,11 @@ Run from the repo root with the editor open:| [02-live-signals.tsx](02-live-signals.tsx) | `dapi mount samples/reconciler/02-live-signals.tsx` | reactive props, replaceText, Show insert/remove || [03-live-list.tsx](03-live-list.tsx) | `dapi mount samples/reconciler/03-live-list.tsx` | \<For\> moves (reorder without recreate), list insert/remove || [04-ticker.tsx](04-ticker.tsx) | `dapi mount samples/reconciler/04-ticker.tsx` | useTicker playhead reactivity (press play) |-| [05-html-paint.tsx](05-html-paint.tsx) | `dapi mount samples/reconciler/05-html-paint.tsx` | DOM/SVG materialization under \<Html\>; needs html-in-canvas |-| [06-anime-timeline.tsx](06-anime-timeline.tsx) | `dapi mount samples/reconciler/06-anime-timeline.tsx` | anime.js timeline seeked from useTicker, driving an ECS node and \<Html\> content in lockstep |+| [05-html-paint.tsx](05-html-paint.tsx) | `dapi mount samples/reconciler/05-html-paint.tsx` | DOM/SVG materialization under \<html\>; needs html-in-canvas |+| [06-anime-timeline.tsx](06-anime-timeline.tsx) | `dapi mount samples/reconciler/06-anime-timeline.tsx` | anime.js timeline seeked from useTicker, driving an ECS node and \<html\> content in lockstep || [07-anime-mini.tsx](07-anime-mini.tsx) | `dapi mount samples/reconciler/07-anime-mini.tsx` | minimal anime.js + useTicker sync, sized for a social post |-| [08-surface-paint.tsx](08-surface-paint.tsx) | `dapi mount samples/reconciler/08-surface-paint.tsx` | ref-provided canvas: \<Surface\> element and \<SurfacePaint\> child, effect-driven redraws |-| [09-three-helmet.tsx](09-three-helmet.tsx) | `dapi mount samples/reconciler/09-three-helmet.tsx` | three.js WebGL renderer owning a \<Surface\>, glTF model loaded over the network, rotation seeked from useTicker |+| [08-surface-paint.tsx](08-surface-paint.tsx) | `dapi mount samples/reconciler/08-surface-paint.tsx` | ref-provided canvas: \<surface\> element and \<surfacePaint\> child, effect-driven redraws |+| [09-three-helmet.tsx](09-three-helmet.tsx) | `dapi mount samples/reconciler/09-three-helmet.tsx` | three.js WebGL renderer owning a \<surface\>, glTF model loaded over the network, rotation seeked from useTicker |Each root scene carries a stable key, so re-mounting a sample replaces itsscene in place. Inspect results with `dapi node tree`; entity ids in sample 03