gatewai-dev/framefields/node-compositor

Compositor

What It Does

Composes media inputs into a single image or video using a layout code tree — the ONE source of truth for the composition. Agents author config.layout: a recursive tree of layout nodes (flex / block / box / text / media) with HTML-like auto-layout (dir, gap, padding, justify, align, wrap) and per-node keyframe animations. Rendering is deterministic: (document, frame) → pixels, identical in preview and final render.

When a video layer uses a cached clip-vision matte, the source frame's mask is authoritative: a known absent subject renders empty rather than holding an earlier silhouette. Prompted SAM clip mattes require matching source aspect ratio; apply layout cropping after source-space matting rather than silently detecting another subject.

When to Use

• Title cards / hero layouts: Flex stacks with title + subtitle text and box chips (see example below).
• Overlays / Watermarks: Absolute-positioned text or media over video/image backgrounds.
• Picture-in-Picture: Multiple videos/images arranged by a flex/block tree or absolute placement.
• Timeline composition: Per-node startFrame / durationFrames + keyframe tracks.
• Visual styling: Box fills + radius, text styling, shadows, keyframe motion.

Inputs

This node uses Variable Inputs. You can add dynamically named input handles of the following types:

• Text
• Image
• Video
• Audio
• Caption
• SVG
• GIF
• Lottie
• Signal

Config

`type` vs `kind`: type is an INPUT DataType (Text, Image, Video, Audio,

Caption, SVG, GIF, Lottie …) and never appears on layout nodes. The layout type of

a node is its `kind`: flex | block | box | text | media | shape | chart | model3d | camera | light.

Layout Node Schema

Common fields (every node):

• `id` (string, required): Unique node id — also keys the timeline.
• `kind` (string, required): "flex" | "block" | "box" | "text" | "media" | "shape" | "model3d" | "camera" | "light".
• `inputHandleId` (string, optional): Graph binding — which connected input this node renders (for text/media nodes).

> [!WARNING] > Do not place a handle label in inputHandleId when updating an existing live Compositor. The renderer may treat the media as unbound and produce a blank layer. Use the actual dynamic input handle ID returned from the live Compositor node.

• `position` (string, optional): "relative" (default, in-flow) or "absolute" (out-of-flow; placed by x/y).
• `x` / `y` (number, optional): Offset from the parent's content box (absolute placement / transform base).
• `width` / `height` (SizeSpec, optional): number (pixels), "auto" (content), "fit" (fit content), or "fill" (fill the parent). block defaults to "fill" width.
• `grow` (number, optional): Flex-grow weight — extra main-axis space is split proportionally.
• `flexShrink` (number, optional): Flex shrink factor (Yoga).
• `flexBasis` (number, optional): Flex basis in pixels.
• `alignSelf` (string, optional): Per-child cross-axis override ("auto" | "start" | "center" | "end" | "stretch" | "baseline").
• `aspectRatio` (number, optional): Intrinsic aspect ratio (width / height).
• `zIndex` (number, optional, default 0): Stack order within the same parent level. Higher renders on top.
• `hidden` (boolean, optional): Skips drawing the node.
• `opacity` (number, optional, 0–1, default 1).
• `blendMode` (string, optional, default "normal"): Blend mode used when compositing the node ("normal", "multiply", "screen", "overlay", "darken", "lighten", "color-dodge", "color-burn", "hard-light", "soft-light", "difference", "exclusion", "hue", "saturation", "color", "luminosity", "source-over", "source-in", "source-out", "source-atop", "destination-over", "destination-in", "destination-out", "destination-atop", "lighter", "copy", "mask-in", "mask-out", "xor").
• `rotation` (degrees) / `scale` (multiplier) / `anchorX`, `anchorY` (0–1): Node transform.
• `rotateX` / `rotateY` / `rotateZ` (degrees, default 0): 3D out-of-plane rotation (pitch, yaw, roll).
• `perspective` (number, px distance, default 0 = disabled): Virtual camera distance for 3D perspective foreshortening.
• `translateZ` (number, px depth, default 0): Translation along depth Z axis (moves closer/further under perspective).
• `perspectiveOriginX`, `perspectiveOriginY` (0–1, default 0.5): 3D perspective vanishing point anchor.
• `backfaceVisibility` ("visible" | "hidden", default "visible"): When "hidden", culls the layer when rotated > 90° away from the camera.
• `transformStyle` ("flat" | "preserve-3d", default "flat"): 3D transform rendering style.
• `startFrame` / `durationFrames` (integer, optional): Node visibility window on the master timeline (frames).
• `deflicker` (object, optional): Temporal de-flickering and optical flow motion warping options (blendWeight, disocclusionThreshold, searchRadius).
• `relighting` / `relight` (object, optional): Screen-space 3D normal relighting options (lightType, intensity, lightPosX, lightPosY, lightPosZ, lightRadius, specularStrength, roughness, metallic, ambientIntensity, depthScale, normalTexture).
• `effects` (array, optional): Post-processing effect pipeline attached to the node (e.g. Effect.deflicker(), Effect.relight3d()).
• `animation` (object, optional): Track-based keyframes (§ Animation Schema).

Container styles (flex/block/box with children):

• `dir` (flex only): "row" (default) or "column".
• `gap` (number): Space between children along the main axis.
• `padding` (number): Inset of the content box.
• `justify` (flex only): start (default) | center | end | space-between | space-around.
• `align` (flex/block): start (default) | center | end | stretch.
• `wrap` (flex only, boolean): Allow main-axis wrapping.
• `overflow` ("hidden" (default) | "visible"): Clip children to container bounds (hidden) or allow drawing outside (visible). A hidden container with a borderRadius clips to its rounded corners, animated radius and size included (an iris mask is a box closing its width, height and borderRadius).
• `staggerFrames` (number, optional, default 0): Automatic frame offset sequentially applied to child nodes.
• `staggerDirection` ("forward" | "reverse" | "center-out", default "forward"): Traversal order when computing child stagger delays.