Skip to content

The VS Code of video editing, built for agents.

TypeScript

Add adjustment layer support to JSX and reconciler

konstantin-paulus3e8602d40705
diff --git a/packages/jsx/src/index.ts b/packages/jsx/src/index.ts
index 2d86852b..01ab1b51 100644
--- a/packages/jsx/src/index.ts
+++ b/packages/jsx/src/index.ts
@@ -37,6 +37,7 @@ export type { CompositionTag, PropValue } from "./source";
export { useTicker, useFile } from "./hooks";
export type { Ticker } from "./hooks";
export type {
+ AdjustmentLayerProps,
AnimatableProperty,
AnimationProps,
AnimationType,
diff --git a/packages/jsx/src/jsx-runtime.ts b/packages/jsx/src/jsx-runtime.ts
index 69686c24..e2478b6e 100644
--- a/packages/jsx/src/jsx-runtime.ts
+++ b/packages/jsx/src/jsx-runtime.ts
@@ -21,6 +21,7 @@
import type { JSX as SolidJSX } from "solid-js";
import type { AssetInput } from "./generate";
import type {
+ AdjustmentLayerProps,
AnimationProps,
AudioProps,
CaptionsProps,
@@ -87,6 +88,7 @@ export declare namespace JSX {
textRange: TextRangeProps & SourceProps;
sequence: SequenceProps & SourceProps;
captions: CaptionsProps & SourceProps;
+ adjustmentLayer: AdjustmentLayerProps & SourceProps;
solidPaint: SolidPaintProps & SourceProps;
linearGradientPaint: GradientPaintProps & SourceProps;
radialGradientPaint: GradientPaintProps & SourceProps;
diff --git a/packages/jsx/src/source.ts b/packages/jsx/src/source.ts
index 90cd5cfb..2e6fd10a 100644
--- a/packages/jsx/src/source.ts
+++ b/packages/jsx/src/source.ts
@@ -100,6 +100,7 @@ export const COMPOSITION_TAGS = [
"textRange",
"sequence",
"captions",
+ "adjustmentLayer",
"solidPaint",
"linearGradientPaint",
"radialGradientPaint",
diff --git a/packages/jsx/src/types.ts b/packages/jsx/src/types.ts
index 6104d367..1a30f51d 100644
--- a/packages/jsx/src/types.ts
+++ b/packages/jsx/src/types.ts
@@ -408,6 +408,31 @@ export type GroupProps = CommonProps & FillProps & {
children?: SolidJSX.Element;
};
+/**
+ * `<adjustmentLayer>` — a layer that draws nothing of its own and transforms
+ * the clip below it: while the layer's own clip lasts, its transform composes
+ * onto that of the sibling directly beneath it in the stack. A punch-in, a
+ * drift or a keyframed zoom is therefore authored once, in a row of its own,
+ * and trimmed and slid along the timeline without the clip it acts on being
+ * touched. In a `<sequence>` the layer acts on what sits below the sequence,
+ * not below the layer inside it.
+ *
+ * `width`/`height` are never drawn: they are the box the transform pivots
+ * around, so `rotation` and `scale` turn about the middle of a frame that
+ * size. Default 1920x1080 — set them to the scene's own size on a frame
+ * shaped otherwise.
+ */
+export type AdjustmentLayerProps =
+ & IdentityProps
+ & Omit<TransformProps, "opacity" | "cornerRadius" | "cornerRadiusTopLeft" | "cornerRadiusTopRight" | "cornerRadiusBottomRight" | "cornerRadiusBottomLeft">
+ & Pick<CompositeProps, "hidden">
+ & TimingProps
+ & SequenceItemProps
+ & {
+ /** `<Animation>` and `<KeyframeTrack>` children — what the layer's transform is animated with. */
+ children?: SolidJSX.Element;
+ };
+
export type RectProps = CommonProps & FillProps & {
/**
* Makes the rect a mask of its parent: it clips the parent (its fills,
diff --git a/packages/reconciler/src/document.ts b/packages/reconciler/src/document.ts
index 47d0a17b..3a35b458 100644
--- a/packages/reconciler/src/document.ts
+++ b/packages/reconciler/src/document.ts
@@ -3,7 +3,7 @@
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
-import { Active, Animation, AnimationPhase, AnimationType, appendChild, AssetId, Audio, Background, BlendMode, BlendModeType, Blur, Caption, CaptionAlign, CaptionType, Chars, ClipHeight, ClipsContent, CornerRadius, createEntity, DEFAULT_BACKGROUND, Color, ColorStop, Effect, EffectType, End, Expanded, FontStyle, FrameRate, Loop, Geometry, GeometryType, Library, getEntityTree, getParentEntity, getParentNode, Hidden, IsMask, isText, ItemIndex, Keyframe, KeyframeTrack, MixedCornerRadius, Muted, Name, Offset, Opacity, Paint, PaintType, parseColor, Playback, PlaybackRate, Position, removeChild, resizeEntity, Scale, ScaleMode, ScaleModeType, secondsToFrames, getAsset, getAssetFile, getEntityChildren, getLibrary, Group, Sequential, Shader, Size, Stage, Root, Rotation, Scene, Selected, Shadow, Source, SourceIn, SourceOut, setCameraMatrix, Start, Stroke, StrokeCap, StrokeJoin, StrokeStyle, SurfaceHost, SurfaceHostHandle, TextAlign, TextBaseline, TextCase, TextRange, TextStyle, Transition, TransitionType, UniformScale, Volume } from '@diffusionstudio/runtime';
+import { Active, AdjustmentLayer, Animation, AnimationPhase, AnimationType, appendChild, AssetId, Audio, Background, BlendMode, BlendModeType, Blur, Caption, CaptionAlign, CaptionType, Chars, ClipHeight, ClipsContent, CornerRadius, createEntity, DEFAULT_BACKGROUND, Color, ColorStop, Effect, EffectType, End, Expanded, FontStyle, FrameRate, Loop, Geometry, GeometryType, Library, getEntityTree, getParentEntity, getParentNode, Hidden, IsMask, isText, ItemIndex, Keyframe, KeyframeTrack, MixedCornerRadius, Muted, Name, Offset, Opacity, Paint, PaintType, parseColor, Playback, PlaybackRate, Position, removeChild, resizeEntity, Scale, ScaleMode, ScaleModeType, secondsToFrames, getAsset, getAssetFile, getEntityChildren, getLibrary, Group, Sequential, Shader, Size, Stage, Root, Rotation, Scene, Selected, Shadow, Source, SourceIn, SourceOut, setCameraMatrix, Start, Stroke, StrokeCap, StrokeJoin, StrokeStyle, SurfaceHost, SurfaceHostHandle, TextAlign, TextBaseline, TextCase, TextRange, TextStyle, Transition, TransitionType, UniformScale, Volume } from '@diffusionstudio/runtime';
import { isPropValue, LOOP_ATTR, parseTime, SOURCE_ATTR } from '@diffusionstudio/jsx';
import type { CameraMatrix, PropertyPath } from '@diffusionstudio/runtime';
@@ -444,6 +444,14 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
entity.add(Caption);
break;
}
+ case 'adjustmentLayer': {
+ entity = createEntity(this.world);
+ entity.add(AdjustmentLayer);
+ entity.add(Position);
+ entity.set(Position, { x: 0, y: 0 });
+ resizeEntity(this.world, entity, { width: 1920, height: 1080 });
+ break;
+ }
case 'rect': {
entity = createEntity(this.world);
entity.add(Geometry);
@@ -582,7 +590,7 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
}
default:
throw new Error(
- `<${tag}> is not supported yet (only <stage>, <scene>, <group>, <sequence>, <captions>, <rect>, <text>, <textRange>, <video>, <image>, <audio>, <surface>, <solidPaint>, <linearGradientPaint>, <radialGradientPaint>, <shaderPaint>, <surfacePaint>, <imagePaint>, <videoPaint>, <colorStop>, <stroke>, <shadow>, <effect>, <animation>, <keyframeTrack> and <keyframe>).`,
+ `<${tag}> is not supported yet (only <stage>, <scene>, <group>, <sequence>, <captions>, <adjustmentLayer>, <rect>, <text>, <textRange>, <video>, <image>, <audio>, <surface>, <solidPaint>, <linearGradientPaint>, <radialGradientPaint>, <shaderPaint>, <surfacePaint>, <imagePaint>, <videoPaint>, <colorStop>, <stroke>, <shadow>, <effect>, <animation>, <keyframeTrack> and <keyframe>).`,
);
}
diff --git a/packages/reconciler/src/elements.ts b/packages/reconciler/src/elements.ts
index 76fdb1d4..9a1eb002 100644
--- a/packages/reconciler/src/elements.ts
+++ b/packages/reconciler/src/elements.ts
@@ -19,6 +19,7 @@ import { createElement, createTextNode, insertNode, setProp, spread, use } from
import type { JSX as SolidJSX } from "solid-js";
import type { AuthoredTree } from "./document";
import type {
+ AdjustmentLayerProps,
AnimationProps,
AudioProps,
CaptionsProps,
@@ -93,6 +94,7 @@ export const Text = hostElement<TextProps>("Text");
export const TextRange = hostElement<TextRangeProps>("TextRange");
export const Sequence = hostElement<SequenceProps>("Sequence");
export const Captions = hostElement<CaptionsProps>("Captions");
+export const AdjustmentLayer = hostElement<AdjustmentLayerProps>("AdjustmentLayer");
export const SolidPaint = hostElement<SolidPaintProps>("SolidPaint");
export const LinearGradientPaint = hostElement<GradientPaintProps>("LinearGradientPaint");
export const RadialGradientPaint = hostElement<GradientPaintProps>("RadialGradientPaint");
diff --git a/packages/runtime/src/actions/timing.ts b/packages/runtime/src/actions/timing.ts
index e9244e04..725c15f5 100644
--- a/packages/runtime/src/actions/timing.ts
+++ b/packages/runtime/src/actions/timing.ts
@@ -9,7 +9,7 @@
import { store } from '../world/store';
import { DEFAULT_DURATION_FRAMES } from '../constants';
import {
- Geometry, Group, Paint, Caption, Cache, Computed, AssetId, IsMask,
+ Geometry, Group, AdjustmentLayer, Paint, Caption, Cache, Computed, AssetId, IsMask,
Start, End, SourceIn, SourceOut, PlaybackRate, CaptionDecoderHandle,
} from '../traits';
import { isGroupLike } from '../queries/predicates';
@@ -280,7 +280,7 @@ export function reactToGeometryDurationChange(world: World, entity: Entity) {
}
export function reactToChildAttached(world: World, child: Entity) {
- if (child.has(Geometry) || child.has(Group)) {
+ if (child.has(Geometry) || child.has(Group) || child.has(AdjustmentLayer)) {
propagateTimeRangeDown(world, child);
bubbleTimeRangeUp(world, child);
return;
@@ -298,7 +298,7 @@ export function reactToChildAttached(world: World, child: Entity) {
* source and needs its current span pinned.
*/
export function reactToChildDetached(world: World, child: Entity) {
- if (child.has(Geometry) || child.has(Group)) {
+ if (child.has(Geometry) || child.has(Group) || child.has(AdjustmentLayer)) {
bubbleTimeRangeUp(world, child);
return;
}
diff --git a/reference/jsx/README.md b/reference/jsx/README.md
index 6f850ba1..f9a5afc9 100644
--- a/reference/jsx/README.md
+++ b/reference/jsx/README.md
@@ -27,6 +27,7 @@ The markup is **pseudo-SVG**: elements like `<rect>`, `<text>`, `<linearGradient
| [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 |
+| [adjustment-layer.md](./adjustment-layer.md) | `<adjustmentLayer>`: a transform over the clip below it |
| [audio-sync.md](./audio-sync.md) | `syncTo` audio alignment |
| [captions.md](./captions.md) | `<captions>` and style presets |
| [generate.md](./generate.md) | Declarative AI asset generation (`generate.*`) |
diff --git a/reference/jsx/adjustment-layer.md b/reference/jsx/adjustment-layer.md
new file mode 100644
index 00000000..ac06c10f
--- /dev/null
+++ b/reference/jsx/adjustment-layer.md
@@ -0,0 +1,43 @@
+# `<adjustmentLayer>`
+
+A layer that draws nothing of its own and transforms **the clip below it**. While the layer's clip lasts, its transform composes onto that of the sibling directly beneath it in the stack, so a punch-in, a drift or a keyframed zoom is authored once, in a row of its own, and trimmed and slid along the timeline without the clip it acts on being touched.
+
+```tsx
+<scene width={1920} height={1080}>
+ <video src="interview.mp4" />
+ <adjustmentLayer start={2} end={6} scale={1.4} />
+</scene>
+```
+
+Keyframe it the way any node is keyframed (see [keyframes.md](./keyframes.md)) — this is what the element is for:
+
+```tsx
+<adjustmentLayer name="Punch in" start={2} end={6}>
+ <keyframeTrack property="scale">
+ <keyframe time={0} value={1} easing="easeInOut" />
+ <keyframe time={2} value={1.6} />
+ </keyframeTrack>
+</adjustmentLayer>
+```
+
+## What it acts on
+
+The **preceding sibling** — one clip, the one drawn directly beneath the layer — for as long as the layer's own `start`/`end` window lasts. Outside that window, or with `hidden`, the clip is left alone. A layer that is the first child of its parent has nothing beneath it and does nothing.
+
+Inside a [`<sequence>`](./sequences.md) the layer acts on what sits below the *sequence*, not on the clip before it inside one: a sequence is a row of clips over time, so "beneath" is measured against the row.
+
+## Props
+
+| Prop | Type | Default | Meaning |
+| ---- | ---- | ------- | ------- |
+| `x`, `y` | `number` | `0` | Translation applied to the clip below, px. |
+| `offsetX`, `offsetY` | `number` | `0` | Render-time translation on top of `x`/`y`, px. |
+| `rotation` | `number` | `0` | Rotation in degrees, about the box centre. |
+| `scale` | `number` | `1` | Uniform scale about the box centre. Overrides `scaleX`/`scaleY` while set. |
+| `scaleX`, `scaleY` | `number` | `1` | Per-axis scale. |
+| `width`, `height` | `number` | `1920` × `1080` | **Never drawn**: the box the transform pivots around. Set them to the scene's own size on a frame shaped otherwise, so `rotation` and `scale` turn about its middle. |
+| `hidden` | `boolean` | absent | Excludes the layer without removing it: the clip below is left alone and the layer keeps its place in the timeline. |
+| `start`, `end`, `sourceIn`, `sourceOut` | `Time` | see [timing.md](./timing.md) | When the layer acts. |
+| `name` | `string` | none | Human-readable node name. |
+
+It has no `fill`, no `opacity` and no `blendMode`: it has no pixels of its own to give them to. Its children are [`<animation>`](./animations.md) and [`<keyframeTrack>`](./keyframes.md) elements — what the layer's transform is animated with.
diff --git a/reference/jsx/elements.md b/reference/jsx/elements.md
index 6419dcf6..703ea273 100644
--- a/reference/jsx/elements.md
+++ b/reference/jsx/elements.md
@@ -13,6 +13,7 @@ camelCase composition elements map 1:1 onto internal node types. Lowercase DOM v
| [`<textRange>`](./text.md#textrange) | **Text range sub-entity** | Style override over a run of the parent `<text>`'s glyphs, by character index. |
| [`<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. |
+| [`<adjustmentLayer>`](./adjustment-layer.md) | **Adjustment layer** | Draws nothing; its transform composes onto the clip directly below it, for as long as its own clip lasts. |
| [`<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. |