Skip to content

Code-first video & image, rendered natively on WebGPU.

feat(engine): effects on any layer, 2D scaleX/scaleY, 3D models follow 2D parents

okanasl93d60a4ead43
diff --git a/nodes/node-compositor/src/renderers/transform.test.ts b/nodes/node-compositor/src/renderers/transform.test.ts
index 59f5dc03..620347e3 100644
--- a/nodes/node-compositor/src/renderers/transform.test.ts
+++ b/nodes/node-compositor/src/renderers/transform.test.ts
@@ -3,6 +3,7 @@ import {
buildLayerMatrix,
type Matrix2D,
multiply,
+ resolveLayer2DPosition,
rotate,
scale,
transformPoint,
@@ -117,4 +118,189 @@ describe("buildLayerMatrix — anchor-aware pivot (review H2)", () => {
};
expectPoint(mapped, { x: 110, y: 70 });
});
+
+ it("scales independently on X and Y with non-uniform scaleX and scaleY", () => {
+ // box: x=10, y=20, width=200, height=100
+ // default center anchor: px = 100, py = 50. Screen pivot: (110, 70)
+ const m = buildLayerMatrix({
+ ...box,
+ rotation: 0,
+ scaleX: 2,
+ scaleY: 0.5,
+ });
+
+ // Center anchor stays invariant:
+ expectPoint(transformPoint(m, 100, 50), { x: 110, y: 70 });
+
+ // Width doubled around center: left edge x=0 maps to 110 - 100*2 = -90
+ // Height halved around center: top edge y=0 maps to 70 - 50*0.5 = 45
+ expectPoint(transformPoint(m, 0, 0), { x: -90, y: 45 });
+
+ // Right edge x=200 maps to 110 + 100*2 = 310
+ // Bottom edge y=100 maps to 70 + 50*0.5 = 95
+ expectPoint(transformPoint(m, 200, 100), { x: 310, y: 95 });
+ });
+
+ it("stretches bars upward with bottom anchor (anchorY: 1)", () => {
+ // Bar positioned at x=50, y=100 with width=20, height=200
+ const bar = { x: 50, y: 100, width: 20, height: 200 };
+ const m = buildLayerMatrix({
+ ...bar,
+ rotation: 0,
+ scaleX: 1,
+ scaleY: 2.5,
+ anchorX: 0.5,
+ anchorY: 1, // grounded at the bottom
+ });
+
+ // Bottom-center pivot (10, 200) -> screen (50 + 10, 100 + 200) = (60, 300)
+ expectPoint(transformPoint(m, 10, 200), { x: 60, y: 300 });
+
+ // Bottom edge is invariant
+ expectPoint(transformPoint(m, 0, 200), { x: 50, y: 300 });
+ expectPoint(transformPoint(m, 20, 200), { x: 70, y: 300 });
+
+ // Top edge (y=0) stretches upward by 2.5x: height goes from 200 to 500
+ // Screen y: 300 - 500 = -200
+ expectPoint(transformPoint(m, 10, 0), { x: 60, y: -200 });
+ });
+
+ it("combines uniform scale with scaleX and scaleY", () => {
+ const m = buildLayerMatrix({
+ ...box,
+ rotation: 0,
+ scale: 2,
+ scaleX: 1.5, // effective sx = 3
+ scaleY: 0.5, // effective sy = 1
+ anchorX: 0,
+ anchorY: 0, // top-left anchor
+ });
+
+ // Top-left corner invariant
+ expectPoint(transformPoint(m, 0, 0), { x: 10, y: 20 });
+ // x scales by 3: 200 * 3 = 600 -> screen 610
+ // y scales by 1: 100 * 1 = 100 -> screen 120
+ expectPoint(transformPoint(m, 200, 100), { x: 610, y: 120 });
+ });
+});
+
+describe("resolveLayer2DPosition (2D parent translation inheritance)", () => {
+ it("returns base/sampled position for top-level layers (no parent)", () => {
+ const pos = resolveLayer2DPosition({
+ rect: { x: 100, y: 200 },
+ baseX: 100,
+ baseY: 200,
+ sampledX: 100,
+ sampledY: 200,
+ parentRect: null,
+ parentMatrix: null,
+ });
+ expect(pos).toEqual({ x: 100, y: 200 });
+ });
+
+ it("applies keyframe delta for animated top-level layers", () => {
+ const pos = resolveLayer2DPosition({
+ rect: { x: 100, y: 200 },
+ baseX: 100,
+ baseY: 200,
+ sampledX: 140,
+ sampledY: 230,
+ parentRect: null,
+ parentMatrix: null,
+ });
+ expect(pos).toEqual({ x: 140, y: 230 });
+ });
+
+ it("inherits 2D parent translation inside a container", () => {
+ // Parent container at (300, 200)
+ const parentMatrix = translate(300, 200);
+ const parentRect = { x: 300, y: 200 };
+ // Child placed at (50, 40) within parent: layout rect is (350, 240)
+ const childRect = { x: 350, y: 240 };
+
+ const pos = resolveLayer2DPosition({
+ rect: childRect,
+ parentRect,
+ baseX: 50,
+ baseY: 40,
+ sampledX: 50,
+ sampledY: 40,
+ parentMatrix,
+ });
+ expect(pos).toEqual({ x: 350, y: 240 });
+ });
+
+ it("inherits cumulative translation through nested containers (components inside components)", () => {
+ // Grandparent at (100, 100), Parent at (200, 150) -> cumulative parentMatrix translates by (300, 250)
+ const parentMatrix = multiply(translate(100, 100), translate(200, 150));
+ const parentRect = { x: 300, y: 250 };
+ // Child placed at (25, 35) inside component -> layout rect (325, 285)
+ const childRect = { x: 325, y: 285 };
+
+ const pos = resolveLayer2DPosition({
+ rect: childRect,
+ parentRect,
+ baseX: 25,
+ baseY: 35,
+ sampledX: 25,
+ sampledY: 35,
+ parentMatrix,
+ });
+ expect(pos).toEqual({ x: 325, y: 285 });
+ });
+
+ it("combines parent container animation with child layer animation", () => {
+ // Parent animated to (350, 220)
+ const parentMatrix = translate(350, 220);
+ const parentRect = { x: 300, y: 200 };
+ // Child layout rect (350, 240), but animated locally from baseX=50 to sampledX=80
+ const childRect = { x: 350, y: 240 };
+
+ const pos = resolveLayer2DPosition({
+ rect: childRect,
+ parentRect,
+ baseX: 50,
+ baseY: 40,
+ sampledX: 80,
+ sampledY: 40,
+ parentMatrix,
+ });
+ // localX = (350 - 300) + (80 - 50) = 50 + 30 = 80
+ // worldX = 350 + 80 = 430
+ // worldY = 220 + 40 = 260
+ expect(pos).toEqual({ x: 430, y: 260 });
+ });
+
+ it("transforms child position when parent container has 2D rotation", () => {
+ // Parent container rotated 90 degrees around (100, 100)
+ // Screen space: 90 deg clockwise maps (dx, dy) -> (-dy, dx)
+ const parentMatrix = multiply(translate(100, 100), rotate(90));
+ const parentRect = { x: 100, y: 100 };
+ const childRect = { x: 150, y: 100 }; // local dx = 50, dy = 0
+
+ const pos = resolveLayer2DPosition({
+ rect: childRect,
+ parentRect,
+ baseX: 50,
+ baseY: 0,
+ sampledX: 50,
+ sampledY: 0,
+ parentMatrix,
+ });
+ // (50, 0) rotated 90 deg -> (0, 50). Translated by (100, 100) -> (100, 150)
+ closeTo(pos.x, 100);
+ closeTo(pos.y, 150);
+ });
+
+ it("falls back gracefully when rect is missing but parent translation exists", () => {
+ const parentMatrix = translate(400, 300);
+ const pos = resolveLayer2DPosition({
+ baseX: 20,
+ baseY: 30,
+ sampledX: 20,
+ sampledY: 30,
+ parentMatrix,
+ });
+ expect(pos).toEqual({ x: 420, y: 330 });
+ });
});
diff --git a/nodes/node-compositor/src/renderers/transform.ts b/nodes/node-compositor/src/renderers/transform.ts
index d63cf498..08875be4 100644
--- a/nodes/node-compositor/src/renderers/transform.ts
+++ b/nodes/node-compositor/src/renderers/transform.ts
@@ -79,7 +79,9 @@ export function buildLayerMatrix(params: {
width: number;
height: number;
rotation: number;
- scale: number;
+ scale?: number;
+ scaleX?: number;
+ scaleY?: number;
anchorX?: number;
anchorY?: number;
}): Matrix2D {
@@ -87,6 +89,9 @@ export function buildLayerMatrix(params: {
const ay = params.anchorY ?? 0.5;
const px = ax * params.width;
const py = ay * params.height;
+ const uniformScale = params.scale ?? 1;
+ const sx = (params.scaleX ?? 1) * uniformScale;
+ const sy = (params.scaleY ?? 1) * uniformScale;
return multiply(
translate(params.x, params.y),
@@ -94,8 +99,54 @@ export function buildLayerMatrix(params: {
translate(px, py),
multiply(
rotate(params.rotation),
- multiply(scale(params.scale), translate(-px, -py)),
+ multiply(scale(sx, sy), translate(-px, -py)),
),
),
);
}
+
+/**
+ * Resolves a layer's 2D world position on the canvas.
+ *
+ * For top-level layers, this is the layout position + animated translation delta.
+ * For children inside a 2D parent container, this inherits the parent container's
+ * 2D translation and transformation (parentMatrix).
+ */
+export function resolveLayer2DPosition(params: {
+ rect?: { x: number; y: number } | null;
+ parentRect?: { x: number; y: number } | null;
+ baseX?: number;
+ baseY?: number;
+ sampledX?: number;
+ sampledY?: number;
+ parentMatrix?: Matrix2D | DOMMatrix | null;
+}): { x: number; y: number } {
+ const baseX = params.baseX ?? 0;
+ const baseY = params.baseY ?? 0;
+ const sampledX = params.sampledX ?? baseX;
+ const sampledY = params.sampledY ?? baseY;
+
+ let localX = 0;
+ let localY = 0;
+ if (params.rect && params.parentRect) {
+ localX = params.rect.x - params.parentRect.x + (sampledX - baseX);
+ localY = params.rect.y - params.parentRect.y + (sampledY - baseY);
+ } else if (params.rect) {
+ localX = params.rect.x + (sampledX - baseX);
+ localY = params.rect.y + (sampledY - baseY);
+ } else {
+ localX = sampledX;
+ localY = sampledY;
+ }
+
+ const pm = params.parentMatrix;
+ if (!pm) {
+ return { x: localX, y: localY };
+ }
+
+ if ("isIdentity" in pm && pm.isIdentity) {
+ return { x: localX, y: localY };
+ }
+
+ return transformPoint(pm as Matrix2D, localX, localY);
+}
diff --git a/nodes/node-compositor/src/renderers/webgpu-renderer.ts b/nodes/node-compositor/src/renderers/webgpu-renderer.ts
index 7da42184..adcc57d2 100644
--- a/nodes/node-compositor/src/renderers/webgpu-renderer.ts
+++ b/nodes/node-compositor/src/renderers/webgpu-renderer.ts
@@ -16,9 +16,11 @@ import {
type VirtualMediaData,
} from "@framefields/core";
import {
+ type NodeRenderProps,
resolveFrameNumber,
solveHomography,
type WebGPUNodeRenderer,
+ type WebGPUNodeRendererArgs,
} from "@framefields/node-sdk";
import {
createFullscreenPipeline,
@@ -70,7 +72,11 @@ import {
import { compileTimeline, seekTimeline } from "../shared/compiler.js";
import type { CompositorOperation } from "../shared/config.js";
import { shouldPaintContainerBackground } from "./container-bg.js";
-import { buildLayerMatrix, toDOMMatrix } from "./transform.js";
+import {
+ buildLayerMatrix,
+ resolveLayer2DPosition,
+ toDOMMatrix,
+} from "./transform.js";
import { has3DTransform, type Quad2D, Transform3DMath } from "./transform3d.js";
// Layout depends on the document tree (whose `children` array keeps its
@@ -541,6 +547,119 @@ function computeContainerScissor(
};
}
+async function applyLayerEffects(
+ effects: unknown[],
+ sourceTex: GPUTexture,
+ width: number,
+ height: number,
+ ctx: RenderContextValue,
+ encoder: GPUCommandEncoder,
+ props: NodeRenderProps,
+ drawChild: WebGPUNodeRendererArgs["drawChild"],
+ excludes: GPUTexture[],
+ shiftedFrame: number,
+ compositionFrame: number,
+ fps: number,
+ isVideoMode: boolean,
+ layerId: string,
+): Promise<{ texture: GPUTexture; view: GPUTextureView }> {
+ const remainingEffects = effects.filter((e: unknown) => {
+ if (!e || typeof e !== "object") return false;
+ const op = (e as { op?: string })?.op;
+ const name = (e as { constructor?: { name?: string } })?.constructor?.name;
+ if (
+ op === "TemporalDeflicker" ||
+ op === "Deflicker" ||
+ op === "Relight3D" ||
+ name === "TemporalDeflicker" ||
+ name === "Relight3D"
+ ) {
+ return false;
+ }
+ return true;
+ });
+
+ if (remainingEffects.length === 0) {
+ return { texture: sourceTex, view: sourceTex.createView() };
+ }
+
+ let currentMedia: VirtualMediaData = {
+ metadata: { width, height },
+ operation: {
+ op: "TextureSource",
+ sourceTexture: sourceTex,
+ dataType: "Image",
+ } as unknown as VirtualMediaData["operation"],
+ children: [],
+ };
+
+ for (let i = 0; i < remainingEffects.length; i++) {
+ const eff = remainingEffects[i];
+ const effOp =
+ eff &&
+ typeof (eff as { toOperation?: unknown }).toOperation === "function"
+ ? (eff as { toOperation: () => Record<string, unknown> }).toOperation()
+ : (eff as Record<string, unknown>);
+ const opName = String(effOp.op ?? "effect");
+ currentMedia = {
+ metadata: { width, height },
+ operation: {
+ op: opName,
+ id: `${layerId}-${opName}_${i}`,
+ effect: eff,
+ ...effOp,
+ dataType: "Image",
+ } as unknown as VirtualMediaData["operation"],
+ children: [currentMedia],
+ };
+ }
+
+ const outTex = ctx.renderer.getTemporaryTexture(width, height, [
+ sourceTex,
+ ...excludes,
+ ]);
+ const outView = outTex.createView();
+
+ const clearPass = ctx.renderer.beginFrame(
+ encoder,
+ outView,
+ { r: 0, g: 0, b: 0, a: 0 },
+ width,
+ height,
+ "clear",
+ );
+ clearPass.end();
+
+ ctx.renderer.pushScissor({ x: 0, y: 0, width, height });
+ ctx.renderer.pushIdentity();
+ try {
+ await drawChild(
+ currentMedia,
+ {
+ ...props,
+ containerWidth: width,
+ containerHeight: height,
+ renderId: `${props.renderId}-${layerId}-fx`,
+ frame: shiftedFrame,
+ compositionFrame,
+ fps,
+ isVideoMode,
+ signals: props.signals,
+ excludeTextures: [sourceTex, outTex, ...excludes],
+ },
+ outView,
+ outTex,
+ width,
+ height,
+ );
+ } finally {
+ ctx.renderer.popTransform();
+ ctx.renderer.popScissor();
+ }
+
+ return { texture: outTex, view: outView };
+}
+
export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
const {
ctx,
@@ -1595,10 +1714,31 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
if (!model || model.meshes.length === 0) return;
- const posX = target?.x ?? lop.x ?? 0;
- const posY = target?.y ?? lop.y ?? 0;
+ const baseX = lop.x ?? 0;
+ const baseY = lop.y ?? 0;
+ const sampledX = target?.x ?? baseX;
+ const sampledY = target?.y ?? baseY;
const posZ = target?.z ?? lop.z ?? 0;
+ let posX = sampledX;
+ let posY = sampledY;
+
+ if (!parent3DMatrix) {
+ // Models are not laid out by x / y (they sit in flow), so their
+ // own x / y are parent-local: map them through the parent.
+ const pos = resolveLayer2DPosition({
+ rect: null,
+ parentRect: null,
+ baseX,
+ baseY,
+ sampledX,
+ sampledY,
+ parentMatrix,
+ });
+ posX = pos.x;
+ posY = pos.y;
+ }
+
const rotX = target?.rotateX ?? lop.rotateX ?? 0;
const rotY = target?.rotateY ?? lop.rotateY ?? 0;
const rotZ =
@@ -2024,6 +2164,8 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
}
const scale = target?.scale ?? lop.scale ?? 1;
+ const scaleX = target?.scaleX ?? lop.scaleX ?? 1;
+ const scaleY = target?.scaleY ?? lop.scaleY ?? 1;
const rotation = target?.rotation ?? lop.rotation ?? 0;
const layerOpacity =
(target?.opacity ?? lop.opacity ?? 1) * accumulatedOpacity;
@@ -2107,6 +2249,8 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
height: layerH,
rotation,
scale,
+ scaleX,
+ scaleY,
anchorX: isPathText ? (anchorX * rect.width) / layerW : anchorX,
anchorY: isPathText ? (anchorY * rect.height) / layerH : anchorY,
}),
@@ -2146,8 +2290,8 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
rotateXDeg: rotateX,
rotateYDeg: rotateY,
rotateZDeg: rotateZ !== 0 ? rotateZ : rotation,
- scaleX: scale,
- scaleY: scale,
+ scaleX: scaleX * scale,
+ scaleY: scaleY * scale,
perspectivePx: perspective,
originXRatio: perspectiveOriginX,
originYRatio: perspectiveOriginY,
@@ -2396,8 +2540,8 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
if (rxRad !== 0)
localM = Matrix4Math.multiply(localM, Matrix4Math.rotateX(rxRad));
- const sx = layerW * scale;
- const sy = layerH * scale;
+ const sx = layerW * scale * scaleX;
+ const sy = layerH * scale * scaleY;
const sz = target?.scaleZ ?? lop.scaleZ ?? 1;
localM = Matrix4Math.multiply(
localM,
@@ -2437,7 +2581,11 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
? (target?.rotateZ ?? lop.rotateZ ?? 0)
: rotation,
],
- scale: [scale, scale, target?.scaleZ ?? lop.scaleZ ?? 1],
+ scale: [
+ scale * scaleX,
+ scale * scaleY,
+ target?.scaleZ ?? lop.scaleZ ?? 1,
+ ],
anchor: [lop.anchorX ?? 0.5, lop.anchorY ?? 0.5],
borderRadius: br,
borderWidth: lop.borderWidth,
@@ -2669,6 +2817,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
// group-texture path below).
if (
(kind === "flex" || kind === "block") &&
+ (!Array.isArray(lop.effects) || lop.effects.length === 0) &&
clipRadius <= 0 &&
!shouldPaintContainerBackground(kind, lop.background) &&
layerOpacity === 1 &&
@@ -3023,6 +3172,27 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
activeGroupView = relitView;
}
+ if (Array.isArray(lop.effects) && lop.effects.length > 0) {
+ const postEffects = await applyLayerEffects(
+ lop.effects,
+ activeGroupTex,
+ targetW,
+ targetH,
+ ctx,
+ encoder,
+ props,
+ drawChild,
+ [activeTex, targetTexture, ...excludes],
+ shiftedFrame,
+ compositionFrame,
+ fps ?? 24,
+ isVideoMode,
+ lop.id ?? `container_${i}`,
+ );
+ activeGroupTex = postEffects.texture;
+ activeGroupView = postEffects.view;
+ }
+
// Always composite container groups using the composite shader
const compositeExcludes = [activeTex, targetTexture, ...excludes];
if (borderResult) compositeExcludes.push(borderResult.borderTex);
@@ -3522,10 +3692,14 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
// Effects work on the layer's pixels: glyphs held back for the 3D
// pass are drawn into its texture after all.
+ const hasEffects =
+ kind !== "media" &&
+ Array.isArray(lop.effects) &&
+ lop.effects.length > 0;
if (
glyphBatches &&
glyphBatches.length > 0 &&
- (deflickerOpts || relightOpts || shutterAngle > 0)
+ (deflickerOpts || relightOpts || shutterAngle > 0 || hasEffects)
) {
const glyphPass = ctx.renderer.beginFrame(
encoder,
@@ -3749,6 +3923,30 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
}
}
+ if (
+ kind !== "media" &&
+ Array.isArray(lop.effects) &&
+ lop.effects.length > 0
+ ) {
+ const postEffects = await applyLayerEffects(
+ lop.effects,
+ finalTex,
+ texW,
+ texH,
+ ctx,
+ encoder,
+ props,
+ drawChild,
+ [localTex, activeTex, targetTexture, ...excludes],
+ shiftedFrame,
+ compositionFrame,
+ fps ?? 24,
+ isVideoMode,
+ lop.id ?? `leaf_${i}`,
+ );
+ finalTex = postEffects.texture;
+ }
+
const borderExcludes = [
localTex,
finalTex,
@@ -3825,8 +4023,8 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
if (rxRad !== 0)
localM = Matrix4Math.multiply(localM, Matrix4Math.rotateX(rxRad));
- const sx = layerW * scale;
- const sy = layerH * scale;
+ const sx = layerW * scale * scaleX;
+ const sy = layerH * scale * scaleY;
const sz = target?.scaleZ ?? lop.scaleZ ?? 1;
localM = Matrix4Math.multiply(localM, Matrix4Math.scale(sx, sy, sz));
@@ -3860,7 +4058,11 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
? (target?.rotateZ ?? lop.rotateZ ?? 0)
: rotation,
],
- scale: [scale, scale, target?.scaleZ ?? lop.scaleZ ?? 1],
+ scale: [
+ scale * scaleX,
+ scale * scaleY,
+ target?.scaleZ ?? lop.scaleZ ?? 1,
+ ],
anchor: [lop.anchorX ?? 0.5, lop.anchorY ?? 0.5],
borderRadius: br,
borderWidth: lop.borderWidth,
diff --git a/packages/components/SPEC.md b/packages/components/SPEC.md
index a0ecb884..f6f61fc8 100644
--- a/packages/components/SPEC.md
+++ b/packages/components/SPEC.md
@@ -1052,9 +1052,7 @@ itself on); the name is live text, flat or extruded in 3D.
Extruded names (`depth > 0`) always swing in (rotate Y −70° → 0 on a spring) whatever the
style, and skip the letter glint: glyph animators don't reach meshes. Lighting is the
-scene's: add lights to the composition for shaded extrusions. 3D nodes ignore their 2D
-parents' offsets, so the name is placed in the root's parent coordinates (the root's own
-`x` / `y` added): give a 3D lockup a top-level, absolute placement.
+scene's: add lights to the composition for shaded extrusions.
**Cues:** `hit` (the mark lands), `revealed` (the lockup is complete), `glint`.
@@ -1810,9 +1808,8 @@ How they are built:
- **WordCycle** splits the line into before / slot / after; spaces at the slot are measured
(`"a a"` minus `"aa"`) rather than trusted to trailing whitespace. Words sit in a clip as
wide as the slot.
-- **Contract:** `BuildContext.requested` now carries `duration`, `at`, `x` and `y`
- (Backdrop keys its loops for the window; Waveform defaults `audioStart`; LogoReveal
- places 3D names).
+- **Contract:** `BuildContext.requested` now carries `duration` and `at` (Backdrop keys
+ its loops for the window; Waveform defaults `audioStart`).
- **Host:** `signal` (`frameArraySignal` itself: the `Signal` namespace would add ~7.6 KB
to every component), `grain`, `extrudedText` (`Layer3D.extrudedText`), and `.svg` files
in `media` (`Layer.svg`). Effects attach only to media layers, so `grain` is its own
@@ -1873,3 +1870,8 @@ Deviations from §7.17–7.21:
card behind is clipped straight across (a sliver of background shows there).
- Selection doesn't recolour selected glyphs; the highlight sits under the text when the
Selection is placed before the text layer.
+
+Follow-up engine fix: 3D models inside 2D containers ignored the containers' offsets (models
+are laid out in flow, so their layout rect never reflected their `x` / `y`). The compositor
+now maps a model's own `x` / `y` through its parent's matrix (`model-parent-offset.render.test.ts`),
+so LogoReveal's extruded names need no compensation and can sit anywhere in the tree.
diff --git a/packages/components/src/core/contract.ts b/packages/components/src/core/contract.ts
index c7887d75..a593772d 100644
--- a/packages/components/src/core/contract.ts
+++ b/packages/components/src/core/contract.ts
@@ -181,17 +181,12 @@ export interface BuildContext {
partId(part: string): string;
/** A seeded stream for `key`, stable across unrelated prop changes. */
rng(key: string | number): Rng;
- /**
- * What the user asked for: size, window, `at`, and the root's own `x` /
- * `y` (3D nodes ignore their 2D parents' offsets, so they add these).
- */
+ /** What the user asked for: size, window and `at`. */
requested: {
width?: number;
height?: number;
duration?: number;
at: number;
- x: number;
- y: number;
};
/** Frames the finished state holds (base `hold`, or the component's default). */
hold: number;
@@ -356,8 +351,6 @@ function assemble<S extends z.ZodRawShape, C extends Cues, E extends object>(
height: props.height,
duration: props.duration,
at: props.at ?? 0,
- x: props.x ?? 0,
- y: props.y ?? 0,
},
hold,
};
diff --git a/packages/components/src/logo-reveal/index.ts b/packages/components/src/logo-reveal/index.ts
index 9a8da4b4..20eae828 100644
--- a/packages/components/src/logo-reveal/index.ts
+++ b/packages/components/src/logo-reveal/index.ts
@@ -311,9 +311,8 @@ export const logoReveal = /* @__PURE__ */ defineComponent({
const name = host.extrudedText({
id: ctx.partId("name"),
text: props.name,
- // 3D nodes ignore 2D parents' offsets: place it in the root's parent.
- x: ctx.requested.x + nameAt.x + nameM.width / 2,
- y: ctx.requested.y + nameAt.y + nameM.height / 2,
+ x: nameAt.x + nameM.width / 2,
+ y: nameAt.y + nameM.height / 2,
depth: props.depth,
fontFamily,
fontSize: ns,
diff --git a/packages/compositions/src/compositions/canvas-composition.ts b/packages/compositions/src/compositions/canvas-composition.ts
index 54b41735..4748f2f5 100644
--- a/packages/compositions/src/compositions/canvas-composition.ts
+++ b/packages/compositions/src/compositions/canvas-composition.ts
@@ -257,6 +257,28 @@ export async function drawCompositionTree(
op.effect.notifyFrame(frameCtx);
}
+ if (op.op === "TextureSource") {
+ const sourceTexture = op.sourceTexture as GPUTexture | undefined;
+ if (sourceTexture) {
+ const pass = ctx.renderer.beginFrame(
+ encoder,
+ targetView,
+ { r: 0, g: 0, b: 0, a: 0 },
+ targetWidth,
+ targetHeight,
+ "load",
+ );
+ ctx.renderer.drawTexture(
+ pass,
+ sourceTexture,
+ { x: 0, y: 0, width: targetWidth, height: targetHeight },
+ { opacity: Number(op.opacity ?? 1) },
+ );
+ pass.end();
+ }
+ return;
+ }
+
const CustomRenderer = webgpuRegistry.get(op.op);
if (CustomRenderer) {
diff --git a/packages/compositions/src/program/animation.test.ts b/packages/compositions/src/program/animation.test.ts
index a2e7a4f3..1471561f 100644
--- a/packages/compositions/src/program/animation.test.ts
+++ b/packages/compositions/src/program/animation.test.ts
@@ -206,3 +206,251 @@ describe("LayerAnimation track merging", () => {
expect(enter.tracks[0].keyframes).toHaveLength(2);
});
});
+
+describe("LayerAnimation repeat & yoyo (looping)", () => {
+ it("repeats keyframes for a finite number of iterations", () => {
+ const anim = LayerAnimation.create().fromTo("opacity", 0, 1, {
+ start: 0,
+ end: 10,
+ repeat: 1, // 1 repeat after initial cycle = 2 total cycles (0..10 and 10..20)
+ });
+
+ expect(anim.tracks[0].repeat).toBe(1);
+
+ // Cycle 0: 0 -> 1
+ expect(evaluateAnimationAtFrame(anim, 0).opacity).toBe(0);
+ expect(evaluateAnimationAtFrame(anim, 5).opacity).toBe(0.5);
+ expect(evaluateAnimationAtFrame(anim, 10).opacity).toBe(0); // starts cycle 1
+
+ // Cycle 1: 0 -> 1
+ expect(evaluateAnimationAtFrame(anim, 15).opacity).toBe(0.5);
+
+ // Completed: rests at final value (1)
+ expect(evaluateAnimationAtFrame(anim, 20).opacity).toBe(1);
+ expect(evaluateAnimationAtFrame(anim, 50).opacity).toBe(1);
+ });
+
+ it("yoyos back and forth for finite repeats", () => {
+ const anim = LayerAnimation.create().fromTo("y", 0, 100, {
+ start: 0,
+ end: 10,
+ repeat: 1, // cycle 0 (forward), cycle 1 (reverse) -> rests at 0
+ yoyo: true,
+ });
+
+ expect(anim.tracks[0].yoyo).toBe(true);
+
+ // Cycle 0 (forward): 0 -> 100
+ expect(evaluateAnimationAtFrame(anim, 0).y).toBe(0);
+ expect(evaluateAnimationAtFrame(anim, 5).y).toBe(50);
+ expect(evaluateAnimationAtFrame(anim, 10).y).toBe(100);
+
+ // Cycle 1 (reverse): 100 -> 0
+ expect(evaluateAnimationAtFrame(anim, 15).y).toBe(50);
+
+ // Completed: rests at 0 because repeat was odd (cycle 1 was in reverse)
+ expect(evaluateAnimationAtFrame(anim, 20).y).toBe(0);
+ expect(evaluateAnimationAtFrame(anim, 30).y).toBe(0);
+ });
+
+ it("rests at end value when finite yoyo repeat is even", () => {
+ const anim = LayerAnimation.create().fromTo("scale", 1, 2, {
+ start: 0,
+ end: 10,
+ repeat: 2, // cycle 0 (fwd), cycle 1 (rev), cycle 2 (fwd) -> rests at 2
+ yoyo: true,
+ });
+
+ // Cycle 2 (forward) ends at frame 30
+ expect(evaluateAnimationAtFrame(anim, 25).scale).toBe(1.5);
+ expect(evaluateAnimationAtFrame(anim, 30).scale).toBe(2);
+ expect(evaluateAnimationAtFrame(anim, 50).scale).toBe(2);
+ });
+
+ it("loops infinitely with repeat: -1 and .loop({ yoyo: true })", () => {
+ const anim = LayerAnimation.create()
+ .fromTo("x", 0, 100, { start: 0, end: 10 })
+ .loop({ yoyo: true });
+
+ expect(anim.tracks[0].repeat).toBe(-1);
+ expect(anim.tracks[0].yoyo).toBe(true);
+
+ // Cycle 0 (0..10): forward
+ expect(evaluateAnimationAtFrame(anim, 0).x).toBe(0);
+ expect(evaluateAnimationAtFrame(anim, 5).x).toBe(50);
+ expect(evaluateAnimationAtFrame(anim, 10).x).toBe(100);
+
+ // Cycle 1 (10..20): reverse
+ expect(evaluateAnimationAtFrame(anim, 15).x).toBe(50);
+ expect(evaluateAnimationAtFrame(anim, 20).x).toBe(0);
+
+ // Cycle 2 (20..30): forward
+ expect(evaluateAnimationAtFrame(anim, 25).x).toBe(50);
+ expect(evaluateAnimationAtFrame(anim, 30).x).toBe(100);
+
+ // Far into the future (frame 105: cycle 10 forward at 50%)
+ expect(evaluateAnimationAtFrame(anim, 105).x).toBe(50);
+ // Frame 115: cycle 11 reverse at 50%
+ expect(evaluateAnimationAtFrame(anim, 115).x).toBe(50);
+ });
+
+ it("applies repeat and yoyo via fluent methods before or after track addition", () => {
+ // Before tracks
+ const animBefore = LayerAnimation.create()
+ .repeat(-1)
+ .yoyo(true)
+ .fromTo("opacity", 0, 1, { start: 0, end: 10 });
+ expect(animBefore.tracks[0].repeat).toBe(-1);
+ expect(animBefore.tracks[0].yoyo).toBe(true);
+
+ // Prop-targeted repeat
+ const animProp = LayerAnimation.create()
+ .fromTo("opacity", 0, 1, { start: 0, end: 10 })
+ .fromTo("scale", 1, 2, { start: 0, end: 10 })
+ .repeat(3, "opacity");
+ expect(animProp.tracks[0].repeat).toBe(3);
+ expect(animProp.tracks[1].repeat).toBeUndefined();
+ });
+
+ it("supports repeat and yoyo in LayerAnimation.keys()", () => {
+ const anim = LayerAnimation.keys(
+ "y",
+ [
+ [0, 10],
+ [10, 50],
+ ],
+ { repeat: -1, yoyo: true },
+ );
+
+ expect(anim.tracks[0].repeat).toBe(-1);
+ expect(anim.tracks[0].yoyo).toBe(true);
+
+ expect(evaluateAnimationAtFrame(anim, 5).y).toBe(30);
+ expect(evaluateAnimationAtFrame(anim, 15).y).toBe(30);
+ });
+
+ it("respects delayed startFrame with repeat and yoyo", () => {
+ const anim = LayerAnimation.create().fromTo("x", 100, 200, {
+ start: 20,
+ end: 40,
+ repeat: -1,
+ yoyo: true,
+ });
+
+ // Before startFrame (frame 0..20 holds fromValue)
+ expect(evaluateAnimationAtFrame(anim, 0).x).toBe(100);
+ expect(evaluateAnimationAtFrame(anim, 10).x).toBe(100);
+ expect(evaluateAnimationAtFrame(anim, 20).x).toBe(100);
+
+ // Cycle 0 (20..40): forward
+ expect(evaluateAnimationAtFrame(anim, 30).x).toBe(150);
+ expect(evaluateAnimationAtFrame(anim, 40).x).toBe(200);
+
+ // Cycle 1 (40..60): reverse
+ expect(evaluateAnimationAtFrame(anim, 50).x).toBe(150);
+ expect(evaluateAnimationAtFrame(anim, 60).x).toBe(100);
+ });
+
+ it("handles multi-keyframe tracks during reverse yoyo playback", () => {
+ const anim = LayerAnimation.keys(
+ "blur",
+ [
+ [0, 0],
+ [10, 50],
+ [20, 100],
+ ],
+ { repeat: 1, yoyo: true },
+ );
+
+ // Cycle 0: forward
+ expect(evaluateAnimationAtFrame(anim, 5).blur).toBe(25);
+ expect(evaluateAnimationAtFrame(anim, 10).blur).toBe(50);
+ expect(evaluateAnimationAtFrame(anim, 15).blur).toBe(75);
+ expect(evaluateAnimationAtFrame(anim, 20).blur).toBe(100);
+
+ // Cycle 1: reverse (duration 20 frames, from 20 to 40)
+ // At frame 25: 5 frames in reverse -> maps to frame 15 (75)
+ expect(evaluateAnimationAtFrame(anim, 25).blur).toBe(75);
+ // At frame 30: 10 frames in reverse -> maps to frame 10 (50)
+ expect(evaluateAnimationAtFrame(anim, 30).blur).toBe(50);
+ // At frame 35: 15 frames in reverse -> maps to frame 5 (25)
+ expect(evaluateAnimationAtFrame(anim, 35).blur).toBe(25);
+ // At frame 40: completed -> rests at 0
+ expect(evaluateAnimationAtFrame(anim, 40).blur).toBe(0);
+ });
+
+ it("supports custom cycle durationFrames with holding period", () => {
+ const anim = LayerAnimation.keys(
+ "scale",
+ [
+ [0, 1],
+ [10, 2],
+ ],
+ { durationFrames: 15, repeat: -1 }, // active 0..10, holds 10..15, then repeats
+ );
+
+ // Forward transition
+ expect(evaluateAnimationAtFrame(anim, 0).scale).toBe(1);
+ expect(evaluateAnimationAtFrame(anim, 5).scale).toBe(1.5);
+ expect(evaluateAnimationAtFrame(anim, 10).scale).toBe(2);
+
+ // Holding period (10..15)
+ expect(evaluateAnimationAtFrame(anim, 12).scale).toBe(2);
+ expect(evaluateAnimationAtFrame(anim, 14).scale).toBe(2);
+
+ // Next cycle starts at frame 15
+ expect(evaluateAnimationAtFrame(anim, 15).scale).toBe(1);
+ expect(evaluateAnimationAtFrame(anim, 20).scale).toBe(1.5);
+ });
+});
+
+describe("LayerAnimation scaleX & scaleY (single-axis stretching)", () => {
+ it("animates scaleX and scaleY via fluent methods and fromTo", () => {
+ const anim = LayerAnimation.create()
+ .scaleX(1, 3, { start: 0, end: 10 })
+ .scaleY(1, 0.5, { start: 0, end: 10 });
+
+ expect(anim.tracks).toHaveLength(2);
+ expect(anim.tracks[0].prop).toBe("scaleX");
+ expect(anim.tracks[1].prop).toBe("scaleY");
+
+ const f0 = evaluateAnimationAtFrame(anim, 0);
+ expect(f0.scaleX).toBe(1);
+ expect(f0.scaleY).toBe(1);
+
+ const f5 = evaluateAnimationAtFrame(anim, 5);
+ expect(f5.scaleX).toBe(2);
+ expect(f5.scaleY).toBe(0.75);
+
+ const f10 = evaluateAnimationAtFrame(anim, 10);
+ expect(f10.scaleX).toBe(3);
+ expect(f10.scaleY).toBe(0.5);
+ });
+
+ it("supports static LayerAnimation.scaleX and LayerAnimation.scaleY factories", () => {
+ const animX = LayerAnimation.scaleX(0.2, 1.8, { start: 5, end: 15 });
+ expect(animX.tracks[0].prop).toBe("scaleX");
+ expect(evaluateAnimationAtFrame(animX, 5).scaleX).toBe(0.2);
+ expect(evaluateAnimationAtFrame(animX, 15).scaleX).toBe(1.8);
+
+ const animY = LayerAnimation.scaleY(0, 2.5, { start: 0, end: 20 });
+ expect(animY.tracks[0].prop).toBe("scaleY");
+ expect(evaluateAnimationAtFrame(animY, 10).scaleY).toBe(1.25);
+ });
+
+ it("supports loop and yoyo on single-axis scale tracks (e.g. audio bar equalizer bounce)", () => {
+ const anim = LayerAnimation.create()
+ .scaleY(0.1, 1.0, { start: 0, end: 6 })
+ .loop({ yoyo: true });
+
+ expect(anim.tracks[0].repeat).toBe(-1);
+ expect(anim.tracks[0].yoyo).toBe(true);
+
+ // Cycle 0 forward: 0.1 -> 1.0
+ expect(evaluateAnimationAtFrame(anim, 0).scaleY).toBe(0.1);
+ expect(evaluateAnimationAtFrame(anim, 6).scaleY).toBe(1.0);
+
+ // Cycle 1 reverse: 1.0 -> 0.1
+ expect(evaluateAnimationAtFrame(anim, 12).scaleY).toBe(0.1);
+ });
+});
diff --git a/packages/compositions/src/program/animation.ts b/packages/compositions/src/program/animation.ts
index 899ef191..72e0ad3d 100644
--- a/packages/compositions/src/program/animation.ts
+++ b/packages/compositions/src/program/animation.ts
@@ -26,6 +26,14 @@ export interface FromToOptions {
toFrame?: number;
durationFrames?: number;
ease?: string | EaseRef;
+ repeat?: number;
+ yoyo?: boolean;
+}
+
+export interface TrackKeyOptions {
+ repeat?: number;
+ yoyo?: boolean;
+ durationFrames?: number;
}
export interface Tilt3DOptions {
@@ -280,6 +288,8 @@ export class LayerAnimation<TProp extends AnimatableProp = AnimatableProp>
public tracks: AnimationTrack<TProp>[] = [];
/** Hold each value for this many frames (see {@link LayerAnimation.stepped}). */
public frameStep?: number;
+ public defaultRepeat?: number;
+ public defaultYoyo?: boolean;
constructor(tracks: AnimationTrack<TProp>[] = []) {
this.tracks = [...tracks];
@@ -291,12 +301,6 @@ export class LayerAnimation<TProp extends AnimatableProp = AnimatableProp>
return new LayerAnimation<P>();
}
- /**
- * Stepped timing for the whole layer: every animated value is held for
- * `frames` frames ("on twos" = 2, "on threes" = 3), the choppy, hand-made
- * look of stop motion and cel animation. Applies to all of the layer's
- * tracks, including ones added by other `.animate()` calls.
- */
public static stepped<P extends AnimatableProp = AnimatableProp>(
frames = 2,
): LayerAnimation<P> {
@@ -322,8 +326,9 @@ export class LayerAnimation<TProp extends AnimatableProp = AnimatableProp>
public static keys<P extends AnimatableProp = AnimatableProp>(
prop: P,
keyframes: readonly KeyframeTuple[],
+ options?: TrackKeyOptions,
): LayerAnimation<P> {
- return new LayerAnimation<P>().keys(prop, keyframes);
+ return new LayerAnimation<P>().keys(prop, keyframes, options);
}
public static signal<P extends AnimatableProp = AnimatableProp>(
@@ -449,11 +454,75 @@ export class LayerAnimation<TProp extends AnimatableProp = AnimatableProp>
return new LayerAnimation().fromTo("rotation", fromAngle, toAngle, options);
}
+ public static scale(
+ fromScale: number,
+ toScale: number,
+ options: FromToOptions = {},
+ ): LayerAnimation {
+ return new LayerAnimation().fromTo("scale", fromScale, toScale, options);
+ }
+
+ public static scaleX(
+ fromScale: number,
+ toScale: number,
+ options: FromToOptions = {},
+ ): LayerAnimation {
+ return new LayerAnimation().fromTo("scaleX", fromScale, toScale, options);
+ }
+
+ public static scaleY(
+ fromScale: number,
+ toScale: number,
+ options: FromToOptions = {},
+ ): LayerAnimation {
+ return new LayerAnimation().fromTo("scaleY", fromScale, toScale, options);
+ }
+
public addTrack(track: AnimationTrack<TProp>): this {
this.tracks.push(track);
return this;
}
+ /**
+ * Configures repeat count on all tracks, or on a specific prop's track:
+ * - `-1`: loops indefinitely.
+ * - `N`: repeats N times after the initial iteration (total N + 1 iterations).
+ */
+ public repeat(count = -1, prop?: AnimatableProp): this {
+ this.defaultRepeat = count;
+ for (const track of this.tracks) {
+ if (!prop || track.prop === prop) {
+ track.repeat = count;
+ }
+ }
+ return this;
+ }
+
+ /**
+ * Enables or disables yoyo (alternate playback direction on each repeat iteration).
+ */
+ public yoyo(enable = true, prop?: AnimatableProp): this {
+ this.defaultYoyo = enable;
+ for (const track of this.tracks) {
+ if (!prop || track.prop === prop) {
+ track.yoyo = enable;
+ }
+ }
+ return this;
+ }
+
+ /**
+ * Shorthand to loop keyframed animation continuously (infinite repeat).
+ * If `options.yoyo` is true, oscillates back and forth.
+ */
+ public loop(options: { yoyo?: boolean } = {}, prop?: AnimatableProp): this {
+ this.repeat(-1, prop);
+ if (options.yoyo) {
+ this.yoyo(true, prop);
+ }
+ return this;
+ }
+
/**
* Creates a keyframed track animating from fromValue to toValue.
*/
@@ -481,11 +550,18 @@ export class LayerAnimation<TProp extends AnimatableProp = AnimatableProp>
id: `${prop}_fromTo_${this.tracks.length}`,
prop: prop as TProp,
keyframes: [],
+ ...(this.defaultRepeat !== undefined && { repeat: this.defaultRepeat }),
+ ...(this.defaultYoyo !== undefined && { yoyo: this.defaultYoyo }),
};
this.tracks.push(newTrack);
track = newTrack;
}
+ if (options.repeat !== undefined) track.repeat = options.repeat;
+ if (options.yoyo !== undefined) track.yoyo = options.yoyo;
+ if (options.durationFrames !== undefined)
+ track.durationFrames = options.durationFrames;
+
const id = track.id;
// If this is the initial keyframe on the track and start > 0, hold fromValue from frame 0
@@ -539,6 +615,8 @@ export class LayerAnimation<TProp extends AnimatableProp = AnimatableProp>
id: `${prop}_track_${this.tracks.length}`,
prop: prop as TProp,
keyframes: [],
+ ...(this.defaultRepeat !== undefined && { repeat: this.defaultRepeat }),
+ ...(this.defaultYoyo !== undefined && { yoyo: this.defaultYoyo }),
};
this.tracks.push(newTrack);
track = newTrack;
@@ -566,10 +644,25 @@ export class LayerAnimation<TProp extends AnimatableProp = AnimatableProp>
* `.keys("scale", [[0, 0], [12, 1.1, "back.out"], [20, 1]])`.
* Frames are rounded to whole frames, so beat math can be passed straight in.
*/
- public keys(prop: AnimatableProp, keyframes: readonly KeyframeTuple[]): this {
+ public keys(
+ prop: AnimatableProp,
+ keyframes: readonly KeyframeTuple[],
+ options?: TrackKeyOptions,
+ ): this {
for (const [frame, value, ease] of keyframes) {
this.keyframe(prop, Math.round(frame), value, ease);
}
+ if (options) {
+ const track = this.tracks.find(
+ (t) => t.prop === prop && (!t.source || t.source.type === "keyframe"),
+ );
+ if (track) {
+ if (options.repeat !== undefined) track.repeat = options.repeat;
+ if (options.yoyo !== undefined) track.yoyo = options.yoyo;
+ if (options.durationFrames !== undefined)
+ track.durationFrames = options.durationFrames;
+ }
+ }
return this;
}
@@ -753,6 +846,39 @@ export class LayerAnimation<TProp extends AnimatableProp = AnimatableProp>
return this.fromTo("rotateZ", fromAngle, toAngle, options);
}
+ /**
+ * Animate scale along the X axis.
+ */
+ public scaleX(
+ fromScale: number,
+ toScale: number,
+ options: FromToOptions = {},
+ ): this {
+ return this.fromTo("scaleX", fromScale, toScale, options);
+ }
+
+ /**
+ * Animate scale along the Y axis.
+ */
+ public scaleY(
+ fromScale: number,
+ toScale: number,
+ options: FromToOptions = {},
+ ): this {
+ return this.fromTo("scaleY", fromScale, toScale, options);
+ }
+
+ /**
+ * Animate uniform scale.
+ */
+ public scale(
+ fromScale: number,
+ toScale: number,
+ options: FromToOptions = {},
+ ): this {
+ return this.fromTo("scale", fromScale, toScale, options);
+ }
+
/**
* Animate perspective camera distance in pixels.
*/
diff --git a/packages/compositions/src/program/evaluator.ts b/packages/compositions/src/program/evaluator.ts
index 9f2ae339..c62ccecd 100644
--- a/packages/compositions/src/program/evaluator.ts
+++ b/packages/compositions/src/program/evaluator.ts
@@ -635,8 +635,51 @@ const COLOR_PROPS = new Set([
"color",
]);
+function computeRepeatFrame(
+ track: AnimationTrack,
+ localFrame: number,
+ startFrame: number,
+ lastFrame: number,
+): { frame: number } | { completedValue: number | boolean | string } {
+ const repeat = track.repeat ?? 0;
+ const cycleSpan = lastFrame - startFrame;
+ const cycleDuration =
+ track.durationFrames !== undefined && track.durationFrames > 0
+ ? track.durationFrames
+ : cycleSpan;
+
+ if (repeat === 0 || cycleDuration <= 0) {
+ if (localFrame >= lastFrame) {
+ const kfs = track.keyframes ?? [];
+ return { completedValue: kfs[kfs.length - 1].value };
+ }
+ return { frame: localFrame };
+ }
+
+ const delta = localFrame - startFrame;
+ const cycleIndex = Math.floor(delta / cycleDuration);
+
+ if (repeat > 0 && cycleIndex >= 1 + repeat) {
+ const isFinalReverse = Boolean(track.yoyo) && repeat % 2 === 1;
+ const kfs = track.keyframes ?? [];
+ const finalVal = isFinalReverse ? kfs[0].value : kfs[kfs.length - 1].value;
+ return { completedValue: finalVal };
+ }
+
+ const cycleOffset = delta - cycleIndex * cycleDuration;
+ const isReverse = Boolean(track.yoyo) && cycleIndex % 2 === 1;
+
+ if (isReverse) {
+ const f = cycleOffset >= cycleSpan ? startFrame : lastFrame - cycleOffset;
+ return { frame: f };
+ }
+
+ const f = cycleOffset >= cycleSpan ? lastFrame : startFrame + cycleOffset;
+ return { frame: f };
+}
+
/**
- * Standard keyframe track evaluation.
+ * Standard keyframe track evaluation with loop (repeat/yoyo) support.
*/
export function evaluateKeyframes(
track: AnimationTrack,
@@ -651,20 +694,31 @@ export function evaluateKeyframes(
if (keyframes.length === 0) return 0;
if (keyframes.length === 1) return keyframes[0].value;
- if (localFrame <= keyframes[0].frame) {
+ const startFrame = keyframes[0].frame;
+ if (localFrame <= startFrame) {
return keyframes[0].value;
}
- if (localFrame >= keyframes[keyframes.length - 1].frame) {
- return keyframes[keyframes.length - 1].value;
+
+ const lastFrame = keyframes[keyframes.length - 1].frame;
+ const repeatResolution = computeRepeatFrame(
+ track,
+ localFrame,
+ startFrame,
+ lastFrame,
+ );
+ if ("completedValue" in repeatResolution) {
+ return repeatResolution.completedValue;
}
+ const evalFrame = repeatResolution.frame;
+
for (let i = 0; i < keyframes.length - 1; i++) {
const kf0 = keyframes[i];
const kf1 = keyframes[i + 1];
- if (localFrame >= kf0.frame && localFrame <= kf1.frame) {
+ if (evalFrame >= kf0.frame && evalFrame <= kf1.frame) {
const delta = kf1.frame - kf0.frame;
- const linear = delta > 0 ? (localFrame - kf0.frame) / delta : 0;
+ const linear = delta > 0 ? (evalFrame - kf0.frame) / delta : 0;
const t = ease ? ease(kf1.ease ?? kf0.ease, delta, linear) : linear;
if (typeof kf0.value === "boolean") {
diff --git a/packages/compositions/src/program/lint.ts b/packages/compositions/src/program/lint.ts
index c09fcacf..37716b3d 100644
--- a/packages/compositions/src/program/lint.ts
+++ b/packages/compositions/src/program/lint.ts
@@ -198,6 +198,8 @@ export function lintComposition(
"translateX",
"translateY",
"scale",
+ "scaleX",
+ "scaleY",
"rotation",
])
) {
diff --git a/packages/compositions/src/program/schema.ts b/packages/compositions/src/program/schema.ts
index e9a83a2c..498e744c 100644
--- a/packages/compositions/src/program/schema.ts
+++ b/packages/compositions/src/program/schema.ts
@@ -704,6 +704,8 @@ const BaseNodeFields = {
effects: z.array(EffectSpecSchema).optional(),
rotation: z.number().default(0),
scale: z.number().min(0).default(1),
+ scaleX: z.number().default(1),
+ scaleY: z.number().default(1),
/** Transform pivot, 0–1 fraction of the node box (0.5 = center). */
anchorX: z.number().min(0).max(1).default(0.5),
anchorY: z.number().min(0).max(1).default(0.5),
@@ -809,6 +811,8 @@ export interface CompositionNodeBase {
blendMode?: string;
rotation?: number;
scale?: number;
+ scaleX?: number;
+ scaleY?: number;
anchorX?: number;
anchorY?: number;
rotateX?: number;
diff --git a/packages/compositions/src/program/to-virtual-media.test.ts b/packages/compositions/src/program/to-virtual-media.test.ts
index 6a8fb5a6..1a3ebd26 100644
--- a/packages/compositions/src/program/to-virtual-media.test.ts
+++ b/packages/compositions/src/program/to-virtual-media.test.ts
@@ -277,4 +277,48 @@ describe("compositorToProgram", () => {
expect((layer2.children![0].operation as any).dataType).toBe("Lottie");
expect((layer2.children![0].operation as any).url).toBe("animation.lottie");
});
+
+ it("preserves effects on non-media layers as CompositorLayer lop.effects", () => {
+ const docWithEffects = {
+ width: 1920,
+ height: 1080,
+ fps: 30,
+ mode: "Video" as const,
+ layout: [
+ {
+ id: "box-fx",
+ kind: "box" as const,
+ width: 200,
+ height: 200,
+ background: "#ff0000",
+ effects: [{ op: "Blur", radius: 10 }],
+ },
+ {
+ id: "text-fx",
+ kind: "text" as const,
+ text: "Hello World",
+ fontSize: 48,
+ effects: [{ op: "FilmGrain", strength: 0.1 }],
+ },
+ ],
+ };
+
+ const vm = compositorToProgram(docWithEffects, {
+ isVideoMode: true,
+ fps: 30,
+ });
+ expect(vm.children).toHaveLength(2);
+
+ const boxLayer = vm.children?.[0];
+ const boxOp = boxLayer?.operation as Record<string, unknown> | undefined;
+ expect(boxOp?.op).toBe("CompositorLayer");
+ expect(boxOp?.kind).toBe("box");
+ expect(boxOp?.effects).toEqual([{ op: "Blur", radius: 10 }]);
+
+ const textLayer = vm.children?.[1];
+ const textOp = textLayer?.operation as Record<string, unknown> | undefined;
+ expect(textOp?.op).toBe("CompositorLayer");
+ expect(textOp?.kind).toBe("text");
+ expect(textOp?.effects).toEqual([{ op: "FilmGrain", strength: 0.1 }]);
+ });
});
diff --git a/packages/compositions/src/utils/layout/resolve-layout.ts b/packages/compositions/src/utils/layout/resolve-layout.ts
index 10410639..6b235974 100644
--- a/packages/compositions/src/utils/layout/resolve-layout.ts
+++ b/packages/compositions/src/utils/layout/resolve-layout.ts
@@ -24,7 +24,6 @@
import type { Yoga, Node as YogaNode } from "yoga-layout/load";
export type { Yoga };
-import { assertNever } from "@framefields/core";
import { loadYoga } from "yoga-layout/load";
import type {
CompositionNodeBase,
@@ -180,9 +179,8 @@ function dirOf(node: LayoutNode): "row" | "column" | null {
case "camera":
case "light":
case "model3d":
- return null;
default:
- return assertNever(node);
+ return null;
}
}
diff --git a/packages/framefields/src/effect-layers.render.test.ts b/packages/framefields/src/effect-layers.render.test.ts
new file mode 100644
index 00000000..ae4d15e1
--- /dev/null
+++ b/packages/framefields/src/effect-layers.render.test.ts
@@ -0,0 +1,257 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import {
+ Blur,
+ Composition,
+ FontManager,
+ Layer,
+ Pixelate,
+ Signal,
+} from "./index.js";
+import { computeMse, decodePngPixels, getPixel } from "./test-utils/pixels.js";
+
+const W = 200;
+const H = 200;
+
+function createStage(fps = 30) {
+ return new Composition({
+ width: W,
+ height: H,
+ fps,
+ durationFrames: 30,
+ backgroundColor: "#000000",
+ });
+}
+
+describe("Effects on Non-Media Layers", () => {
+ beforeAll(async () => {
+ await FontManager.register("assets/fonts/Inter.ttf");
+ });
+
+ it("applies post-processing effect (Blur) directly to Layer.box", async () => {
+ // Stage without effect: a 40x40 white square at center (x: 80, y: 80)
+ const plainComp = createStage();
+ plainComp.add(
+ Layer.box({
+ x: 80,
+ y: 80,
+ width: 40,
+ height: 40,
+ background: "#ffffff",
+ }),
+ );
+ const plainImg = await decodePngPixels(
+ await plainComp.renderFrame({ frame: 0 }),
+ );
+ // Outside the box (x: 70, y: 100), the plain background is pure black
+ const outsidePlain = getPixel(plainImg, 70, 100);
+ expect(outsidePlain.r).toBe(0);
+ expect(outsidePlain.g).toBe(0);
+ expect(outsidePlain.b).toBe(0);
+
+ // Stage with Blur effect directly on the Layer.box
+ const blurComp = createStage();
+ blurComp.add(
+ Layer.box({
+ x: 80,
+ y: 80,
+ width: 40,
+ height: 40,
+ background: "#ffffff",
+ }).withEffect(new Blur({ strength: 35 })),
+ );
+ const blurImg = await decodePngPixels(
+ await blurComp.renderFrame({ frame: 0 }),
+ );
+ // Inside the blurred box at center, it's lit
+ const centerBlur = getPixel(blurImg, 100, 100);
+ expect(centerBlur.r).toBeGreaterThan(40);
+
+ // With blur, white spreads outside the 80..120 bounds
+ const edgeIn = getPixel(blurImg, 80, 100);
+ expect(edgeIn.r).toBeGreaterThan(10);
+
+ // The images must differ significantly
+ const mse = computeMse(plainImg.pixels, blurImg.pixels);
+ expect(mse).toBeGreaterThan(50);
+ });
+
+ it("applies post-processing effect (Blur) directly to Layer.shape", async () => {
+ // Plain shape: filled white circle at center (radius 25)
+ const plainComp = createStage();
+ plainComp.add(
+ Layer.shape("circle", {
+ x: 75,
+ y: 75,
+ width: 50,
+ height: 50,
+ fillColor: "#ffffff",
+ }),
+ );
+ const plainImg = await decodePngPixels(
+ await plainComp.renderFrame({ frame: 0 }),
+ );
+ // Plain circle center is fully white
+ expect(getPixel(plainImg, 100, 100).r).toBe(255);
+
+ // Shape with Blur effect attached
+ const blurComp = createStage();
+ blurComp.add(
+ Layer.shape("circle", {
+ x: 75,
+ y: 75,
+ width: 50,
+ height: 50,
+ fillColor: "#ffffff",
+ }).withEffect(new Blur({ strength: 35 })),
+ );
+ const blurImg = await decodePngPixels(
+ await blurComp.renderFrame({ frame: 0 }),
+ );
+
+ // With blur, center intensity is softened and edges blurred
+ const centerBlur = getPixel(blurImg, 100, 100);
+ expect(centerBlur.r).toBeLessThan(255);
+ expect(centerBlur.r).toBeGreaterThan(40);
+
+ const mse = computeMse(plainImg.pixels, blurImg.pixels);
+ expect(mse).toBeGreaterThan(50);
+ });
+
+ it("applies post-processing effect directly to Layer.text", async () => {
+ const plainComp = createStage();
+ plainComp.add(
+ Layer.text("EFFECT", {
+ x: 20,
+ y: 70,
+ fontSize: 36,
+ fill: "#ffffff",
+ fontFamily: "Inter",
+ }),
+ );
+ const plainImg = await decodePngPixels(
+ await plainComp.renderFrame({ frame: 0 }),
+ );
+
+ const blurComp = createStage();
+ blurComp.add(
+ Layer.text("EFFECT", {
+ x: 20,
+ y: 70,
+ fontSize: 36,
+ fill: "#ffffff",
+ fontFamily: "Inter",
+ }).withEffect(new Blur({ strength: 20 })),
+ );
+ const blurImg = await decodePngPixels(
+ await blurComp.renderFrame({ frame: 0 }),
+ );
+
+ const mse = computeMse(plainImg.pixels, blurImg.pixels);
+ expect(mse).toBeGreaterThan(50);
+ });
+
+ it("applies effect to container layers (Layer.box / Layer.flex with children)", async () => {
+ // Container with background and two colored boxes inside
+ const makeComp = (effect?: Blur) => {
+ const comp = createStage();
+ const container = Layer.box({
+ x: 30,
+ y: 30,
+ width: 140,
+ height: 140,
+ background: "#111111",
+ children: [
+ Layer.box({
+ x: 10,
+ y: 10,
+ width: 40,
+ height: 40,
+ background: "#ff0000",
+ }),
+ Layer.box({
+ x: 80,
+ y: 80,
+ width: 40,
+ height: 40,
+ background: "#0000ff",
+ }),
+ ],
+ });
+ if (effect) {
+ container.withEffect(effect);
+ }
+ comp.add(container);
+ return comp;
+ };
+
+ const plainImg = await decodePngPixels(
+ await makeComp().renderFrame({ frame: 0 }),
+ );
+ const blurImg = await decodePngPixels(
+ await makeComp(new Blur({ strength: 30 })).renderFrame({ frame: 0 }),
+ );
+
+ // Container blur bleeds child red/blue squares across container boundaries
+ const mse = computeMse(plainImg.pixels, blurImg.pixels);
+ expect(mse).toBeGreaterThan(50);
+ });
+
+ it("evaluates animated effect uniforms on non-media layers across frames", async () => {
+ // Blur strength animates from 0 at frame 0 to 40 at frame 15 via Signal.builder
+ const animatedStrengthSignal = Signal.builder({
+ type: "custom",
+ fn: (ctx: { frame: number }) => (ctx.frame >= 15 ? 40 : 0),
+ });
+ const comp = createStage(30);
+ comp.add(
+ Layer.box({
+ x: 80,
+ y: 80,
+ width: 40,
+ height: 40,
+ background: "#ffffff",
+ }).withEffect(new Blur({ strength: animatedStrengthSignal })),
+ );
+
+ const frame0Img = await decodePngPixels(
+ await comp.renderFrame({ frame: 0 }),
+ );
+ const frame15Img = await decodePngPixels(
+ await comp.renderFrame({ frame: 15 }),
+ );
+
+ // At frame 0, strength is 0 -> sharp box, center is 255
+ const p0 = getPixel(frame0Img, 100, 100);
+ expect(p0.r).toBe(255);
+
+ // At frame 15, strength is 40 -> blurred box, center drops due to blur dispersion
+ const p15 = getPixel(frame15Img, 100, 100);
+ expect(p15.r).toBeLessThan(100);
+ expect(p15.r).toBeGreaterThan(20);
+
+ // The two frames must differ significantly
+ const mse = computeMse(frame0Img.pixels, frame15Img.pixels);
+ expect(mse).toBeGreaterThan(50);
+ });
+
+ it("supports multiple chained effects on non-media layers", async () => {
+ const comp = createStage();
+ comp.add(
+ Layer.box({
+ x: 50,
+ y: 50,
+ width: 100,
+ height: 100,
+ background: "#ffffff",
+ }).withEffects([new Pixelate({ size: 10 }), new Blur({ strength: 15 })]),
+ );
+
+ const buf = await comp.renderFrame({ frame: 0 });
+ expect(Buffer.isBuffer(buf)).toBe(true);
+ expect(buf.length).toBeGreaterThan(100);
+
+ const img = await decodePngPixels(buf);
+ const center = getPixel(img, 100, 100);
+ expect(center.r).toBeGreaterThan(100);
+ });
+});
diff --git a/packages/framefields/src/model-parent-offset.render.test.ts b/packages/framefields/src/model-parent-offset.render.test.ts
new file mode 100644
index 00000000..98828360
--- /dev/null
+++ b/packages/framefields/src/model-parent-offset.render.test.ts
@@ -0,0 +1,78 @@
+/**
+ * 3D models inside 2D containers sit at their own x / y in the parent's
+ * coordinates, like any other layer: a container's offset moves them too.
+ */
+import { describe, expect, it } from "vitest";
+import { Composition, Layer, Layer3D } from "./index.js";
+import { decodePngPixels, getPixel } from "./test-utils/pixels.js";
+
+async function litBounds(nested: boolean) {
+ const comp = new Composition({
+ width: 600,
+ height: 400,
+ fps: 30,
+ durationFrames: 10,
+ backgroundColor: "#000000",
+ });
+ const model = Layer3D.roundedBox({
+ id: "m",
+ width: 80,
+ height: 80,
+ depth: 40,
+ x: 60,
+ y: 60,
+ color: "#ffffff",
+ } as never);
+ comp.add(
+ nested
+ ? Layer.box({
+ id: "outer",
+ position: "absolute",
+ x: 300,
+ y: 200,
+ width: 200,
+ height: 150,
+ children: [
+ Layer.box({
+ id: "inner",
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: 200,
+ height: 150,
+ children: [model],
+ }),
+ ],
+ })
+ : model,
+ );
+ const img = await decodePngPixels(await comp.renderFrame({ frame: 0 }));
+ let x0 = 1e9;
+ let y0 = 1e9;
+ let x1 = -1;
+ let y1 = -1;
+ for (let y = 0; y < 400; y++)
+ for (let x = 0; x < 600; x++) {
+ const p = getPixel(img, x, y);
+ if (p.r + p.g + p.b > 60) {
+ x0 = Math.min(x0, x);
+ y0 = Math.min(y0, y);
+ x1 = Math.max(x1, x);
+ y1 = Math.max(y1, y);
+ }
+ }
+ return { x0, y0, x1, y1 };
+}
+
+describe("3D models in 2D containers", () => {
+ it("inherit the containers' offset", async () => {
+ const top = await litBounds(false);
+ const nested = await litBounds(true);
+ expect(top.x1).toBeGreaterThan(0);
+ // Bounds centres: perspective shows a little more side face off-centre.
+ const cx = (r: typeof top) => (r.x0 + r.x1) / 2;
+ const cy = (r: typeof top) => (r.y0 + r.y1) / 2;
+ expect(Math.abs(cx(nested) - cx(top) - 300)).toBeLessThan(15);
+ expect(Math.abs(cy(nested) - cy(top) - 200)).toBeLessThan(15);
+ });
+});
diff --git a/packages/framefields/src/primitives-3d-render.test.ts b/packages/framefields/src/primitives-3d-render.test.ts
index f7a9f010..43dc2a16 100644
--- a/packages/framefields/src/primitives-3d-render.test.ts
+++ b/packages/framefields/src/primitives-3d-render.test.ts
@@ -63,6 +63,38 @@ describe("Layer3D mesh primitives", () => {
expect(img.at(20, 20).r).toBeLessThan(10);
});
+ it("inherits 2D parent translation when nested inside a 2D container", async () => {
+ const comp = stage();
+ // Parent container positioned at (200, 150)
+ comp.add(
+ Layer.box({
+ id: "card",
+ x: 200,
+ y: 150,
+ width: 400,
+ height: 300,
+ children: [
+ Layer3D.roundedBox({
+ id: "slab-nested",
+ width: 300,
+ height: 40,
+ depth: 300,
+ radius: 12,
+ x: 200,
+ y: 150,
+ color: "#ff3030",
+ }),
+ ],
+ }),
+ );
+ const img = await decode(await comp.renderFrame({ frame: 0 }));
+ // World position: (200 + 200, 150 + 150) = (400, 300)
+ const top = img.at(400, 300);
+ expect(top.r).toBeGreaterThan(150);
+ expect(top.g).toBeLessThan(top.r / 2);
+ expect(img.at(20, 20).r).toBeLessThan(10);
+ });
+
it("tints by the animated `color` prop", async () => {
const comp = stage();
comp.add(
diff --git a/packages/node-sdk/renderer/index.ts b/packages/node-sdk/renderer/index.ts
index 17df8a31..c2ed4abd 100644
--- a/packages/node-sdk/renderer/index.ts
+++ b/packages/node-sdk/renderer/index.ts
@@ -336,6 +336,27 @@ export function registerWebGPURenderer(
webgpuRegistry.register(op, renderer);
}
+export type { WebGPUNodeRendererArgs } from "./gpu.js";
+
+export interface TextureSourceOp {
+ op: "TextureSource";
+ sourceTexture: GPUTexture;
+ opacity?: number;
+ dataType?: "Image";
+}
+
+registerWebGPURenderer("TextureSource", (args) => {
+ const op = args.props.virtualMedia.operation as unknown as TextureSourceOp;
+ if (op?.sourceTexture) {
+ args.ctx.renderer.drawTexture(
+ args.pass,
+ op.sourceTexture,
+ { x: 0, y: 0, width: args.targetWidth, height: args.targetHeight },
+ { opacity: Number(op.opacity ?? 1) },
+ );
+ }
+});
+
class AudioProcessorRegistry {
private processors = new Map<string, AudioProcessor>();
diff --git a/plugins/framefields/skills/framefields-effects/SKILL.md b/plugins/framefields/skills/framefields-effects/SKILL.md
index d863c35e..9394234e 100644
--- a/plugins/framefields/skills/framefields-effects/SKILL.md
+++ b/plugins/framefields/skills/framefields-effects/SKILL.md
@@ -22,18 +22,26 @@ See [references/effects-catalog.md](references/effects-catalog.md) for the gener
There are 4 main attachment modes in the engine:
### 1. Layer-Level Effect Pipeline
-Attach one or more effects to a media layer (video, image, SVG, Lottie). Box and text layers take only `TemporalDeflicker` and `Relight3D` directly; to treat a group or text as an image, render it into a media layer first.
-
+Attach one or more effects to any layer (`box`, `flex`, `shape`, `text`, `media`) directly via `.withEffect(effect)` or `.withEffects([...])`:
```typescript
-import { Layer, Curves, Vignette, Blur } from "framefields";
+import { Layer, Curves, Vignette, Blur, Pixelate } from "framefields";
+// Media layer with color grade and lens effects
const videoLayer = Layer.video("assets/footage.mp4", { fit: "cover" })
.withEffect(new Curves({
master: [{ x: 0, y: 0.05 }, { x: 0.5, y: 0.52 }, { x: 1, y: 0.95 }]
}))
.withEffect(new Vignette({ strength: 0.4, radius: 0.85, softness: 0.6 }))
.withEffect(new Blur({ strength: 8, blurType: "Gaussian" }));
+
+// Styled container box with blur
+const cardLayer = Layer.box({ width: 400, height: 300, background: "#1e1e24" })
+ .withEffect(new Blur({ radius: 12 }));
+
+// Kinetic text with pixelation
+const titleLayer = Layer.text("CYBERPUNK", { fontSize: 72 })
+ .withEffect(new Pixelate({ size: 8 }));
```
### 2. Whole-Composition Master Emulsion
diff --git a/spec/effect-layers.md b/spec/effect-layers.md
new file mode 100644
index 00000000..8565935a
--- /dev/null
+++ b/spec/effect-layers.md
@@ -0,0 +1,216 @@
+# Specification: Effects on Non-Media Layers
+
+**Status:** Proposed
+**Issue:** Resolves #4 ("Effects only work on media layers")
+**Target Packages:**
+- `packages/compositions` (`canvas-composition.ts`, `to-virtual-media.ts`)
+- `packages/node-sdk` (`renderer/index.ts`, `renderer/gpu.ts`)
+- `nodes/node-compositor` (`webgpu-renderer.ts`)
+- `packages/framefields` (tests & public API conformance)
+
+---
+
+## 1. Problem Statement
+
+In Framefields, calling `.withEffect(effect)` or `.withEffects([...])` is exposed on all layer builders (`Layer.box`, `Layer.shape`, `Layer.text`, `Layer.media`) via `withAnimation()`. Furthermore, `BaseNodeFields` in `CompositorProgramSchema` accepts `effects: z.array(...)` for any layer type.
+
+However, currently:
+1. `to-virtual-media.ts` only converts `node.effects` into Virtual Media DAG nodes if `node.kind === "media"`.
+2. For all non-media nodes (`box`, `flex`, `block`, `shape`, `text`), `node.effects` is retained only as an inert array on the `CompositorLayer` operation (`lop.effects`).
+3. Inside `node-compositor/src/renderers/webgpu-renderer.ts`, the intermediate textures (`groupTex` for containers, `localTex` for text/shapes) only execute hardcoded routines for `TemporalDeflicker` and `Relight3D`. All 50+ general WebGPU effect nodes (e.g. `FilmGrain`, `Blur`, `Vignette`, `Pixelate`, `Curves`, `Bloom`, `LUT`, etc.) are silently ignored.
+
+### Developer Consequence
+Developers cannot apply effects directly to a styled backdrop, vector shape, kinetic text, or UI layout. They are forced into awkward workarounds, such as overlaying an extra image layer with soft-light blending, or manually rendering pre-baked video clips.
+
+---
+
+## 2. Architecture & Design
+
+### 2.1 The Two Execution Models in Framefields
+
+```
+┌────────────────────────────────────────────────────────────────────────┐
+│ 1. VirtualMedia DAG (High-Level Graph Pipeline) │
+│ Orchestrated by HeadlessMediaRenderer & canvas-composition.ts │
+│ Nodes: node-film-grain, node-blur, node-vignette, etc. │
+│ Contract: childMedia = children[0] │
+│ { texture: tmpTex } = await drawChildToTexture(childMedia)│
+│ outputs to args.targetView │
+└───────────────────────────────────┬────────────────────────────────────┘
+ │ drawChild / TextureSource bridge
+ ▼
+┌────────────────────────────────────────────────────────────────────────┐
+│ 2. Compositor Node (Internal Monolithic WebGPU Renderer) │
+│ Evaluates Yoga layout, Slug typography, SDF shapes, and borders. │
+│ - Containers (box, flex, block) render into `groupTex`. │
+│ - Leaf primitives (shape, text) render into `localTex` / `finalTex`.│
+└────────────────────────────────────────────────────────────────────────┘
+```
+
+Every standard effect node in Framefields expects an input child in `virtualMedia.children[0]` and calls `drawChildToTexture(args, childMedia)`. `drawChildToTexture` creates a temporary texture and invokes `args.drawChild(childMedia, ...)`.
+
+### 2.2 The Solution: `TextureSource` Bridge
+
+To allow any rendered texture inside `node-compositor` to be processed by arbitrary effect nodes without modifying all 50+ individual effect packages, we introduce a universal **`TextureSource`** virtual media operation.
+
+1. **`TextureSource` Operation Definition:**
+ A virtual media node holding an existing `GPUTexture`:
+ ```typescript
+ interface TextureSourceOp {
+ op: "TextureSource";
+ sourceTexture: GPUTexture;
+ opacity?: number;
+ dataType?: "Image";
+ }
+ ```
+
+2. **Handling in `drawCompositionTree` (`packages/compositions/src/compositions/canvas-composition.ts`):**
+ When `drawCompositionTree` encounters `op.op === "TextureSource"`, it renders `sourceTexture` directly into `targetView` using `ctx.renderer.drawTexture`:
+ ```typescript
+ if (op.op === "TextureSource") {
+ const sourceTexture = op.sourceTexture as GPUTexture | undefined;
+ if (sourceTexture) {
+ ctx.renderer.drawTexture(
+ renderArgs.pass,
+ sourceTexture,
+ { x: 0, y: 0, width: targetWidth, height: targetHeight },
+ { opacity: Number(op.opacity ?? 1) },
+ );
+ }
+ renderArgs.pass.end();
+ return;
+ }
+ ```
+ This operation is also registered in `webgpuRegistry` (`@framefields/node-sdk`) for uniform dispatch across render environments.
+
+---
+
+## 3. Pipeline Integration
+
+### 3.1 Generic Effect Runner Helper
+
+In `nodes/node-compositor/src/renderers/webgpu-renderer.ts`, we add `applyLayerEffects`:
+
+```typescript
+async function applyLayerEffects(
+ effects: unknown[],
+ sourceTex: GPUTexture,
+ width: number,
+ height: number,
+ ctx: RenderContextValue,
+ encoder: GPUCommandEncoder,
+ props: NodeRenderProps,
+ drawChild: WebGPUNodeRendererArgs["drawChild"],
+ excludes: GPUTexture[],
+ shiftedFrame: number,
+ compositionFrame: number,
+ fps: number,
+ isVideoMode: boolean,
+ layerId: string,
+): Promise<{ texture: GPUTexture; view: GPUTextureView }>
+```
+
+#### Step-by-Step Execution:
+1. Filter out effects already handled by dedicated inline pipelines (`TemporalDeflicker`, `Deflicker`, `Relight3D`).
+2. If no remaining effects, return `{ texture: sourceTex, view: sourceTex.createView() }`.
+3. Construct the virtual media effect chain:
+ - Root child: `{ operation: { op: "TextureSource", sourceTexture: sourceTex } }`
+ - Wrap iteratively for each effect `eff`:
+ `currentMedia = { operation: { op: effOp.op, ...effOp }, children: [currentMedia] }`
+4. Allocate temporary output texture:
+ `const outTex = ctx.renderer.getTemporaryTexture(texW, texH, [sourceTex, ...excludes])`
+5. Invoke `await drawChild(currentMedia, ..., outView, outTex, texW, texH)`.
+6. Return `{ texture: outTex, view: outView }`.
+
+### 3.2 Container Layers (`box`, `flex`, `block`)
+
+1. **Bypass Guard:**
+ Prevent transparent container bypass optimization when `lop.effects` has items:
+ ```typescript
+ if (
+ (kind === "flex" || kind === "block") &&
+ (!Array.isArray(lop.effects) || lop.effects.length === 0) &&
+ ...
+ )
+ ```
+2. **Post-Processing Pass:**
+ In container rendering after background, children, border, deflicker, and relighting are drawn to `activeGroupTex`:
+ ```typescript
+ const postEffects = await applyLayerEffects(
+ lop.effects,
+ activeGroupTex,
+ targetW,
+ targetH,
+ ctx,
+ encoder,
+ props,
+ drawChild,
+ [activeTex, targetTexture, ...excludes],
+ shiftedFrame,
+ compositionFrame,
+ fps ?? 24,
+ isVideoMode,
+ lop.id ?? `container_${i}`,
+ );
+ activeGroupTex = postEffects.texture;
+ activeGroupView = postEffects.view;
+ ```
+ `activeGroupTex` is then composited onto `destTex` using `ctx.renderer.composite`.
+
+### 3.3 Leaf Primitives (`shape`, `text`)
+
+1. In leaf rendering, after vector rasterization or text rendering, masking, deflicker, relighting, and motion blur are complete on `finalTex`:
+ ```typescript
+ if (kind !== "media" && Array.isArray(lop.effects) && lop.effects.length > 0) {
+ const postEffects = await applyLayerEffects(
+ lop.effects,
+ finalTex,
+ texW,
+ texH,
+ ctx,
+ encoder,
+ props,
+ drawChild,
+ [localTex, activeTex, targetTexture, ...excludes],
+ shiftedFrame,
+ compositionFrame,
+ fps ?? 24,
+ isVideoMode,
+ lop.id ?? `leaf_${i}`,
+ );
+ finalTex = postEffects.texture;
+ }
+ ```
+2. For `kind === "media"`, skip `applyLayerEffects` because media effects are already resolved and executed upstream by `drawChild(content)` at line 3349.
+
+---
+
+## 4. Edge Cases & Safeguards
+
+1. **Texture Pool Exclusions:**
+ `sourceTex` and `outTex` must be included in `excludeTextures` passed to `drawChild` to prevent intermediate effect passes (e.g. Gaussian blur's two passes or multi-tap shaders) from borrowing and overwriting textures currently in use.
+2. **Scissor States:**
+ When running `applyLayerEffects`, isolate local scissors to `{ x: 0, y: 0, width: texW, height: texH }` so parent layout scissors don't clip full-quad effect shaders.
+3. **Signal & Animated Uniforms:**
+ Effect properties wrapped in `lop.effects` can be `Signal` instances or dynamic frame functions. Passing `compositionFrame`, `frame`, `fps`, and `props.signals` into `drawChild` ensures `unwrapFrameParam` and `signalRegistry` evaluate identical values on non-media layers as they do on media layers.
+4. **Zero Allocation overhead for layers without effects:**
+ If `lop.effects` is empty or undefined, zero extra textures are allocated and zero additional passes are encoded.
+
+---
+
+## 5. Implementation Steps
+
+1. **Step 1: Add `TextureSource` renderer**
+ - Register `TextureSource` in [canvas-composition.ts](file:///Users/okanaslankan/frameshop/packages/compositions/src/compositions/canvas-composition.ts) and `@framefields/node-sdk`.
+2. **Step 2: Add `applyLayerEffects` helper**
+ - Implement `applyLayerEffects` in [webgpu-renderer.ts](file:///Users/okanaslankan/frameshop/nodes/node-compositor/src/renderers/webgpu-renderer.ts).
+3. **Step 3: Wire containers and leaf primitives**
+ - Guard container bypass optimization.
+ - Run `applyLayerEffects` on `activeGroupTex` for containers.
+ - Run `applyLayerEffects` on `finalTex` for shapes and text (skipping `media`).
+4. **Step 4: Update Documentation**
+ - Update [framefields-effects/SKILL.md](file:///Users/okanaslankan/frameshop/plugins/framefields/skills/framefields-effects/SKILL.md) to note that effects can now be directly attached to any layer (`box`, `flex`, `shape`, `text`, `media`).
+5. **Step 5: Testing & Verification**
+ - Add integration tests verifying `.withEffect()` on `Layer.box`, `Layer.shape`, and `Layer.text`.
+ - Verify non-media layer with animated effect uniforms.
+ - Run all package tests (`node-compositor`, `compositions`, `framefields`).