Skip to content

The VS Code of video editing, built for agents.

TypeScript

Update JSX documentation to clarify group behavior and paint usage

konstantin-paulus7ace383dbe25
diff --git a/apps/cli/reference/README.md b/apps/cli/reference/README.md
index eb57f845..a9bec575 100644
--- a/apps/cli/reference/README.md
+++ b/apps/cli/reference/README.md
@@ -2,7 +2,7 @@
Reference for `dapi`, the Diffusion Studio CLI. Every canvas and project command talks to the running app over a local socket. Responses are JSON written to stdout; errors are human-readable messages on stderr with a non-zero exit.
-Each feature command has its own file (linked below). The JSX code syntax consumed by [`mount`](./mount.md) and [`node insert`](./node/insert.md) is specified in [jsx/](./jsx/README.md).
+Each feature command has its own file (linked below). The JSX code syntax consumed by [`mount`](./mount.md) and [`node insert`](./node/insert.md) is specified in [jsx/](./jsx/README.md); the markup is **pseudo-SVG**, mirroring SVG's shape-and-paint model with the editor's own tags and props rather than the SVG spec.
## Groups
diff --git a/apps/cli/reference/jsx/README.md b/apps/cli/reference/jsx/README.md
index 358c51d2..efa27864 100644
--- a/apps/cli/reference/jsx/README.md
+++ b/apps/cli/reference/jsx/README.md
@@ -4,6 +4,8 @@ The JSX API defines the code contract for injecting content into the editor via
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 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.
## Contents
@@ -64,7 +66,7 @@ function Title(props: { text: string; start: Time; end: Time }) {
<text
textAlign="center"
textBaseline="middle"
- color="#FFFFFF"
+ fill="#FFFFFF"
fontSize={128}
fontWeight="bold"
height={1080}
diff --git a/apps/cli/reference/jsx/elements.md b/apps/cli/reference/jsx/elements.md
index e56a64b1..6cb0b874 100644
--- a/apps/cli/reference/jsx/elements.md
+++ b/apps/cli/reference/jsx/elements.md
@@ -5,7 +5,7 @@ Lowercase intrinsic elements map 1:1 onto internal node types:
| 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; give it `fill` to draw a rectangle. |
+| [`<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. |
diff --git a/apps/cli/reference/jsx/group.md b/apps/cli/reference/jsx/group.md
index e330b432..cf80c4cb 100644
--- a/apps/cli/reference/jsx/group.md
+++ b/apps/cli/reference/jsx/group.md
@@ -1,19 +1,13 @@
# `<group>`
-A container with a transform. Children are positioned relative to the group's box; give it `fill` to draw a rectangle behind them.
+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} width={800} height={600} fill="#111111">
+<group x={100} y={100}>
{/* children */}
</group>
```
## Props
-All [common props](./elements.md#common-props), plus:
-
-| Prop | Type | Default | Meaning |
-| ---- | ---- | ------- | ------- |
-| `fill` | `string` | none | Any CSS color, applied to the node's fill; alpha is ignored (use `opacity`). |
-
-Also accepts [paint children](./paints.md). When timing is omitted, a group auto-fits its children (see [timing.md](./timing.md)).
+A group takes only **transform** (`x`, `y`, `rotation`, `opacity`) and **timing** (`start`, `end`) props (see [common props](./elements.md#common-props) and [timing.md](./timing.md)). It has no `fill` and no explicit `width` / `height`, and takes no [paint children](./paints.md): its size is auto-fit from its children. When timing is omitted, a group spans its children in time as well (see [timing.md](./timing.md)).
diff --git a/apps/cli/reference/jsx/paints.md b/apps/cli/reference/jsx/paints.md
index 00a35c19..5b7fd825 100644
--- a/apps/cli/reference/jsx/paints.md
+++ b/apps/cli/reference/jsx/paints.md
@@ -11,7 +11,7 @@ Internally a node's fill is not a property but a **paint child**: a sub-entity a
</rect>
```
-Paint elements are valid inside any visual element (`<rect>`, `<group>`, `<scene>`, `<text>`, `<video>`, `<image>`). 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 |
| ------- | ----- | ------- |
diff --git a/apps/cli/reference/jsx/text.md b/apps/cli/reference/jsx/text.md
index 149aeaa0..158e0ad8 100644
--- a/apps/cli/reference/jsx/text.md
+++ b/apps/cli/reference/jsx/text.md
@@ -3,7 +3,7 @@
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 color="#FFFFFF" fontSize={128} fontWeight="bold" textAlign="center" textBaseline="middle">
+<text fill="#FFFFFF" fontSize={128} fontWeight="bold" textAlign="center" textBaseline="middle">
Hello World
</text>
```
@@ -19,6 +19,6 @@ All [common props](./elements.md#common-props), plus:
| `fontSize` | `number` | editor default | Px. |
| `fontWeight` | `number \| "normal" \| "bold"` | `"normal"` | CSS weights `100`-`900`. |
| `fontStyle` | `"normal" \| "italic"` | `"normal"` | |
-| `color` | `Animatable<string>` | editor default | The glyph color, any CSS color. |
+| `fill` | `string` | white | The glyph color; any CSS color, alpha ignored (use `opacity`). Shorthand for a solid paint child (see [paints.md](./paints.md)); animate it by declaring the paint explicitly. |
| `textAlign` | `"left" \| "center" \| "right"` | `"left"` | Horizontal alignment of glyphs within the box. |
| `textBaseline` | `"top" \| "middle" \| "bottom"` | `"top"` | Vertical alignment within the box. |