Skip to content

The VS Code of video editing, built for agents.

TypeScript

Implement horizontal and vertical constraints in the inspector

konstantin-paulus5481035f179f
diff --git a/apps/web/src/components/sidebar-right/inspector/transform/constants.ts b/apps/web/src/components/sidebar-right/inspector/transform/constants.ts
index 049b8cf7..04c8d04a 100644
--- a/apps/web/src/components/sidebar-right/inspector/transform/constants.ts
+++ b/apps/web/src/components/sidebar-right/inspector/transform/constants.ts
@@ -3,6 +3,9 @@
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
import { ConstraintType } from "@diffusionstudio/runtime";
+import { HORIZONTAL_CONSTRAINTS, VERTICAL_CONSTRAINTS } from "@diffusionstudio/reconciler";
+
+import type { HorizontalConstraint, VerticalConstraint } from "@diffusionstudio/jsx";
export type Constraint = {
key: ConstraintType;
@@ -43,3 +46,21 @@ export const verticalConstraints: Constraint[] = [
{ key: ConstraintType.STRETCH, label: 'Top & bottom' },
{ key: ConstraintType.SCALE, label: 'Scale' },
];
+
+const HORIZONTAL_NAMES = new Map<ConstraintType, HorizontalConstraint>(
+ Object.entries(HORIZONTAL_CONSTRAINTS).map(([name, type]) => [type, name as HorizontalConstraint]),
+);
+
+const VERTICAL_NAMES = new Map<ConstraintType, VerticalConstraint>(
+ Object.entries(VERTICAL_CONSTRAINTS).map(([name, type]) => [type, name as VerticalConstraint]),
+);
+
+/** The anchor as the JSX spells it on the horizontal axis (`constrainX="right"`). */
+export function horizontalConstraintName(type: ConstraintType): HorizontalConstraint {
+ return HORIZONTAL_NAMES.get(type) ?? "left";
+}
+
+/** The same on the vertical axis (`constrainY="bottom"`). */
+export function verticalConstraintName(type: ConstraintType): VerticalConstraint {
+ return VERTICAL_NAMES.get(type) ?? "top";
+}
diff --git a/apps/web/src/components/sidebar-right/inspector/transform/constraints-row.tsx b/apps/web/src/components/sidebar-right/inspector/transform/constraints-row.tsx
index 8b528017..540f49b7 100644
--- a/apps/web/src/components/sidebar-right/inspector/transform/constraints-row.tsx
+++ b/apps/web/src/components/sidebar-right/inspector/transform/constraints-row.tsx
@@ -11,9 +11,15 @@ import {
SelectItem,
SelectPortal,
} from "@/components/ui/select";
-import { horizontalConstraints, verticalConstraints } from "./constants";
+import {
+ horizontalConstraintName,
+ horizontalConstraints,
+ verticalConstraintName,
+ verticalConstraints,
+} from "./constants";
import { useTrait } from "@diffusionstudio/koota-solid";
import { Constraint, ConstraintType } from "@diffusionstudio/runtime";
+import { useEditor } from "@/engine/hooks";
import type { Entity } from "koota";
@@ -22,33 +28,43 @@ type ConstraintsRowProps = {
};
/**
- * How the node follows its scene's frame when that frame resizes. `Constraint`
- * has no JSX spelling, so this writes the trait alone; the runtime seeds the
- * cache it resolves against the first time it sees the node with one, so a
- * constraint set here does not move anything until the frame changes.
+ * How the node follows its scene's frame when that frame resizes, written to
+ * the document as `constrainX`/`constrainY`. The runtime seeds the cache it
+ * resolves against the first time it sees the node with a constraint, so one
+ * set here does not move anything until the frame changes.
+ *
+ * Each axis is written on its own, and `MIN` — pinned where the node already
+ * is — spells as the prop's absence, the way every other default does. The
+ * two writes the centre button makes land in one history step, as any two
+ * edits in a burst do.
*/
export function ConstraintsRow(props: ConstraintsRowProps) {
+ const editor = useEditor();
const constraint = useTrait(() => props.node, Constraint);
const horizontal = () => constraint()?.horizontal ?? ConstraintType.MIN;
const vertical = () => constraint()?.vertical ?? ConstraintType.MIN;
- const assign = (value: Partial<{ horizontal: ConstraintType; vertical: ConstraintType }>) => {
- props.node.add(Constraint);
- props.node.set(Constraint, value);
- };
-
const assignHorizontal = (value: ConstraintType | null) => {
if (value == null) return;
- assign({ horizontal: value });
+ editor.editProperty(
+ props.node,
+ "constrainX",
+ value === ConstraintType.MIN ? false : horizontalConstraintName(value),
+ );
};
const assignVertical = (value: ConstraintType | null) => {
if (value == null) return;
- assign({ vertical: value });
+ editor.editProperty(
+ props.node,
+ "constrainY",
+ value === ConstraintType.MIN ? false : verticalConstraintName(value),
+ );
};
const assignCenter = () => {
- assign({ horizontal: ConstraintType.CENTER, vertical: ConstraintType.CENTER });
+ assignHorizontal(ConstraintType.CENTER);
+ assignVertical(ConstraintType.CENTER);
};
return (
diff --git a/apps/web/src/components/sidebar-right/inspector/transform/transform-settings.tsx b/apps/web/src/components/sidebar-right/inspector/transform/transform-settings.tsx
index 5a6bc319..0bc1d988 100644
--- a/apps/web/src/components/sidebar-right/inspector/transform/transform-settings.tsx
+++ b/apps/web/src/components/sidebar-right/inspector/transform/transform-settings.tsx
@@ -46,12 +46,12 @@ type TransformAddons = Partial<Record<TransformAddon, boolean>>;
/**
* Where a node sits and how it is transformed there. Position, rotation,
- * offset and scale are props (`x`/`y`, `rotation`, `offsetX`/`offsetY`,
- * `scale` or `scaleX`/`scaleY`) written through the editor; anchor, flip,
- * skew and constraints have no JSX spelling and are written to their traits
- * alone, so they do not survive a recompile. The rows below Position are
- * opt-in and which ones are shown is app state, kept per user rather than
- * per node.
+ * offset, scale and constraints are props (`x`/`y`, `rotation`,
+ * `offsetX`/`offsetY`, `scale` or `scaleX`/`scaleY`,
+ * `constrainX`/`constrainY`) written through the editor; anchor, flip and
+ * skew have no JSX spelling and are written to their traits alone, so they do
+ * not survive a recompile. The rows below Position are opt-in and which ones
+ * are shown is app state, kept per user rather than per node.
*/
export function TransformSettings(props: TransformSettingsProps) {
const world = useWorld();
diff --git a/packages/jsx/src/index.ts b/packages/jsx/src/index.ts
index 8e2a15d3..9e8350de 100644
--- a/packages/jsx/src/index.ts
+++ b/packages/jsx/src/index.ts
@@ -64,6 +64,7 @@ export type {
Fit,
GradientPaintProps,
GroupProps,
+ HorizontalConstraint,
HtmlPaintProps,
HtmlProps,
ImageProps,
@@ -90,5 +91,6 @@ export type {
Time,
TransitionSpec,
TransitionType,
+ VerticalConstraint,
VideoProps,
} from "./types";
diff --git a/packages/jsx/src/types.ts b/packages/jsx/src/types.ts
index a62187e2..9668e088 100644
--- a/packages/jsx/src/types.ts
+++ b/packages/jsx/src/types.ts
@@ -21,6 +21,19 @@ export type StrokeJoin = "miter" | "round" | "bevel";
/** How a stroke ends an open path: the canvas `lineCap` values. */
export type StrokeCap = "butt" | "round" | "square";
+/**
+ * How an element follows its scene's frame along one axis when that frame is
+ * resized: pinned to the near edge ("left"/"top", the default), to the far
+ * one ("right"/"bottom"), to the middle ("center"), to both edges at once
+ * ("stretch", which resizes the element to keep either margin), or to the
+ * frame's proportions ("scale", which moves and resizes it by the frame's
+ * ratio).
+ */
+export type HorizontalConstraint = "left" | "right" | "center" | "stretch" | "scale";
+
+/** The vertical axis of `HorizontalConstraint`. */
+export type VerticalConstraint = "top" | "bottom" | "center" | "stretch" | "scale";
+
/**
* How an element composites over what is below it: the canvas
* `globalCompositeOperation` blend modes, camelCase. Default "sourceOver".
@@ -221,6 +234,16 @@ type SizeProps = {
};
type TransformProps = PositionProps & OffsetProps & SizeProps & {
+ /**
+ * How the element follows its scene's frame when that frame is resized —
+ * horizontally, then vertically. They are read only against a frame that
+ * changes size, so a constraint moves nothing until the scene is resized;
+ * a `<sequence>` is not a frame of its own and its children are constrained
+ * to the frame the sequence sits in. Default "left" and "top", which pin
+ * the element where it is.
+ */
+ constrainX?: HorizontalConstraint;
+ constrainY?: VerticalConstraint;
/** Rotation in degrees. */
rotation?: number;
/** Uniform scale about the box origin, 1 = natural size. Overrides `scaleX`/`scaleY` while set. */
diff --git a/packages/reconciler/src/document.ts b/packages/reconciler/src/document.ts
index 38ab1c2f..ebbd4fd1 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, AdjustmentLayer, Animation, AnimationPhase, AnimationType, appendChild, AssetId, Audio, Background, bindAsset, BlendMode, BlendModeType, Blur, Caption, CaptionAlign, CAPTION_PRESET_FILLS, CAPTION_PRESET_STYLES, CaptionType, Chars, ClipHeight, ClipsContent, Computed, CornerRadius, createEntity, DEFAULT_BACKGROUND, Color, ColorStop, Delay, Effect, EffectType, Expanded, FontStyle, FramePromises, FrameRate, Generating, GenerationRequest, getActiveEntity, Loop, LoadRequest, Geometry, GeometryType, getEntityTree, getParentEntity, getParentNode, Hidden, Host, IsMask, isText, ItemIndex, KeepAspectRatio, Keyframe, KeyframeTrack, MixedCornerRadius, Mode, Muted, Name, Offset, Opacity, Paint, PaintType, parseColor, PendingSource, PendingSync, Playback, PlaybackRate, Position, removeChild, RenderSurface, resizeEntity, Scale, ScaleMode, ScaleModeType, secondsToFrames, getAsset, getEntityChildren, Group, Sequential, Shader, Size, Stage, Root, Rotation, Scene, Selected, Shadow, Source, SourceError, SourceFrameRate, SourceModifiers, hasModifier, setCameraMatrix, setTimelineView, Stroke, StrokeCap, StrokeJoin, StrokeStyle, SyncRequest, TextAlign, TextBaseline, TextCase, TextRange, TextStyle, TranscriptionRequest, Transition, TransitionType, Trim, UniformScale, Volume, Workarea } from '@diffusionstudio/runtime';
+import { Active, AdjustmentLayer, Animation, AnimationPhase, AnimationType, appendChild, AssetId, Audio, Background, bindAsset, BlendMode, BlendModeType, Blur, Caption, CaptionAlign, CAPTION_PRESET_FILLS, CAPTION_PRESET_STYLES, CaptionType, Chars, ClipHeight, ClipsContent, Computed, Constraint, ConstraintCache, ConstraintType, CornerRadius, createEntity, DEFAULT_BACKGROUND, Color, ColorStop, Delay, Effect, EffectType, Expanded, FontStyle, FramePromises, FrameRate, Generating, GenerationRequest, getActiveEntity, Loop, LoadRequest, Geometry, GeometryType, getEntityTree, getParentEntity, getParentNode, Hidden, Host, IsMask, isText, ItemIndex, KeepAspectRatio, Keyframe, KeyframeTrack, MixedCornerRadius, Mode, Muted, Name, Offset, Opacity, Paint, PaintType, parseColor, PendingSource, PendingSync, Playback, PlaybackRate, Position, removeChild, RenderSurface, resizeEntity, Scale, ScaleMode, ScaleModeType, secondsToFrames, getAsset, getEntityChildren, Group, Sequential, Shader, Size, Stage, Root, Rotation, Scene, Selected, Shadow, Source, SourceError, SourceFrameRate, SourceModifiers, hasModifier, setCameraMatrix, setTimelineView, Stroke, StrokeCap, StrokeJoin, StrokeStyle, SyncRequest, TextAlign, TextBaseline, TextCase, TextRange, TextStyle, TranscriptionRequest, Transition, TransitionType, Trim, UniformScale, Volume, Workarea } from '@diffusionstudio/runtime';
import { LOOP_ATTR, parseTime, SOURCE_ATTR } from '@diffusionstudio/jsx';
import { createSignal } from 'solid-js';
import { SVGElements } from 'solid-js/web';
@@ -159,6 +159,27 @@ export const BLEND_MODES: Record<string, BlendModeType> = {
luminosity: BlendModeType.LUMINOSITY,
};
+/**
+ * The `constrainX` values as the runtime's anchors: which edge of the scene's
+ * frame the element is pinned to, or how it follows the frame instead.
+ */
+export const HORIZONTAL_CONSTRAINTS: Record<string, ConstraintType> = {
+ left: ConstraintType.MIN,
+ right: ConstraintType.MAX,
+ center: ConstraintType.CENTER,
+ stretch: ConstraintType.STRETCH,
+ scale: ConstraintType.SCALE,
+};
+
+/** The same for `constrainY`, whose near and far edges are top and bottom. */
+export const VERTICAL_CONSTRAINTS: Record<string, ConstraintType> = {
+ top: ConstraintType.MIN,
+ bottom: ConstraintType.MAX,
+ center: ConstraintType.CENTER,
+ stretch: ConstraintType.STRETCH,
+ scale: ConstraintType.SCALE,
+};
+
/**
* A `<keyframeTrack>`'s `property` (a prop name) as the runtime's property
* path. `width` depends on the holder: a stroke's is its line width.
@@ -883,6 +904,28 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {
entity.set(Scale, { [name === 'scaleX' ? 'x' : 'y']: toNumber(value) ?? 1 });
return;
}
+ case 'constrainX':
+ case 'constrainY': {
+ const { entity, props } = node;
+ // A sequence is not a spatial construct; it mirrors its parent's frame.
+ if (entity.has(Sequential)) return;
+
+ const horizontal = typeof props.constrainX === 'string' ? HORIZONTAL_CONSTRAINTS[props.constrainX] : undefined;
+ const vertical = typeof props.constrainY === 'string' ? VERTICAL_CONSTRAINTS[props.constrainY] : undefined;
+
+ if (horizontal === undefined && vertical === undefined) {
+ entity.remove(Constraint);
+ entity.remove(ConstraintCache);
+ return;
+ }
+
+ entity.add(Constraint);
+ entity.set(Constraint, {
+ horizontal: horizontal ?? ConstraintType.MIN,
+ vertical: vertical ?? ConstraintType.MIN,
+ });
+ return;
+ }
case 'cornerRadius': {
const radius = toNumber(value);
if (radius === undefined) {
diff --git a/reference/jsx/elements.md b/reference/jsx/elements.md
index 66309a4d..a43b261f 100644
--- a/reference/jsx/elements.md
+++ b/reference/jsx/elements.md
@@ -88,6 +88,8 @@ Every node accepts:
| `offsetX`, `offsetY` | `number` | `0` | Render-time translation on top of `x`/`y`, px; moves the drawn content without changing the layout box (the channel the slide animations drive). Subpixel values are kept. |
| `width`, `height` | `number` | per element | Box size, px — see the table above. |
| `keepAspectRatio` | `boolean` | absent | Locks the box to its authored proportions: resizing one bound (an editor handle, a layout row) drives the other so the ratio `width`:`height` has is kept — or, with neither authored, the ratio the box currently has. |
+| `constrainX` | `"left" \| "right" \| "center" \| "stretch" \| "scale"` | `"left"` | How the element follows its scene's frame when that frame is resized, horizontally — see below. |
+| `constrainY` | `"top" \| "bottom" \| "center" \| "stretch" \| "scale"` | `"top"` | The same vertically. |
| `rotation` | `number` | `0` | Rotation in degrees. |
| `scale` | `number` | `1` | Uniform scale about the box origin. Overrides `scaleX`/`scaleY` while set. |
| `scaleX`, `scaleY` | `number` | `1` | Per-axis scale. |
@@ -102,6 +104,18 @@ Every node accepts:
Props are animated by [`<keyframeTrack>`](./keyframes.md) children naming them; preset in/out effects are [`<animation>`](./animations.md) children. No prop takes keyframes inline.
+### Constraints
+
+`constrainX` and `constrainY` say what an element does when **the frame it sits in is resized** — a scene taken from 1920×1080 to 1080×1920, say. Nothing else reads them: a constraint moves nothing at the moment it is written, only the next time the frame changes size.
+
+| Value | `constrainX` | `constrainY` |
+| ----- | ------------ | ------------ |
+| `"left"` / `"top"` | Keeps its distance from the left edge — where an element with no constraint stays. | The same from the top edge. |
+| `"right"` / `"bottom"` | Keeps its distance from the right edge, so it travels with it. | The same from the bottom edge. |
+| `"center"` | Keeps its position relative to the middle of the frame. | The same vertically. |
+| `"stretch"` | Holds both margins, so the element is **resized** by the frame's width delta. | Holds the top and bottom margins, resizing its height. |
+| `"scale"` | Position and width take the frame's horizontal ratio, so the element keeps its share of the frame. | The same vertically. |
+
### Editor state
Three more props are written by the editor and read back on the next mount. They are not part of the composition — nothing rendered or exported depends on them — but the source is the document, so a row resized in the timeline has nowhere else to be remembered:
diff --git a/reference/jsx/scene.md b/reference/jsx/scene.md
index c7b029f8..94191772 100644
--- a/reference/jsx/scene.md
+++ b/reference/jsx/scene.md
@@ -25,6 +25,8 @@ A scene is the **clipped, playable frame** a composition is made in, and the onl
A scene also takes paints as children, exactly as a `<rect>` does (see [paints.md](./paints.md)); `fill` is the shorthand for a solid one.
+What happens to the children when the frame is resized is theirs to say: see [`constrainX`/`constrainY`](./elements.md#constraints).
+
## Editor state in the source
`active`, `selected`, `x`, `y` and `timeline` are editor concerns rather than part of the composition, but they live in the file for the same reason [`<stage>`](./stage.md)'s `camera` does: the source is the document, so a scene dragged or clicked on the canvas — or a timeline scrolled or zoomed — has nowhere else to be written back to. The editor writes them and removes them again; there is no need to author a `timeline`, and the first scroll or zoom overwrites one.