The VS Code of video editing, built for agents.
TypeScript
Refactor timing properties in JSX elements for improved clarity and consistency
konstantin-paulusefb17d896c66
diff --git a/README.md b/README.mdindex f3738cc2..3fa9f518 100644--- a/README.md+++ b/README.md@@ -22,8 +22,8 @@ const hero = generate.image({ prompt: "A neon city at night, cinematic" });const motion = generate.video({ prompt: "slow camera push-in", startFrame: hero });const TITLES = [- { text: "The Grid", inPoint: 0, outPoint: 2.5 },- { text: "Neon Nights", inPoint: 2.5, outPoint: 5 },+ { text: "The Grid", start: 0, end: 2.5 },+ { text: "Neon Nights", start: 2.5, end: 5 },];export default function Project() {@@ -40,8 +40,8 @@ export default function Project() {width={1920}height={1080}fill="white"- inPoint={t.inPoint}- outPoint={t.outPoint}+ start={t.start}+ end={t.end}>{t.text}</text>diff --git a/apps/cli/reference/jsx/README.md b/apps/cli/reference/jsx/README.mdindex 162aec2c..358c51d2 100644--- a/apps/cli/reference/jsx/README.md+++ b/apps/cli/reference/jsx/README.md@@ -16,7 +16,7 @@ The pipeline is driven by two commands: [`dapi mount`](../mount.md) renders the| [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>` || [media.md](./media.md) | `src` resolution (paths, URLs, asset ids, `AssetRef`) |-| [timing.md](./timing.md) | `inPoint` / `outPoint` / `startTime`, time formats |+| [timing.md](./timing.md) | `start` / `end` / `sourceIn` / `sourceOut`, time formats || [keyframes.md](./keyframes.md) | Keyframe animation and easing || [transitions.md](./transitions.md) | The `transition` prop on sequence clips || [sequences.md](./sequences.md) | `<sequence>` sequential placement |@@ -34,7 +34,7 @@ The pipeline is driven by two commands: [`dapi mount`](../mount.md) renders the4. **Mount**: the component tree is rendered into a **staging root**. The universal renderer materializes each element as an ECS entity with the appropriate components (see [elements.md](./elements.md)). Mounting is synchronous; an error here aborts the import with nothing inserted.5. **Commit**: the rendered roots are reconciled against the document (see [roots.md](./roots.md)) as a **single undoable operation** that also covers the generated assets below.6. **Generate**: declared assets generate in dependency order, **blocking the command** until every one has landed. Each placeholder renders a generating state until its asset lands, then the node's paint is attached (see [generate.md](./generate.md)).-7. **Sync**: nodes declaring `syncTo` are aligned once every generated asset has landed: each node's audio is cross-correlated against its target's and its `startTime` is written from the measured offset (see [audio-sync.md](./audio-sync.md)). Local and blocking; captions wait for it.+7. **Sync**: nodes declaring `syncTo` are aligned once every generated asset has landed: each node's audio is cross-correlated against its target's and its `start` is written from the measured offset (see [audio-sync.md](./audio-sync.md)). Local and blocking; captions wait for it.## Full example@@ -55,11 +55,11 @@ const heroMotion = generate.video({});const TITLES = [- { text: "Hello World", inPoint: 3, outPoint: 6 },- { text: "Chapter One", inPoint: 6, outPoint: 9 },+ { text: "Hello World", start: 3, end: 6 },+ { text: "Chapter One", start: 6, end: 9 },];-function Title(props: { text: string; inPoint: Time; outPoint: Time }) {+function Title(props: { text: string; start: Time; end: Time }) {return (<texttextAlign="center"@@ -69,8 +69,8 @@ function Title(props: { text: string; inPoint: Time; outPoint: Time }) {fontWeight="bold"height={1080}width={1920}- inPoint={props.inPoint}- outPoint={props.outPoint}+ start={props.start}+ end={props.end}>{props.text}</text>@@ -81,8 +81,8 @@ export default function Project() {return (<scene key="my-first-scene" name="MyFirstScene" fill="black" width={1920} height={1080}><sequence>- <video src={heroMotion} inPoint={0} outPoint={5} transition={{ type: "dissolve" }} />- <video src="/Movies/video.mp4" inPoint={5} outPoint={16} startTime="-30f" />+ <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} />@@ -91,8 +91,8 @@ export default function Project() {<audiosrc="https://my.videoarchive.com/audio/video-xyz.wav"- inPoint={2.2}- outPoint={16}+ sourceIn={6}+ sourceOut={16}volume={0.5}/>diff --git a/apps/cli/reference/jsx/audio-sync.md b/apps/cli/reference/jsx/audio-sync.mdindex 082b94d2..b5b3a2ef 100644--- a/apps/cli/reference/jsx/audio-sync.md+++ b/apps/cli/reference/jsx/audio-sync.md@@ -1,10 +1,10 @@# Audio sync-`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 `startTime` 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.+`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" inPoint={0} outPoint={45} muted />+ <video key="camera" src="/Movies/take-3.mp4" sourceOut={45} muted /><audio src="/Movies/lav.wav" syncTo="camera" /></scene>```@@ -12,10 +12,10 @@## Semantics- `syncTo` names the `key` of another element in the same render. Both sides must carry an audio track; any pairing works (audio-to-video, audio-to-audio, video-to-video).-- The computed placement is `startTime = target.startTime + offset`, where `offset` is the measured source-time offset between the two recordings (positive when this node's recording started after the target's; possibly negative). `syncTo` and `startTime` are mutually exclusive.-- `inPoint`/`outPoint` keep their normal meaning and remain yours to set. When omitted on a synced node, the window defaults to the intersection of the node's natural extent with the target's window (instead of the usual natural-duration fit), so a lav track simply covers its take.+- The computed placement is `start = target.start + offset`, where `offset` is the measured source-time offset between the two recordings (positive when this node's recording started after the target's; possibly negative). `syncTo` and `start` are mutually exclusive.+- `sourceIn`/`sourceOut` keep their normal meaning and remain yours to set. When omitted on a synced node, the window defaults to the intersection of the node's natural extent with the target's window (instead of the usual natural-duration fit), so a lav track simply covers its take.- Alignment reads source content: `muted` and `volume` on either side do not affect the measurement. Use `muted` to keep only one side audible, as on the camera track above.-- Chains resolve in dependency order (A may sync to B while B syncs to C). Unknown keys, cycles, and combining `syncTo` with `startTime` are mount errors; nothing is inserted.+- Chains resolve in dependency order (A may sync to B while B syncs to C). Unknown keys, cycles, and combining `syncTo` with `start` are mount errors; nothing is inserted.## Executiondiff --git a/apps/cli/reference/jsx/audio.md b/apps/cli/reference/jsx/audio.mdindex 94c38193..cffd686b 100644--- a/apps/cli/reference/jsx/audio.md+++ b/apps/cli/reference/jsx/audio.md@@ -1,9 +1,9 @@# `<audio>`-An audio clip: no visual output, no spatial props; carries volume. When `inPoint`/`outPoint` are omitted, the node fits its natural duration (see [timing.md](./timing.md)).+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" inPoint={2.2} outPoint={16} volume={0.5} />+<audio src="https://my.videoarchive.com/audio/clip.wav" start={2.2} sourceOut={16} volume={0.5} />```## Props@@ -12,7 +12,7 @@ An audio clip: no visual output, no spatial props; carries volume. When `inPoint| ---- | ---- | ------- | ------- || `src` | `string \| AssetRef` | **required** | See [media.md](./media.md). || `name` | `string` | none | Human-readable node name. |-| `inPoint`, `outPoint`, `startTime` | `Time` | see [timing.md](./timing.md) | Temporal placement. |+| `start`, `end`, `sourceIn`, `sourceOut` | `Time` | see [timing.md](./timing.md) | Temporal placement. || `volume` | `Animatable<number>` | `1` | `0`-`1`; `1` = unity gain. || `muted` | `boolean` | `false` | Excludes the node's audio from the mix; independent of `volume`. |-| `syncTo` | `string` | none | Key of another element carrying audio; derives `startTime` by audio alignment (see [audio-sync.md](./audio-sync.md)). Mutually exclusive with `startTime`. |+| `syncTo` | `string` | none | Key of another element carrying audio; derives `start` by audio alignment (see [audio-sync.md](./audio-sync.md)). Mutually exclusive with `start`. |diff --git a/apps/cli/reference/jsx/elements.md b/apps/cli/reference/jsx/elements.mdindex a2f45ada..e56a64b1 100644--- a/apps/cli/reference/jsx/elements.md+++ b/apps/cli/reference/jsx/elements.md@@ -11,7 +11,7 @@ Lowercase intrinsic elements map 1:1 onto internal node types:| [`<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** | Lays children out back-to-back. |+| [`<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. |@@ -38,7 +38,7 @@ All visual elements accept:| `rotation` | `Animatable<number>` | `0` | Rotation in degrees. || `opacity` | `Animatable<number>` | `1` | `0`-`1`. || `cornerRadius` | `Animatable<number>` | `0` | Uniform corner radius, px. |-| `inPoint`, `outPoint`, `startTime` | `Time` | see [timing.md](./timing.md) | Temporal placement. |+| `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)). |`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 1c1b62d7..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 `startTime`) | 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 320c9169..febe3c00 100644--- a/apps/cli/reference/jsx/generate.md+++ b/apps/cli/reference/jsx/generate.md@@ -23,7 +23,7 @@ const heroMotion = generate.video({export default function Project() {return (<scene key="intro" name="Intro" width={1920} height={1080}>- <video src={heroMotion} inPoint={0} outPoint={5} />+ <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 37c08738..e330b432 100644--- a/apps/cli/reference/jsx/group.md+++ b/apps/cli/reference/jsx/group.md@@ -16,4 +16,4 @@ All [common props](./elements.md#common-props), plus:| ---- | ---- | ------- | ------- || `fill` | `string` | none | Any CSS color, applied to the node's fill; alpha is ignored (use `opacity`). |-Also accepts [paint children](./paints.md). When `inPoint`/`outPoint` are omitted, a group auto-fits its children (see [timing.md](./timing.md)).+Also accepts [paint children](./paints.md). When timing is omitted, a group auto-fits its children (see [timing.md](./timing.md)).diff --git a/apps/cli/reference/jsx/keyframes.md b/apps/cli/reference/jsx/keyframes.mdindex f8080eee..d6852394 100644--- a/apps/cli/reference/jsx/keyframes.md+++ b/apps/cli/reference/jsx/keyframes.md@@ -5,7 +5,7 @@ Animatable props accept a keyframe list in place of a static value:```tsx<imagesrc="/photo.jpg"- inPoint={0} outPoint={5}+ start={0} end={5}x={[{ time: 0, value: -400 },{ time: 1, value: 200, easing: "easeOut" },@@ -23,7 +23,7 @@ Animatable props: `x`, `y`, `width`, `height`, `rotation`, `opacity`, `cornerRad## Semantics-- `time` is **node-local**: `0` is the node's in point, in any [time format](./timing.md#time-formats). Timing props are composition-relative; keyframe times are not, so animation moves with the clip.+- `time` is **node-local**: `0` is where the clip begins (its `start`), in any [time format](./timing.md#time-formats). Timing props are parent-relative; keyframe times are not, so animation moves with the clip.- Outside the keyframed range the value holds at the first/last keyframe.- `easing` shapes the segment from its keyframe to the next; the last keyframe's easing is ignored. Default `"linear"`.- A **static value replaces any existing keyframes** on that property; mount and `dapi node patch` own what they set. Keyframes land as regular editor keyframes, editable in the timeline and inspector, and props the render doesn't set keep their hand-made tracks across re-mounts.diff --git a/apps/cli/reference/jsx/sequences.md b/apps/cli/reference/jsx/sequences.mdindex c4a0f607..1ef441da 100644--- a/apps/cli/reference/jsx/sequences.md+++ b/apps/cli/reference/jsx/sequences.md@@ -1,15 +1,17 @@# Sequences-`<sequence>` enforces **sequential, non-overlapping** placement of its children: the editor's track-like behavior. It has no spatial or temporal properties of its own; it lays its children out back-to-back in document order.+`<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" inPoint={0} outPoint={12} />- <video src="/Movies/main.mp4" inPoint={12} outPoint="02:30" />- <video src="/Movies/outro.mp4" inPoint="02:30" outPoint="02:45" />+ <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.+## Props| Prop | Type | Meaning |diff --git a/apps/cli/reference/jsx/timing.md b/apps/cli/reference/jsx/timing.mdindex 141f5501..de47d2d7 100644--- a/apps/cli/reference/jsx/timing.md+++ b/apps/cli/reference/jsx/timing.md@@ -1,20 +1,27 @@# Timing-Timing props follow Lottie-inspired semantics. All values are **composition-relative** (measured against the parent's timeline), in any supported [time format](#time-formats).+Timing splits the two independent questions a clip answers: **where it sits on the parent timeline** (`start` / `end`) and **which part of its source plays** (`sourceIn` / `sourceOut`). All values accept any [time format](#time-formats).-| Prop | Lottie | Meaning |-| ---- | ------ | ------- |-| `inPoint` | `ip` | Composition time at which the node becomes visible/audible. |-| `outPoint` | `op` | Composition time at which the node stops. |-| `startTime` | `st` | Composition time at which the node's *source* time 0 is placed. Shifts the source content within the in/out window. Defaults to the in point. |+| Prop | Meaning |+| ---- | ------- |+| `start` | Parent-timeline time at which the clip begins. Default 0. |+| `end` | Parent-timeline time at which the clip ends. Alternative to `sourceOut`. |+| `sourceIn` | Source in point: the time within the source where playback begins. Default 0; trims the head. |+| `sourceOut` | Source out point: the time within the source where playback ends. Defaults to the source's natural end. Alternative to `end`. |## Semantics-- `inPoint` / `outPoint` define the **visible/audible window** on the parent timeline. They are a pair; if omitted, a media node fits its natural duration and a group auto-fits its children.-- `startTime` controls **which part of the source plays inside that window**. It is the composition time where source frame 0 sits, so it may be negative to skip into the source.-- Instead of declaring `startTime`, a media node can derive it from another node's audio with `syncTo` (see [audio-sync.md](./audio-sync.md)).--> Example: `inPoint={0} outPoint={16} startTime="-30f"` shows the clip from composition second 0 to 16, but because source-time-0 is placed 30 frames *before* the in point, the first 30 frames (1s @ 30fps) of the source are trimmed; playback begins 1s into the source.+- `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.+- 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).++> 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.## Time formatsdiff --git a/apps/cli/reference/jsx/transitions.md b/apps/cli/reference/jsx/transitions.mdindex 50b36262..1017929e 100644--- a/apps/cli/reference/jsx/transitions.md+++ b/apps/cli/reference/jsx/transitions.md@@ -4,9 +4,9 @@```tsx<sequence>- <video src="/Movies/intro.mp4" inPoint={0} outPoint={12} transition={{ type: "fadeToBlack", duration: "20f" }} />- <video src="/Movies/main.mp4" inPoint={12} outPoint={24} transition={{}} /> {/* dissolve, 1s */}- <video src="/Movies/outro.mp4" inPoint={24} outPoint={30} />+ <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>```diff --git a/apps/cli/reference/jsx/video.md b/apps/cli/reference/jsx/video.mdindex 17b4ecef..65da57e9 100644--- a/apps/cli/reference/jsx/video.md+++ b/apps/cli/reference/jsx/video.md@@ -1,9 +1,9 @@# `<video>`-A video clip. `src` resolves to a video asset (see [media.md](./media.md)); when `inPoint`/`outPoint` are omitted, the node fits its natural duration (see [timing.md](./timing.md)).+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" inPoint={0} outPoint={12} startTime="-30f" volume={0.8} />+<video src="/Movies/main.mp4" start={0} sourceIn={1} sourceOut={13} volume={0.8} />```## Props@@ -16,6 +16,6 @@ All [common props](./elements.md#common-props), plus:| `objectFit` | `"cover" \| "contain" \| "fill"` | `"cover"` | How the source maps into the box. || `volume` | `Animatable<number>` | `1` | `0`-`1`; `1` = unity gain. || `muted` | `boolean` | `false` | Excludes the node's audio from the mix; independent of `volume`. |-| `syncTo` | `string` | none | Key of another element carrying audio; derives `startTime` by audio alignment (see [audio-sync.md](./audio-sync.md)). Mutually exclusive with `startTime`. |+| `syncTo` | `string` | none | Key of another element carrying audio; derives `start` by audio alignment (see [audio-sync.md](./audio-sync.md)). Mutually exclusive with `start`. |A paint child draws over the media paint created by `src` (see [paints.md](./paints.md)).diff --git a/apps/cli/reference/node/patch.md b/apps/cli/reference/node/patch.mdindex 1c2494c4..e121db8f 100644--- a/apps/cli/reference/node/patch.md+++ b/apps/cli/reference/node/patch.md@@ -21,7 +21,7 @@ All props are optional; a patch may set any subset. An unsupported property or a- `fill` recolors the entity's existing solid fill(s), or creates one if the entity has none.- `src` takes a path, URL, or asset id (`generate.*` declarations are JSX-only). The source resolves asynchronously after the other props land; if resolution fails, the entity is reported rejected even though its other props were applied. Patch `src` on its own to avoid ambiguity.-- `syncTo` re-runs audio alignment against the document node carrying the given key and writes the entity's `startTime` from the measured offset (see [jsx/audio-sync.md](../jsx/audio-sync.md)). The command blocks until alignment settles; a failed alignment rejects the entity.+- `syncTo` re-runs audio alignment against the document node carrying the given key and writes the entity's `start` from the measured offset (see [jsx/audio-sync.md](../jsx/audio-sync.md)). The command blocks until alignment settles; a failed alignment rejects the entity.- `transition` sets, merges into, or (with `null`) removes the clip's transition into the next clip (see [jsx/transitions.md](../jsx/transitions.md)).- Keyframe lists are accepted wherever the property is animatable, with the same semantics as mount (see [jsx/keyframes.md](../jsx/keyframes.md)); a static value replaces any existing keyframes.- Element applicability is not checked: props are applied wherever `mount` would apply them (e.g. `fontSize` only makes sense on a text node).diff --git a/apps/web/src/utils/jsx.ts b/apps/web/src/utils/jsx.tsindex ac9d9ad3..4b780d97 100644--- a/apps/web/src/utils/jsx.ts+++ b/apps/web/src/utils/jsx.ts@@ -46,9 +46,10 @@ import type { GenerationMemo } from "@/utils/jsx-generation";type DocumentNode = {kind: "element";eid: number;- inPoint?: number;- outPoint?: number;- startTime?: number;+ start?: number;+ end?: number;+ sourceIn?: number;+ sourceOut?: number;objectFit?: keyof typeof SCALE_MODE_MAP;parent?: DocumentNode;children?: DocumentNode[];@@ -264,17 +265,24 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {const parentDelay = parentEid !== null ? (c.Computed.delay[parentEid] ?? 0) : 0;const delay = (c.Computed.delay[targetEid] ?? 0) + offsetFrames - parentDelay;- node.startTime = delay;setComponent(world, node.eid, c.Delay, delay);const targetStart = (c.Computed.start[targetEid] ?? 0) - parentDelay;const targetEnd = (c.Computed.end[targetEid] ?? 0) - parentDelay;const duration = findAssetDuration(world, node.eid);- const start = node.inPoint ?? Math.max(delay, targetStart);- const end = node.outPoint ?? Math.min(duration !== null ? delay + duration : targetEnd, targetEnd);- assert(end > start, `syncTo: the aligned clip does not overlap the window of "${targetKey}"`);- setComponent(world, node.eid, c.Trim, { start: start - delay, end: end - delay });+ // `sourceIn`/`sourceOut` are source-relative; default to the overlap+ // with the target window. `end` (timeline) converts through `delay`.+ const trimStart = node.sourceIn ?? Math.max(0, targetStart - delay);+ const trimEnd = node.sourceOut+ ?? (node.end !== undefined+ ? node.end - delay+ : (duration !== null ? Math.min(duration, targetEnd - delay) : targetEnd - delay));+ assert(trimEnd > trimStart, `syncTo: the aligned clip does not overlap the window of "${targetKey}"`);+ setComponent(world, node.eid, c.Trim, { start: trimStart, end: trimEnd });+ node.sourceIn = trimStart;+ node.sourceOut = trimEnd;+ node.start = delay + trimStart;}}@@ -401,23 +409,52 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {* Wraps an existing entity so props can be applied to it through the same* `setProperty` path a fresh render uses (e.g. `dapi node patch`). Timing* state is hydrated from the entity's components so a partial patch (say,- * only `inPoint`) composes with its existing delay/trim like a full render.+ * only `sourceIn`) composes with its existing delay/trim like a full render.*/public element(eid: number): DocumentNode {const world = this.world;const c = world.components;const node: DocumentNode = { kind: "element", eid };- if (hasComponent(world, eid, c.Delay)) node.startTime = c.Delay[eid];+ const delay = hasComponent(world, eid, c.Delay) ? c.Delay[eid] : 0;if (hasComponent(world, eid, c.Trim)) {- const delay = node.startTime ?? 0;const start = c.Trim.start[eid];const end = c.Trim.end[eid];- if (start !== undefined) node.inPoint = start + delay;- if (end !== undefined) node.outPoint = end + delay;+ if (start !== undefined) {+ node.sourceIn = start;+ }+ if (end !== undefined) {+ node.sourceOut = end;+ }+ }+ // start = timeline placement of source-0 (Delay) shifted by the source in point.+ if (hasComponent(world, eid, c.Delay) || node.sourceIn !== undefined) {+ node.start = delay + (node.sourceIn ?? 0);}return node;}+ private reconcileTiming(node: DocumentNode) {+ if (node.kind !== "element") return;+ const world = this.world;+ const c = world.components;+ const eid = node.eid;+ const sourceIn = node.sourceIn ?? 0;+ const start = node.start ?? 0;+ const delay = start - sourceIn;+ setComponent(world, eid, c.Delay, delay);++ if (node.sourceIn !== undefined) {+ setComponent(world, eid, c.Trim, { start: node.sourceIn });+ }+ if (node.sourceOut !== undefined) {+ setComponent(world, eid, c.Trim, { end: node.sourceOut });+ } else if (node.end !== undefined) {+ const trimEnd = node.end - delay;+ assert(trimEnd > sourceIn, `\`end\` must be after \`start\`, got start=${start}, end=${node.end}`);+ setComponent(world, eid, c.Trim, { end: trimEnd });+ }+ }+public replaceText(node: DocumentNode, text: string) {assert(node.kind === "text", "replaceText target is not a text node");node.text = text;@@ -551,32 +588,32 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {assert(value >= 0, "`cornerRadius` must be >= 0");setComponent(world, eid, c.CornerRadius, Math.round(value));break;- } case "inPoint": {+ } case "start": {const parsed = parseFrames(String(value), 30);- assert(typeof parsed === "number", "`inPoint` must be a string or number" + `, value: ${value}`);- node.inPoint = parsed;- const delay = node.startTime ?? 0;- setComponent(world, eid, c.Trim, { start: node.inPoint - delay });+ assert(typeof parsed === "number", "`start` must be a string or number" + `, value: ${value}`);+ node.start = parsed;+ this.reconcileTiming(node);break;- } case "outPoint": {+ } case "end": {const parsed = parseFrames(String(value), 30);- assert(typeof parsed === "number", "`outPoint` must be a string or number" + `, value: ${value}`);- node.outPoint = parsed;- const delay = node.startTime ?? 0;- setComponent(world, eid, c.Trim, { end: node.outPoint - delay });+ assert(typeof parsed === "number", "`end` must be a string or number" + `, value: ${value}`);+ node.end = parsed;+ // `end` and `sourceOut` are two spellings of the clip's out edge.+ node.sourceOut = undefined;+ this.reconcileTiming(node);break;- }- case "startTime": {+ } case "sourceIn": {const parsed = parseFrames(String(value), 30);- assert(typeof parsed === "number", "`startTime` must be a string or number" + `, value: ${value}`);- node.startTime = parsed;- setComponent(world, eid, c.Delay, node.startTime);- if (node.inPoint !== undefined) {- setComponent(world, eid, c.Trim, { start: node.inPoint - node.startTime });- }- if (node.outPoint !== undefined) {- setComponent(world, eid, c.Trim, { end: node.outPoint - node.startTime });- }+ assert(typeof parsed === "number", "`sourceIn` must be a string or number" + `, value: ${value}`);+ node.sourceIn = parsed;+ this.reconcileTiming(node);+ break;+ } case "sourceOut": {+ const parsed = parseFrames(String(value), 30);+ assert(typeof parsed === "number", "`sourceOut` must be a string or number" + `, value: ${value}`);+ node.sourceOut = parsed;+ node.end = undefined;+ this.reconcileTiming(node);break;}case "fill": {diff --git a/docs/composition.md b/docs/composition.mdindex f019397e..1f399945 100644--- a/docs/composition.md+++ b/docs/composition.md@@ -36,7 +36,7 @@ The first rendered root becomes the active scene. New roots are auto-placed on t| `<text>` | Editable text. || `<video>` / `<image>` | Media; `src` is required. || `<audio>` | Sound only, no spatial props. |-| `<sequence>` | Lays children out back-to-back in time. |+| `<sequence>` | Track container for back-to-back clips (positions are explicit); hosts transitions. || `<captions>` | Transcribes the scene's audio into styled captions. || `<solidPaint>`, `<linearGradientPaint>`, `<radialGradientPaint>`, `<colorStop>` | Fills, declared as children; see [Paints](#paints). |@@ -53,7 +53,7 @@ User-defined components are ordinary Solid components; only intrinsic elements p| `rotation` | `0` | Degrees. Animatable. || `opacity` | `1` | `0`–`1`. Animatable. || `cornerRadius` | `0` | Px. Animatable. |-| `inPoint`, `outPoint`, `startTime` | see [Timing](#timing) | Temporal placement. |+| `start`, `end`, `sourceIn`, `sourceOut` | see [Timing](#timing) | Temporal placement. || `transition` | none | Cut into the next clip; `<sequence>` children only. See [Transitions](#transitions). |Animatable props also take a keyframe list — see [Animation](#animation).@@ -86,30 +86,33 @@ These same props are what `dapi node patch` assigns on existing nodes.## Timing-Composition-relative, Lottie-inspired. Values take any [time format](cli.md#time-values) (seconds, `"45f"` frames, `"MM:SS"`).+`start`/`end` place a clip on the parent timeline; `sourceIn`/`sourceOut` select which part of its source plays. The two are independent. Values take any [time format](cli.md#time-values) (seconds, `"45f"` frames, `"MM:SS"`).| Prop | Meaning || --- | --- |-| `inPoint` / `outPoint` | The window on the parent timeline where the node is visible/audible. Omitted: media fits its natural duration, groups auto-fit their children. |-| `startTime` | Where source time 0 sits on the composition timeline (defaults to the in point). May be negative to skip into the source. |+| `start` / `end` | Parent-timeline window. `start` defaults to 0; omit both and media fits its natural duration, groups auto-fit their children. |+| `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" inPoint={0} outPoint={16} startTime="-30f" />-// plays from composition 0-16 s, starting 1 s (30 frames) into the source+<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" />+// a sourceless node placed straight on the timeline: on screen from 2 s to 5 s```-`<sequence>` removes the arithmetic for back-to-back cuts: children are placed sequentially and non-overlapping in document order.+`<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 `startTime` 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`.+`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" inPoint={0} outPoint={45} muted />+<video key="camera" src="/Movies/take-3.mp4" sourceOut={45} muted /><audio src="/Movies/lav.wav" syncTo="camera" />```-`syncTo` and `startTime` are mutually exclusive; `inPoint`/`outPoint` 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.+`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@@ -117,8 +120,8 @@ A clip inside a `<sequence>` takes a `transition` prop rendering the cut into th```tsx<sequence>- <video src="/Movies/a.mp4" outPoint={8} transition={{ type: "fadeToBlack", duration: 0.5 }} />- <video src="/Movies/b.mp4" />+ <video src="/Movies/a.mp4" start={0} end={8} transition={{ type: "fadeToBlack", duration: 0.5 }} />+ <video src="/Movies/b.mp4" start={8} /></sequence>```@@ -141,7 +144,7 @@ Animatable props (`x`, `y`, `width`, `height`, `rotation`, `opacity`, `cornerRad```tsx<imagesrc="/photo.jpg"- inPoint={0} outPoint={5}+ start={0} end={5}x={[{ time: 0, value: -400 },{ time: 1, value: 200, easing: "easeOut" },diff --git a/packages/jsx/src/types.ts b/packages/jsx/src/types.tsindex d9763b7d..0010f563 100644--- a/packages/jsx/src/types.ts+++ b/packages/jsx/src/types.ts@@ -34,7 +34,7 @@ export type Easing =| `steps(${string})`;export type Keyframe<T> = {- /** Node-local time: 0 is the node's in point. Any `Time` format. */+ /** Node-local time: 0 is where the clip begins (its `start`). Any `Time` format. */time: Time;value: T;/** Shapes the segment to the next keyframe; ignored on the last. Default "linear". */@@ -100,16 +100,18 @@ export type PatchProps = {opacity?: Animatable<number>;/** Uniform corner radius, px. Animatable. */cornerRadius?: Animatable<number>;- /** Composition time at which the node becomes visible/audible. */- inPoint?: Time;- /** Composition time at which the node stops. */- outPoint?: Time;- /** Composition time at which the node's source time 0 is placed. Defaults to the in point. */- startTime?: Time;+ /** Parent-timeline time at which the node begins. Default 0. */+ start?: Time;+ /** Parent-timeline time at which the node ends. Alternative to `sourceOut`. */+ end?: Time;+ /** Source in point: where playback begins within the source, trimming the head. Default 0. */+ sourceIn?: Time;+ /** Source out point: where playback ends within the source. Defaults to the natural end. Alternative to `end`. */+ sourceOut?: Time;/**- * Key of another element carrying an audio track. Derives `startTime` by- * cross-correlating the two audio signals so the recordings coincide on the- * timeline. Mutually exclusive with `startTime`.+ * Key of another element carrying an audio track. Derives the timeline+ * placement (`start`) by cross-correlating the two audio signals so the+ * recordings coincide on the timeline. Mutually exclusive with `start`.*/syncTo?: string;/**@@ -160,9 +162,10 @@ export const PATCH_PROP_KEYS = Object.keys({rotation: true,opacity: true,cornerRadius: true,- inPoint: true,- outPoint: true,- startTime: true,+ start: true,+ end: true,+ sourceIn: true,+ sourceOut: true,syncTo: true,transition: true,fill: true,@@ -182,7 +185,7 @@ export const PATCH_PROP_KEYS = Object.keys({colors: true,} satisfies Record<keyof PatchProps, true>) as ReadonlyArray<keyof PatchProps>;-type TimingProps = Pick<PatchProps, "inPoint" | "outPoint" | "startTime">;+type TimingProps = Pick<PatchProps, "start" | "end" | "sourceIn" | "sourceOut">;type CommonProps = TimingProps &Pick<