Code-first video & image, rendered natively on WebGPU.
Let LayerAnimation.signal take a signal object
okanasl985e6be7bda2
diff --git a/.changeset/inline-signal-tracks.md b/.changeset/inline-signal-tracks.mdnew file mode 100644index 00000000..6aa948d5--- /dev/null+++ b/.changeset/inline-signal-tracks.md@@ -0,0 +1,6 @@+---+"gitframes": patch+"@gitframes/compositions": patch+---++`LayerAnimation.signal()` and `.colorSignal()` now accept a signal object (`Signal.fromArray`, `Signal.builder`, …) as well as a name registered with `comp.addSignal`. Before, passing the object produced a meaningless handle id and the track silently did nothing (or picked up an unrelated signal). The object is carried on its track and registered with the program under a generated `inline_signal_N` id, so specs stay plain JSON. Values that are neither a signal nor a name now throw.diff --git a/packages/compositions/src/program/animation.ts b/packages/compositions/src/program/animation.tsindex d263b0df..acdc9b56 100644--- a/packages/compositions/src/program/animation.ts+++ b/packages/compositions/src/program/animation.ts@@ -1,3 +1,4 @@+import { attachInlineSignal, resolveSignalArg } from "./inline-signals.js";import type {AnimatableProp,AnimationTrack,@@ -233,30 +234,6 @@ function parseEase(ease?: string | EaseRef): EaseRef | undefined {return undefined;}-function extractSignalHandleId(signalOrHandleId: unknown): string {- if (typeof signalOrHandleId === "string") return signalOrHandleId;- if (- signalOrHandleId &&- typeof signalOrHandleId === "object" &&- "inputHandleId" in signalOrHandleId &&- typeof (signalOrHandleId as { inputHandleId: unknown }).inputHandleId ===- "string"- ) {- return (signalOrHandleId as { inputHandleId: string }).inputHandleId;- }- if (- signalOrHandleId &&- typeof signalOrHandleId === "object" &&- "gpuBinding" in signalOrHandleId &&- (signalOrHandleId as { gpuBinding?: { nodeId?: string } }).gpuBinding- ?.nodeId- ) {- return (signalOrHandleId as { gpuBinding: { nodeId: string } }).gpuBinding- .nodeId;- }- return String(signalOrHandleId);-}-/*** Fluent builder and runtime representation for layer animations.* Supports chainable keyframes, reactive signal binding, Perlin wiggles, and springs.@@ -790,13 +767,18 @@ export class LayerAnimation implements LayerAnimationSpec {/*** Binds an animatable property to a reactive continuous Signal (e.g. LFO, speech energy, audio pitch).+ *+ * `signalOrHandleId` is either a signal object (`Signal.fromArray`,+ * `Signal.builder`, an audio channel …) — carried on the track and+ * registered with the program automatically — or the name of a signal+ * registered with `comp.addSignal(name, signal)`.*/public signal(prop: AnimatableProp,signalOrHandleId: unknown,options: SignalTrackOptions = {},): this {- const handleId = extractSignalHandleId(signalOrHandleId);+ const { handleId, inline } = resolveSignalArg(signalOrHandleId);const id = `${prop}_sig_${handleId}_${this.tracks.length}`;const source: TrackSource = {@@ -811,6 +793,7 @@ export class LayerAnimation implements LayerAnimationSpec {debounceFrames: options.debounceFrames ?? 2,channel: options.channel ?? "primary",};+ if (inline) attachInlineSignal(source, inline);this.tracks.push({id,@@ -822,14 +805,15 @@ export class LayerAnimation implements LayerAnimationSpec {}/**- * Modulates color interpolation based on an active signal.+ * Modulates color interpolation based on an active signal (object or+ * registered name, as in {@link LayerAnimation.signal}).*/public colorSignal(prop: AnimatableProp,signalOrHandleId: unknown,options: ColorSignalOptions,): this {- const handleId = extractSignalHandleId(signalOrHandleId);+ const { handleId, inline } = resolveSignalArg(signalOrHandleId);const id = `${prop}_colorSig_${handleId}_${this.tracks.length}`;const source: TrackSource = {@@ -844,6 +828,7 @@ export class LayerAnimation implements LayerAnimationSpec {colorThreshold: options.threshold,channel: "primary",};+ if (inline) attachInlineSignal(source, inline);this.tracks.push({id,diff --git a/packages/compositions/src/program/inline-signals.ts b/packages/compositions/src/program/inline-signals.tsnew file mode 100644index 00000000..7ab49da3--- /dev/null+++ b/packages/compositions/src/program/inline-signals.ts@@ -0,0 +1,121 @@+/**+ * Inline signal objects on animation tracks.+ *+ * `LayerAnimation.signal(prop, Signal.fromArray(...))` binds a track to a+ * signal object instead of a name registered with `comp.addSignal`. The spec+ * stays plain data: the track's `inputHandleId` gets a generated name and the+ * object rides on the source under a non-enumerable symbol (invisible to JSON,+ * zod and hashing). `compositorToProgram` walks the layout and folds those+ * objects into the program's `signals` map under their generated names, so+ * every evaluator (which only looks signals up by name) sees them.+ */++const INLINE_SIGNAL = Symbol.for("gitframes.inlineSignal");++const handleIds = new WeakMap<object, string>();+let nextHandle = 0;++/**+ * The generated handle id for a signal object. The same object always gets+ * the same id, so reusing one signal across tracks registers it once.+ */+function inlineSignalHandleId(signal: object): string {+ let id = handleIds.get(signal);+ if (id === undefined) {+ id = `inline_signal_${nextHandle++}`;+ handleIds.set(signal, id);+ }+ return id;+}++/**+ * Resolves the `signalOrHandleId` argument of `LayerAnimation.signal` /+ * `colorSignal` to a handle id, plus the signal object to carry inline (when+ * it is not a registered name).+ */+export function resolveSignalArg(signalOrHandleId: unknown): {+ handleId: string;+ inline?: object;+} {+ if (typeof signalOrHandleId === "string") {+ return { handleId: signalOrHandleId };+ }+ if (+ signalOrHandleId === null ||+ (typeof signalOrHandleId !== "object" &&+ typeof signalOrHandleId !== "function")+ ) {+ throw new TypeError(+ `LayerAnimation.signal: expected a signal object or a signal name, got ${String(signalOrHandleId)}. ` ++ `Pass a signal (Signal.fromArray / Signal.builder / an audio channel …) or register it with comp.addSignal(name, signal) and pass the name.`,+ );+ }+ const obj = signalOrHandleId as {+ inputHandleId?: unknown;+ gpuBinding?: { nodeId?: unknown };+ get?: unknown;+ };+ // Graph source descriptors (audio extractors …) are resolved by their own+ // handle at render time.+ if (typeof obj.inputHandleId === "string") {+ return { handleId: obj.inputHandleId };+ }+ // GPU-bound signals keep their node id as the handle; their CPU `get()`+ // still rides inline, so the track animates even when nothing registers+ // that node id (an explicit registration under the same id wins).+ if (typeof obj.gpuBinding?.nodeId === "string") {+ return typeof obj.get === "function"+ ? { handleId: obj.gpuBinding.nodeId, inline: signalOrHandleId }+ : { handleId: obj.gpuBinding.nodeId };+ }+ return {+ handleId: inlineSignalHandleId(signalOrHandleId),+ inline: signalOrHandleId,+ };+}++/** Attaches an inline signal object to a track source without making it enumerable. */+export function attachInlineSignal(source: object, signal: object): void {+ Object.defineProperty(source, INLINE_SIGNAL, {+ value: signal,+ enumerable: false,+ configurable: true,+ writable: true,+ });+}++/** The inline signal object carried by a track source, if any. */+export function getInlineSignal(source: unknown): object | undefined {+ if (!source || typeof source !== "object") return undefined;+ return (source as { [INLINE_SIGNAL]?: object })[INLINE_SIGNAL];+}++/**+ * Collects every inline signal object under `nodes` (animation tracks of each+ * node, recursing into `children`) keyed by its generated handle id.+ */+export function collectInlineSignals(+ nodes: readonly unknown[],+ out: Record<string, unknown> = {},+): Record<string, unknown> {+ for (const node of nodes) {+ if (!node || typeof node !== "object") continue;+ const { animation, children } = node as {+ animation?: { tracks?: unknown };+ children?: unknown;+ };+ const tracks = animation?.tracks;+ if (Array.isArray(tracks)) {+ for (const track of tracks) {+ const source = (track as { source?: { inputHandleId?: unknown } })+ ?.source;+ const signal = getInlineSignal(source);+ if (signal && typeof source?.inputHandleId === "string") {+ out[source.inputHandleId] = signal;+ }+ }+ }+ if (Array.isArray(children)) collectInlineSignals(children, out);+ }+ return out;+}diff --git a/packages/compositions/src/program/to-virtual-media.ts b/packages/compositions/src/program/to-virtual-media.tsindex de358868..c399c78d 100644--- a/packages/compositions/src/program/to-virtual-media.ts+++ b/packages/compositions/src/program/to-virtual-media.ts@@ -17,6 +17,7 @@ import {getActiveMediaMetadata,type VirtualMediaData,} from "@gitframes/core";+import { collectInlineSignals } from "./inline-signals.js";import type { CompositorProgramConfig, LayoutNode } from "./schema.js";import { computeStaggerDelay } from "./stagger.js";@@ -288,7 +289,12 @@ export function compositorToProgram(// is NOT read by the renderer — do not treat it as the source of// truth (the config is).layout: config.layout,- signals: signals ?? (config as any).signals ?? {},+ // Signal objects passed straight to `LayerAnimation.signal` ride on+ // their tracks; fold them in under their generated handle ids.+ signals: {+ ...collectInlineSignals(config.layout),+ ...(signals ?? (config as any).signals ?? {}),+ },...(((config as any).onRequestFrame ||(options as any).onRequestFrame) && {onRequestFrame:diff --git a/packages/gitframes/src/signal-tracks.test.ts b/packages/gitframes/src/signal-tracks.test.tsnew file mode 100644index 00000000..71cf9024--- /dev/null+++ b/packages/gitframes/src/signal-tracks.test.ts@@ -0,0 +1,146 @@+/**+ * LayerAnimation.signal accepts a signal object or the name of one registered+ * with comp.addSignal — both must drive the property frame by frame.+ */+import { Canvas, loadImage } from "skia-canvas";+import { describe, expect, it } from "vitest";+import { Composition, Layer, LayerAnimation, Signal } from "./index.js";++const FPS = 30;+// Opacity 0 on even frames, 1 on odd ones.+const GATE = Array.from({ length: 30 }, (_, f) => f % 2);++async function pixel(png: Buffer, x: number, y: number) {+ const img = await loadImage(png);+ const canvas = new Canvas(img.width, img.height);+ const ctx = canvas.getContext("2d");+ ctx.drawImage(img, 0, 0);+ return Array.from(ctx.getImageData(x, y, 1, 1).data.slice(0, 3));+}++function comp() {+ return new Composition({+ width: 200,+ height: 200,+ fps: FPS,+ durationFrames: 30,+ backgroundColor: "#000000",+ });+}++function square(id: string, x: number, anim: LayerAnimation) {+ return Layer.box({+ id,+ position: "absolute",+ x,+ y: 0,+ width: 100,+ height: 200,+ background: "#ffffff",+ }).animate(anim);+}++async function brightness(c: Composition, frame: number, x = 50) {+ return (await pixel(await c.renderFrame({ frame }), x, 100))[0];+}++describe("signal tracks", () => {+ it("animates from a signal object (Signal.fromArray)", async () => {+ const c = comp();+ c.add(+ square(+ "a",+ 0,+ LayerAnimation.create().signal("opacity", Signal.fromArray(GATE, FPS)),+ ),+ );+ expect(await brightness(c, 4)).toBe(0);+ expect(await brightness(c, 5)).toBe(255);+ });++ it("animates from a signal object (Signal.builder custom fn)", async () => {+ const c = comp();+ const sig = Signal.builder({+ type: "custom",+ fn: (ctx) => (ctx.frame >= 10 ? 1 : 0),+ });+ c.add(square("a", 0, LayerAnimation.create().signal("opacity", sig)));+ expect(await brightness(c, 3)).toBe(0);+ expect(await brightness(c, 12)).toBe(255);+ });++ it("animates from a registered signal name", async () => {+ const c = comp();+ c.addSignal("gate", Signal.fromArray(GATE, FPS));+ c.add(square("a", 0, LayerAnimation.create().signal("opacity", "gate")));+ expect(await brightness(c, 4)).toBe(0);+ expect(await brightness(c, 5)).toBe(255);+ });++ it("keeps each inline signal on its own track, alongside named ones", async () => {+ const c = comp();+ c.addSignal("gate", Signal.fromArray(GATE, FPS));+ const inverted = Signal.fromArray(+ GATE.map((v) => 1 - v),+ FPS,+ );+ c.add(+ square("named", 0, LayerAnimation.create().signal("opacity", "gate")),+ // A nested child: inline signals are collected through containers.+ Layer.box({+ id: "wrap",+ position: "absolute",+ x: 100,+ y: 0,+ width: 100,+ height: 200,+ children: [+ square(+ "inline",+ 0,+ LayerAnimation.create().signal("opacity", inverted),+ ),+ ],+ }),+ );+ expect(await brightness(c, 4, 50)).toBe(0);+ expect(await brightness(c, 4, 150)).toBe(255);+ expect(await brightness(c, 5, 50)).toBe(255);+ expect(await brightness(c, 5, 150)).toBe(0);+ });++ it("keeps the spec plain data and registers inline signals with the program", () => {+ const sig = Signal.fromArray(GATE, FPS);+ const anim = LayerAnimation.create()+ .signal("opacity", sig)+ .signal("scale", sig, { offset: 1 });+ const [a, b] = anim.tracks.map(+ (t) => (t.source as { inputHandleId: string }).inputHandleId,+ );+ // Same object → same handle, and the spec serialises without the object.+ expect(a).toBe(b);+ expect(a).toMatch(/^inline_signal_\d+$/);+ expect(JSON.parse(JSON.stringify(anim.toSpec()))).toEqual(anim.toSpec());++ const c = comp();+ c.add(square("a", 0, anim));+ const vm = c.toVirtualMedia() as {+ operation: { op: string; signals?: Record<string, unknown> };+ children?: unknown[];+ };+ const find = (n: typeof vm): typeof vm | undefined =>+ n.operation.op === "Compositor"+ ? n+ : (n.children as (typeof vm)[] | undefined)?.map(find).find(Boolean);+ expect(find(vm)?.operation.signals?.[a]).toBe(sig);+ });++ it("rejects values that are neither a signal nor a name", () => {+ expect(() => LayerAnimation.create().signal("opacity", 0.5)).toThrow(+ /addSignal/,+ );+ expect(() => LayerAnimation.create().signal("opacity", undefined)).toThrow(+ /addSignal/,+ );+ });+});diff --git a/plugins/gitframes/skills/gitframes-compose/SKILL.md b/plugins/gitframes/skills/gitframes-compose/SKILL.mdindex 71fc38ae..36c78e6a 100644--- a/plugins/gitframes/skills/gitframes-compose/SKILL.md+++ b/plugins/gitframes/skills/gitframes-compose/SKILL.md@@ -211,11 +211,23 @@ const floatAnim = LayerAnimation.create()const springAnim = LayerAnimation.create().spring("scale", { damping: 14, stiffness: 190, mass: 1 });-// Audio reactivity via Signal+// Audio reactivity: pass the signal object straight in…+const kick = Signal.fromArray(kickEnvelope, fps); // or Signal.builder({ type: "custom", fn })const beatAnim = LayerAnimation.create()- .signal("scale", "drum_stem_signal", { multiplier: 0.12, offset: 1.0, smoothing: 2 });+ .signal("scale", kick, { multiplier: 0.12, offset: 1.0, smoothing: 2 });++// …or register it once by name and bind the name (handy when many layers share it)+comp.addSignal("drum_stem_signal", kick);+const beatAnim2 = LayerAnimation.create()+ .signal("opacity", "drum_stem_signal", { multiplier: 0.5, offset: 0.5 });```+`.signal()` / `.colorSignal()` drive the prop with `value × multiplier + offset` every frame. A signal+object is carried on its track and registered with the program automatically (under a generated+`inline_signal_N` id, so the spec stays plain JSON); a string is looked up in `comp.addSignal` names.+Anything else (a number, `undefined`) throws. Signals are sampled at the **composition** frame+(`ctx.frame`), not the layer's local frame.+---## Critical Authoring Rules & Gotchas