@osmo.inc/cli-linux-arm64 0.1.19 → 0.1.21

package/runtime/packages/scene/src/evaluate.ts

@@ -1,7 +1,8 @@
+import { evaluateTextAnimation, type EvaluatedTextAnimation } from "./text-animation.js";
 import { readMask, maskSourceIndex } from "./mask.mjs";
 import { clipFields, clipTiming, isClipPrimitive } from "./clip.mjs";
 import { readGroupLabel, readGroupPlayback, readSceneTracks, trackPlayback } from "./metadata.mjs";
-import { isKnobRef, isKnobSet, resolveKnob, evaluateKnobs, type KnobScope, type KnobDescription } from "./knobs.js";
+import { isKnobRef, isKnobSet, resolveKnob, resolveKnobAsset, evaluateKnobs, type KnobScope, type KnobDescription } from "./knobs.js";
 import { evaluateEffects, type EvaluatedEffect } from "./effects.js";
 import {
 	Scene, Model, Surface,
@@ -40,6 +41,7 @@ interface BaseNode {
 	key?: string | number;
 }
 export interface CompositionNode extends BaseNode {
+    controls?: KnobDescription;
     type: "composition";
     width: number;
     height: number;
@@ -86,6 +88,7 @@ export interface PathNode extends BaseNode {
   stroke?: { color: Color; width: number; cap: "butt" | "round" | "square"; join: "miter" | "round" | "bevel"; miterLimit: number; trimStart: number; trimEnd: number };
 }
 export interface TextNode extends BaseNode {
+  animate?: EvaluatedTextAnimation;
   height?: number;
   verticalAlign?: "top" | "center" | "bottom";
   alignBounds?: "lineBox" | "glyphs";
@@ -145,6 +148,7 @@ export interface EvaluatedCamera {
 	fov: number;
 }
 export interface EvaluatedScene extends FrameContext {
+    controls?: KnobDescription;
 	effects?: EvaluatedEffect[];
 	camera?: EvaluatedCamera;
 	type: "scene";
@@ -179,17 +183,14 @@ function color(value: unknown, label: string): Color {
 	return value as Color;
 }
 function transform(props: Readonly<Record<string, unknown>>): Transform {
-	const scale = props.scale ?? 1;
+	const scale = number(props.scale ?? 1, "scale (one uniform number)");
 	const opacity = number(props.opacity ?? 1, "opacity", 0);
 	if (opacity > 1) throw new Error("opacity: must be <= 1");
 	return {
 		position: pair(props.position ?? [0, 0], "position"),
 		z: number(props.z ?? 0, "z"),
 		rotation: number(props.rotation ?? 0, "rotation"),
-		scale:
-			typeof scale === "number"
-				? [number(scale, "scale"), scale]
-				: pair(scale, "scale"),
+		scale: [scale, scale],
 		origin: pair(props.origin ?? [0, 0], "origin"),
 		opacity,
 	};
@@ -223,7 +224,13 @@ function isElement(value: unknown): value is Element {
 export function evaluateFrame(root: Element, frame: number): EvaluatedScene {
     return evaluateScene(root, frame);
 }
-function evaluateScene(root: Element, frame: number, clock?: Partial<ClockContext>, depth = 0): EvaluatedScene {
+interface SceneBindings {
+  values?: Record<string, unknown>;
+  scope: KnobScope;
+  time: number;
+  sourceFile?: string;
+}
+function evaluateScene(root: Element, frame: number, clock?: Partial<ClockContext>, depth = 0, instance?: SceneBindings): EvaluatedScene {
     if (depth > 32) throw new Error("Scene nesting exceeds 32 levels");
 	if (!isElement(root) || (root.type !== Scene && root.type !== "scene")) {
 		throw new Error(
@@ -234,7 +241,7 @@ function evaluateScene(root: Element, frame: number, clock?: Partial<ClockContex
 	checkProps(
 		p,
 		"Scene",
-		["width", "height", "duration", "fps", "background", "children", "effects", "tracks"],
+		["width", "height", "duration", "fps", "background", "children", "effects", "tracks", "knobs", "values"],
 		false,
 	);
 	const tracks = readSceneTracks(p.tracks);
@@ -258,6 +265,24 @@ function evaluateScene(root: Element, frame: number, clock?: Partial<ClockContex
 		duration,
         ...clock,
 	});
+    for (const values of [p.values, instance?.values])
+        if (values !== undefined && (!values || typeof values !== "object" || Array.isArray(values)))
+            throw new Error("Scene.values must be named knob bindings");
+    let scope: KnobScope = [];
+    let controls: KnobDescription | undefined;
+    if (p.knobs !== undefined) {
+        const overrides = instance?.values ?? {};
+        controls = evaluateKnobs(p.knobs as import("./knobs.js").KnobSet,
+            {...(p.values as object ?? {}), ...overrides}, context.time, instance?.scope ?? [], {
+                sourceFile: root.sourceFile,
+                valueSources: {...root.valueSources, ...Object.fromEntries(Object.keys(overrides)
+                    .filter(() => instance?.sourceFile).map(k => [k, instance!.sourceFile!]))},
+                bindingTimes: Object.fromEntries(Object.keys(overrides).map(k => [k, instance!.time])),
+            });
+        scope = [{set: p.knobs as import("./knobs.js").KnobSet, description: controls}];
+    } else if (p.values !== undefined || instance?.values !== undefined) {
+        throw new Error("Scene.values requires Scene.knobs");
+    }
 	let camera: EvaluatedCamera | undefined;
 	const children: unknown[] = [];
 	function collect(child: unknown, depth = 0): void {
@@ -269,14 +294,15 @@ function evaluateScene(root: Element, frame: number, clock?: Partial<ClockContex
 		) {
 			if (camera) throw new Error("Scene accepts only one Camera");
 			camera = evaluateCamera(
-				resolve(child.props, context.time) as Record<string, unknown>, context,
+				resolve(child.props, context.time, scope) as Record<string, unknown>, context,
 			);
 		} else {
 			children.push(child);
 		}
 	}
 	collect(p.children);
- const evaluatedChildren = isolateGroups(visit(children, context, depth));
+ const evaluatedChildren = isolateGroups(visit(children, context, depth, scope)
+  .filter(node => node.track === undefined || !tracks[node.track]?.hidden));
  function checkPlacement(nodes: SceneNode[], parent: string) {
   for (const n of nodes) {
    if (n.track !== undefined && parent !== "scene") throw new Error(`${n.type}.track is only supported on root timeline clips`);
@@ -286,7 +312,7 @@ function evaluateScene(root: Element, frame: number, clock?: Partial<ClockContex
   }
  }
  checkPlacement(evaluatedChildren, "scene");
- // Keep topology and local clocks stable while applying lane playback controls.
+ // Apply solo and mute to the remaining visible lanes without changing clocks.
  for (const node of evaluatedChildren) {
   const state = trackPlayback(tracks, node.track);
   if (!state.visible) node.transform.opacity = 0;
@@ -297,8 +323,9 @@ function evaluateScene(root: Element, frame: number, clock?: Partial<ClockContex
 		...(camera ? { camera } : {}),
 		...context,
 		totalFrames,
-		background: color(p.background ?? "transparent", "Scene.background"),
-		...(p.effects === undefined ? {} : { effects: evaluateEffects(p.effects, context.time, root.sourceFile) }),
+		background: color(resolve(p.background ?? "transparent", context.time, scope), "Scene.background"),
+        ...(controls ? {controls} : {}),
+		...(p.effects === undefined ? {} : { effects: evaluateEffects(p.effects, context.time, root.sourceFile, v => isKnobRef(v) ? resolveKnob(v, scope) : v) }),
 		children: evaluatedChildren,
 	};
 }
@@ -400,11 +427,17 @@ function visit(
 		[Camera, "camera"],
 	]);
 	const type = builtins.get(child.type) ?? child.type;
+    // Hidden layers remain in the authored document, but contribute no evaluated
+    // nodes, layout space, hit targets, or descendant media.
+    if (typeof type !== "function" && child.props.hidden !== undefined) {
+        readGroupPlayback({hidden: child.props.hidden});
+        if (child.props.hidden === true) return [];
+    }
     if (type === 'composition') {
         const source = child.props.scene as Element;
         const timing = clipTiming(child.props, context.duration, context.fps, 'Scene instance');
         const localTime = Math.max(0,Math.min(timing.duration-1e-9,context.time-timing.start));
-        const p = Object.fromEntries(Object.entries(child.props).filter(([k])=>k!=='scene').map(([k,v])=>[k,k==='effects'?v:resolve(v,localTime,scope)]));
+        const p = Object.fromEntries(Object.entries(child.props).filter(([k])=>k!=='scene').map(([k,v])=>[k,k==='effects'||k==='values'?v:resolve(v,localTime,scope)]));
         const trim = number(p.trimIn ?? 0, 'Scene instance.trimIn', 0);
         const sourceDuration = positive(source.props.duration, 'Scene.duration');
         if (trim >= sourceDuration) throw new Error('Scene instance.trimIn must be before the source end');
@@ -422,13 +455,14 @@ function visit(
             return Math.round(value);
         };
         const viewport = {...source,props:{...source.props,width:dimension('width'),height:dimension('height')}};
-        const scene = evaluateScene(viewport, 0, {time, frame:time*context.fps, fps:context.fps, offset, windowStart:start, windowEnd:end}, depth+1);
+        const scene = evaluateScene(viewport, 0, {time, frame:time*context.fps, fps:context.fps, offset, windowStart:start, windowEnd:end}, depth+1, {values:p.values as Record<string,unknown> | undefined, scope, time:localTime, sourceFile:child.sourceFile});
         const active = context.time >= timing.start && context.time < timing.start + Math.min(timing.duration, sourceDuration-trim);
         readGroupLabel(p.label); readGroupPlayback(p);
         const node: CompositionNode = {type:'composition',width:scene.width,height:scene.height,scene,
+            ...(scene.controls ? {controls:scene.controls} : {}),
             ...(timing.track === undefined ? {} : {track:timing.track}),
-            transform:transform({...p,opacity:active && !p.hidden ? p.opacity : 0}),
-            ...(p.effects === undefined ? {} : {effects:evaluateEffects(p.effects,localTime,child.sourceFile)})};
+            transform:transform({...p,opacity:active ? p.opacity : 0}),
+            ...(p.effects === undefined ? {} : {effects:evaluateEffects(p.effects,localTime,child.sourceFile,v => isKnobRef(v) ? resolveKnob(v,scope) : v)})};
         if (p.solo) soloGroups.add(node);
         return [node];
     }
@@ -452,10 +486,18 @@ function visit(
         readGroupPlayback(child.props);
         if (child.props.knobs !== undefined) {
             if (!isKnobSet(child.props.knobs)) throw new Error("Group.knobs must be a defineKnobs declaration");
-            controls = evaluateKnobs(child.props.knobs, child.props.values, context.time, scope);
+            controls = evaluateKnobs(child.props.knobs, child.props.values, context.time, scope, {sourceFile:child.sourceFile, valueSources:child.valueSources});
             scope = [...scope, { set: child.props.knobs, description: controls }];
         } else if (child.props.values !== undefined) throw new Error("Group.values requires Group.knobs");
     }
+    // Asset controls carry their authoring file through all forwarding scopes.
+    const assetSource = (prop: "src" | "font") => {
+        const ref = child.props[prop];
+        const asset = isKnobRef(ref) ? resolveKnobAsset(ref, scope) : undefined;
+        if (asset && asset.kind !== (prop === "font" ? "font" : type))
+            throw new Error(`${type}.${prop}: asset knob ${asset.name} has incompatible kind ${asset.kind}`);
+        return asset?.sourceFile ?? child.sourceFile;
+    };
     const props = Object.fromEntries(Object.entries(child.props).map(([name, value]) => [name,
         (name === "children" && !isKnobRef(value)) || name === "effects" || (type === "group" && (name === "knobs" || name === "values"))
             ? value : resolve(value, context.time, scope),
@@ -485,7 +527,7 @@ function visit(
 	if (type === "scene") throw new Error("Scenes cannot be nested");
 	if (type === "camera") throw new Error("Camera must be a direct child of Scene");
  if (type === "model") {
-  checkProps(props, "Model", ["src","position","z","height","rotation","scale","opacity","animations","children"], false);
+  checkProps(props, "Model", ["src","position","z","height","rotation","scale","opacity","hidden","animations","children"], false);
   if (typeof props.src !== "string" || !/\.glb$/i.test(props.src) || /^[a-z]+:/i.test(props.src)) throw new Error("Model.src: expected a local .glb path");
   const rot=props.rotation ?? [0,0,0];
   if (!Array.isArray(rot) || rot.length !== 3) throw new Error("Model.rotation: expected [x,y,z] degrees");
@@ -500,7 +542,7 @@ function visit(
   }
   const children=visit(props.children,context,depth+1,scope);
   if(children.some(n=>n.type!=="surface"))throw new Error("Model accepts Surface children only");
-  return [{type:"model",src:props.src,...(child.sourceFile?{sourceFile:child.sourceFile}:{}),
+  return [{type:"model",src:props.src,...(assetSource("src")?{sourceFile:assetSource("src")}:{}),
    ...(child.key===undefined?{}:{key:child.key}),
    ...(timing?.track === undefined ? {} : {track: timing.track}),
    transform:transform({...props,opacity:active ? props.opacity : 0,position:props.position??[context.width/2,context.height/2],rotation:0,scale:positive(props.scale??1,"Model.scale")}),
@@ -612,6 +654,8 @@ function visit(
             const isMask = i === sourceIndex;
             const evaluated = visit(isMask && mask!.mode === "vector" ? vectorMask(source) : source, context, depth + 1, scope);
             if (isMask) {
+                // Removing a hidden matte also removes its masking operation.
+                if (evaluated.length === 0) continue;
                 if (evaluated.length !== 1 || evaluated[0].type === "audio") throw new Error("Group.mask: source must be a visual layer");
                 maskIndex = children.length;
                 // A matte controls visibility only; video/audio descendants are silent.
@@ -654,9 +698,8 @@ function visit(
 				clip: props.clip !== false,
 				...(props.clip === true ? { clipEffects: true } : {}),
 				children: isolateGroups(sources ? children : visit(props.children, context, depth + 1, scope)),
-                ...(mask ? {mask:{index:maskIndex,mode:mask.mode,invert:mask.invert}} : {}),
+                ...(mask && maskIndex >= 0 ? {mask:{index:maskIndex,mode:mask.mode,invert:mask.invert}} : {}),
 			};
-        if (props.hidden) node.transform.opacity = 0;
         if (props.solo) soloGroups.add(node);
         return [node];
 	}
@@ -683,7 +726,7 @@ function visit(
 			Object.defineProperty(uniforms, name, { value, enumerable: true });
 		}
 		return [{ type: "shader", ...base, src: props.src, backdrop: props.backdrop ?? false,
-			...(child.sourceFile ? { sourceFile: child.sourceFile } : {}),
+			...(assetSource("src") ? { sourceFile: assetSource("src") } : {}),
 			width: positive(props.width, "Shader.width"), height: positive(props.height, "Shader.height"),
 			rounding: number(props.rounding ?? 0, "Shader.rounding", 0), uniforms }];
 	}
@@ -712,7 +755,7 @@ function visit(
 			type,
 			...base,
 			src: props.src,
-			...(child.sourceFile ? { sourceFile: child.sourceFile } : {}),
+			...(assetSource("src") ? { sourceFile: assetSource("src") } : {}),
 		};
 		if (visual)
 			Object.assign(node, {
@@ -738,7 +781,10 @@ function visit(
 				throw new Error(`${type}.playbackRate: expected 0.25 through 4`);
 			Object.assign(node, {
 				start,
-                duration: Math.max(1 / context.fps, end - start),
+                // Media windows use seconds, even when shorter than a video
+                // frame. Keep a positive placeholder only for muted, fully
+                // clipped nodes so their native metadata remains valid.
+                duration: end > start ? end - start : 1 / context.fps,
                 trimIn: number(props.trimIn ?? 0, `${type}.trimIn`, 0) + (start - authoredStart) * rate,
 				playbackRate: rate,
 				volume: end > start ? volume : 0,
@@ -805,7 +851,7 @@ function visit(
 		];
 	}
 	if (type === "text") {
-		checkProps(props, "Text", ["height", "verticalAlign", "alignBounds",
+		checkProps(props, "Text", ["animate", "height", "verticalAlign", "alignBounds",
 			"children",
 			"font",
 			"fontSize",
@@ -817,6 +863,7 @@ function visit(
 			"letterSpacing",
 			"path",
 		]);
+		if (props.animate !== undefined && props.path !== undefined) throw new Error("Text.animate cannot be combined with Text.path");
 		let path: TextPath | undefined;
 		if (props.path !== undefined) {
 			if (!props.path || typeof props.path !== "object" || Array.isArray(props.path))
@@ -863,8 +910,9 @@ function visit(
 				...base, ...box,
 				...(path ? { path } : {}),
 				text: String(props.children),
+                ...(props.animate === undefined ? {} : {animate: evaluateTextAnimation(props.animate, String(props.children), context.time, color(props.color ?? "#ffffff", "Text.color"))}),
 				font,
-				...(child.sourceFile ? { fontSource: child.sourceFile } : {}),
+				...(assetSource("font") ? { fontSource: assetSource("font") } : {}),
 				...(props.fontWeight === undefined
 					? {}
 					: {
@@ -910,7 +958,7 @@ function checkProps(
         "id",
         ...(isClipPrimitive(label) ? clipFields : []),
 			...allowed,
-		...(visual ? ["position", "z", "rotation", "scale", "origin", "opacity", "effects"] : []),
+		...(visual ? ["position", "z", "rotation", "scale", "origin", "opacity", "effects", "hidden"] : []),
 	]);
     if (props.id !== undefined && (typeof props.id !== "string" || !props.id.trim())) throw new Error(`${label}.id: expected a nonempty string`);
 	for (const name of Object.keys(props))

package/runtime/packages/scene/src/index.ts

@@ -67,3 +67,7 @@ export type { EffectPadding, Knob, KnobGroup, Knobs, KnobValues, EffectDefinitio
 
 export { defineKnobs, describeKnobs } from "./knobs.js";
 export type { KnobRef, KnobSet, KnobBindings, KnobDescription } from "./knobs.js";
+
+export type { TextAnimation, TextAnimationStyle } from "./text-animation.js";
+
+export type { AssetKind, AssetPath } from "./assets.js";

package/runtime/packages/scene/src/jsx-runtime.ts

@@ -2,7 +2,6 @@ import {
 	element,
 	type Element as SceneElement,
 	type InputProps,
-	type SceneProps,
 	type Component,
     type GroupInstance,
 	Scene,
@@ -18,9 +17,11 @@ export function jsx(
 	if (typeof type === "object" && type !== null) {
 		if (type.type === Scene || type.type === "scene") {
             const overrides = (props ?? {}) as Record<string, unknown>;
-            const allowed = new Set(['id','label','track','start','duration','trimIn','width','height','position','z','rotation','scale','origin','opacity','effects','hidden','solo']);
+            const allowed = new Set(['id','label','track','start','duration','trimIn','width','height','position','z','rotation','scale','origin','opacity','effects','hidden','solo','values']);
             for (const name of Object.keys(overrides)) if (!allowed.has(name))
                 throw new Error(`Scene instance.${name}: edit scene settings in the source file`);
+            if (overrides.values !== undefined && (!overrides.values || typeof overrides.values !== "object" || Array.isArray(overrides.values)))
+                throw new Error("Scene instance.values must be named knob bindings");
             return element("composition", {duration:type.props.duration, ...overrides, scene:type}, key);
         }
         if (type.type !== Group && type.type !== "group")
@@ -36,6 +37,7 @@ export function jsx(
 				...(values === undefined ? {} : { values: { ...(type.props.values as object ?? {}), ...values } }),
 			}, key),
 			...(type.sourceFile ? { sourceFile: type.sourceFile } : {}),
+            ...(type.valueSources ? { valueSources: type.valueSources } : {}),
 		});
 	}
 	return element(type, props ?? {}, key);
@@ -50,6 +52,10 @@ export function jsxDEV(
 ): SceneElement {
 	return Object.freeze({
 		...jsx(type, props, key),
+        ...(source?.fileName && props && "values" in props && props.values && typeof props.values === "object" ? {
+            valueSources: {...(typeof type === "object" ? type.valueSources : {}),
+                ...Object.fromEntries(Object.keys(props.values).map(k => [k, source.fileName!]))},
+        } : {}),
 		...(typeof type === "object" && type?.sourceFile && type.type!==Scene && type.type!=="scene" ? { sourceFile: type.sourceFile }
 			: source?.fileName ? { sourceFile: source.fileName } : {}),
 	});
@@ -68,6 +74,6 @@ export namespace JSX {
 	}
 	export interface IntrinsicElements {}
 	export type LibraryManagedAttributes<C, P> = C extends typeof Scene
-		? SceneProps
+		? P
 		: InputProps<P>;
 }

package/runtime/packages/scene/src/knob-schema.ts

@@ -1,3 +1,4 @@
+import { validAssetPath, type AssetKind } from "./assets.js";
 import { parseColor } from "./color.js";
 type When = Readonly<Record<string, string | number | boolean>>;
 interface Control {
@@ -23,6 +24,7 @@ export type Knob = Control & (
       max?: number;
     }
 	| { type: "color" | "text"; default: string }
+	| { type: "asset"; kind: AssetKind; default: string }
 	| { type: "boolean"; default: boolean }
 	| { type: "select"; default: string; options: Readonly<Record<string, string>> }
 	| { type: "multiselect"; default: readonly string[]; options: Readonly<Record<string, string>> }
@@ -59,6 +61,7 @@ export function validateKnobValue(knob: Knob, value: unknown, name: string) {
 	switch (knob.type) {
 		case "number": if (!finite(value)) fail(`${name}: expected a finite number`); break;
 		case "boolean": if (typeof value !== "boolean") fail(`${name}: expected a boolean`); break;
+		case "asset": if (!validAssetPath(knob.kind, value)) fail(`${name}: expected a local ${knob.kind} asset path`); break;
 		case "text": if (typeof value !== "string") fail(`${name}: expected text`); break;
 		case "color": if (!parseColor(value)) fail(`${name}: expected a hex color or transparent`); break;
 		case "select": if (typeof value !== "string" || !Object.hasOwn(knob.options, value)) fail(`${name}: unknown choice`); break;
@@ -97,9 +100,9 @@ export function validateKnobSchema(knobs: Knobs, inputGroups: Readonly<Record<st
 	}
 	for (const [name, knob] of Object.entries(knobs)) {
 		if (!/^[a-zA-Z][a-zA-Z0-9_]*$/.test(name) || !record(knob)) fail(`invalid knob ${name}`);
-		const extras = knob.type === "number" ? ["min", "max", "step"] : ["select", "multiselect"].includes(knob.type) ? ["options"] : [];
+		const extras = knob.type === "number" ? ["min", "max", "step"] : knob.type === "asset" ? ["kind"] : ["select", "multiselect"].includes(knob.type) ? ["options"] : [];
 		keys(knob, ["type", "default", "label", "group", "visibleWhen", ...extras], name);
-		if (!["number", "color", "text", "boolean", "select", "multiselect"].includes(knob.type)) fail(`${name}: unknown knob type`);
+		if (!["number", "color", "text", "boolean", "select", "multiselect", "asset"].includes(knob.type)) fail(`${name}: unknown knob type`);
 		if (knob.label !== undefined && typeof knob.label !== "string") fail(`${name}.label: expected text`);
 		if (knob.group !== undefined && !Object.hasOwn(groups, knob.group)) fail(`${name}: unknown group ${knob.group}`);
 		if (knob.type === "number") {

package/runtime/packages/scene/src/knobs.ts

@@ -1,3 +1,4 @@
+import type { AssetKind, AssetPath } from "./assets.js";
 import type { Color } from "./elements.js";
 import { isMotion, sampleMotion, type Motion, type MotionValue, type TrackDefinition } from "./motion.js";
 import { freeze, validateKnobSchema, validateKnobValue, type Knob, type KnobGroup, type Knobs, type KnobValue } from "./knob-schema.js";
@@ -5,7 +6,8 @@ import { freeze, validateKnobSchema, validateKnobValue, type Knob, type KnobGrou
 const SET = Symbol("osmo.knobs");
 const REF = Symbol("osmo.knob.reference");
 const VALUE = Symbol("osmo.knob.value-type");
-type ControlValue<K extends Knob> = K extends { type: "color" } ? Color
+type ControlValue<K extends Knob> = K extends { type: "asset"; kind: infer A extends AssetKind } ? AssetPath<A>
+  : K extends { type: "color" } ? Color
   : K extends { type: "select"; options: infer O } ? keyof O & string
   : K extends { type: "multiselect"; options: infer O } ? readonly (keyof O & string)[]
   : KnobValue<K>;
@@ -16,13 +18,16 @@ export interface KnobRef<T = unknown> {
   readonly [VALUE]?: T;
 }
 export type KnobSet<K extends Knobs = Knobs> = {
-  readonly [SET]: { readonly knobs: K; readonly groups: Readonly<Record<string, KnobGroup>> };
+  readonly [SET]: { readonly knobs: K; readonly groups: Readonly<Record<string, KnobGroup>>; readonly sourceFile?: string };
 } & { readonly [P in keyof K]: KnobRef<ControlValue<K[P]>> };
 /** Per-Group overrides. Parent knob references forward values into a child scope; motion tracks animate them. */
 export type KnobBindings<K extends Knobs> = {
-  readonly [P in keyof K]?: ControlValue<K[P]> | Motion<KnobValue<K[P]>> | KnobRef<ControlValue<K[P]>>;
+  readonly [P in keyof K]?: ControlValue<K[P]> | (K[P] extends { type: "asset" } ? never : Motion<KnobValue<K[P]>>) | KnobRef<ControlValue<K[P]>>;
 };
+export interface AssetBinding { kind: AssetKind; sourceFile?: string; name: string }
 export interface KnobDescription {
+  readonly assets?: Readonly<Record<string, AssetBinding>>;
+  readonly origins?: Readonly<Record<string, { sourceFile?: string; animated: boolean }>>;
   readonly knobs: Knobs;
   readonly groups: Readonly<Record<string, KnobGroup>>;
   readonly values: Readonly<Record<string, MotionValue>>;
@@ -39,11 +44,11 @@ export type KnobScope = readonly { set: KnobSet; description: KnobDescription }[
  * const style = defineKnobs({ size: { type: "number", default: 48, step: 1 }, ink: { type: "color", default: "#ffffff" } });
  * // <Group knobs={style} values={{ size: 64 }}><Text fontSize={style.size} color={style.ink}>Hello</Text></Group>
  */
-export function defineKnobs<const K extends Knobs>(knobs: K, options: { groups?: Readonly<Record<string, KnobGroup>> } = {}): KnobSet<K> {
+export function defineKnobs<const K extends Knobs>(knobs: K, options: { groups?: Readonly<Record<string, KnobGroup>> } = {}, sourceFile?: string): KnobSet<K> {
   if (!options || typeof options !== "object" || Array.isArray(options) || Object.keys(options).some(k => k !== "groups"))
     throw new Error("Knobs: options may only contain groups");
   validateKnobSchema(knobs, options.groups);
-  const definition = freeze(JSON.parse(JSON.stringify({ knobs, groups: options.groups ?? {} })));
+  const definition = freeze(JSON.parse(JSON.stringify({ knobs, groups: options.groups ?? {}, sourceFile })));
   const set = Object.create(null);
   Object.defineProperty(set, SET, { value: definition });
   for (const name of Object.keys(knobs)) {
@@ -64,13 +69,30 @@ export function resolveKnob(ref: KnobRef, scope: KnobScope): MotionValue {
   const { set, name } = ref[REF];
   for (let i = scope.length - 1; i >= 0; i--)
     if (scope[i].set === set) return scope[i].description.values[name];
-  throw new Error(`Knob "${name}" has no owning Group in this scope`);
+  throw new Error(`Knob "${name}" has no owning Group or Scene in this scope`);
+}
+
+export function resolveKnobAsset(ref: KnobRef, scope: KnobScope): AssetBinding | undefined {
+  const { set, name } = ref[REF];
+  for (let i = scope.length - 1; i >= 0; i--)
+    if (scope[i].set === set) return scope[i].description.assets?.[name];
+}
+function resolveKnobOrigin(ref: KnobRef, scope: KnobScope) {
+  const { set, name } = ref[REF];
+  for (let i = scope.length - 1; i >= 0; i--)
+    if (scope[i].set === set) return scope[i].description.origins?.[name];
+}
+export interface KnobContext {
+  sourceFile?: string;
+  valueSources?: Readonly<Record<string, string>>;
+  bindingTimes?: Readonly<Record<string, number>>;
 }
 
 // Track definitions are immutable. Validate all future keys once per knob,
 // rather than rescanning a long timeline on every rendered frame.
 const validatedTracks = new WeakMap<Motion, WeakSet<Knob>>();
 function validateBinding(knob: Knob, binding: MotionValue | Motion, name: string) {
+  if (knob.type === "asset" && isMotion(binding)) throw new Error(`Knob ${name}: asset bindings must be static`);
   if (!isMotion(binding)) { validateKnobValue(knob, binding, name); return; }
   let checked = validatedTracks.get(binding);
   if (checked?.has(knob)) return;
@@ -83,24 +105,42 @@ function validateBinding(knob: Knob, binding: MotionValue | Motion, name: string
 export function describeKnobs<K extends Knobs>(set: KnobSet<K>, bindings: KnobBindings<K> = {}, time = 0): KnobDescription {
   return evaluateKnobs(set, bindings, time, []);
 }
-export function evaluateKnobs(set: KnobSet, bindings: unknown, time: number, parentScope: KnobScope): KnobDescription {
+export function evaluateKnobs(set: KnobSet, bindings: unknown, time: number, parentScope: KnobScope, context: KnobContext = {}): KnobDescription {
   if (!isKnobSet(set)) throw new Error("Group.knobs must be a defineKnobs declaration");
   if (!Number.isFinite(time)) throw new Error("Knob time must be finite");
   const input = bindings === undefined ? {} : bindings;
   if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("Group.values must be named knob bindings");
-  const { knobs, groups } = set[SET];
+  const { knobs, groups, sourceFile } = set[SET];
   for (const name of Object.keys(input))
     if (!Object.hasOwn(knobs, name)) throw new Error(`Group.values: unknown knob "${name}"`);
   const values: Record<string, MotionValue> = Object.create(null);
   const tracks: Record<string, TrackDefinition> = Object.create(null);
+  const assets: Record<string, AssetBinding> = Object.create(null);
+  const origins: Record<string, {sourceFile?: string; animated:boolean}> = Object.create(null);
   for (const [name, knob] of Object.entries(knobs)) {
     const supplied = (input as Record<string, unknown>)[name];
     // Explicit null is invalid; only an omitted/undefined binding uses the default.
     let binding = supplied === undefined ? knob.default : supplied;
+    origins[name] = (isKnobRef(binding) ? resolveKnobOrigin(binding, parentScope) : undefined) ?? {
+      sourceFile: supplied === undefined ? sourceFile ?? context.sourceFile
+        : context.valueSources?.[name] ?? context.sourceFile,
+      animated: isMotion(binding),
+    };
+    const forwarded = isKnobRef(binding) ? resolveKnobAsset(binding, parentScope) : undefined;
+    if (knob.type === "asset") {
+      if (origins[name].animated) throw new Error(`Knob ${name}: asset bindings must be static`);
+      if (forwarded && forwarded.kind !== knob.kind)
+        throw new Error(`Knob ${name}: cannot bind ${forwarded.kind} to ${knob.kind}`);
+      assets[name] = forwarded ?? { kind: knob.kind, name,
+        sourceFile: origins[name].sourceFile };
+    } else if (forwarded) {
+      // Legacy text controls may forward typed paths without losing their origin.
+      assets[name] = forwarded;
+    }
     if (isKnobRef(binding)) binding = resolveKnob(binding, parentScope);
     validateBinding(knob, binding as MotionValue | Motion, name);
     const value = isMotion(binding)
-      ? sampleMotion(binding, time, knob.type === "color" ? "color" : knob.type === "number" ? undefined : "discrete")
+      ? sampleMotion(binding, context.bindingTimes?.[name] ?? time, knob.type === "color" ? "color" : knob.type === "number" ? undefined : "discrete")
       : binding as MotionValue;
     validateKnobValue(knob, value, name);
     values[name] = Array.isArray(value) ? [...value] : value;
@@ -114,5 +154,5 @@ export function evaluateKnobs(set: KnobSet, bindings: unknown, time: number, par
   const visibleKnobs = Object.fromEntries(Object.entries(knobs).map(([name, knob]) => [name,
     visible(knob.visibleWhen) && (!knob.group || visibleGroups[knob.group])
   ]));
-  return freeze({ knobs, groups, values, tracks, visibleGroups, visibleKnobs });
+  return freeze({ knobs, groups, values, tracks, visibleGroups, visibleKnobs, origins, ...(Object.keys(assets).length ? {assets} : {}) });
 }

package/runtime/packages/scene/src/motion-sampling.d.mts

@@ -1,2 +1,3 @@
+export function isEasing(value: any): boolean;
 /** @param {any} definition @param {number} time @param {"color" | "discrete"} [interpolation] @returns {any} */
 export function sampleTrack(definition: any, time: number, interpolation?: "color" | "discrete"): any;

package/runtime/packages/scene/src/motion-sampling.mjs

@@ -1,5 +1,38 @@
 import {parseColor, mixColor} from "./color-value.mjs";
+const curves = new Map();
+function curve(value) {
+	if (typeof value !== "string") return null;
+	if (curves.has(value)) return curves.get(value);
+	const match = /^cubic-bezier\(([^)]+)\)$/.exec(value);
+	if (!match) return null;
+	const parts = match[1].split(",");
+	const points = parts.map(Number);
+	if (parts.some(p => !p.trim()) || points.length !== 4 || !points.every(Number.isFinite) ||
+		points[0] < 0 || points[0] > 1 || points[2] < 0 || points[2] > 1) return null;
+	if (curves.size >= 256) curves.clear();
+	curves.set(value, points);
+	return points;
+}
+export function isEasing(value) {
+	return ["linear", "easeIn", "easeOut", "easeInOut", "hold"].includes(value) || curve(value) !== null;
+}
+function bezier(t, a, b) {
+	return 3 * (1 - t) ** 2 * t * a + 3 * (1 - t) * t * t * b + t ** 3;
+}
 function ease(t, easing) {
+	const points = curve(easing);
+	if (points) {
+		// Easing is y(x^-1(time)), not y(time). Bisection remains stable
+		// with flat tangents, including x1=1/x2=0, and allows y overshoot.
+		if (t <= 0 || t >= 1) return t;
+		let lo = 0, hi = 1;
+		for (let i = 0; i < 32; i++) {
+			const u = (lo + hi) / 2;
+			if (bezier(u, points[0], points[2]) < t) lo = u;
+			else hi = u;
+		}
+		return bezier((lo + hi) / 2, points[1], points[3]);
+	}
 	switch (easing) {
 		case "linear":
 			return t;

package/runtime/packages/scene/src/motion.ts

@@ -1,9 +1,11 @@
 import { parseColor } from "./color.js";
-import { sampleTrack } from "./motion-sampling.mjs";
+import { sampleTrack, isEasing } from "./motion-sampling.mjs";
 const TRACK = Symbol("osmo.motion.track");
 /** Numbers/vectors interpolate; colors interpolate in linear light; text, booleans and choices switch discretely. */
 export type MotionValue = number | boolean | string | readonly number[] | readonly string[];
-export type Easing = "linear" | "easeIn" | "easeOut" | "easeInOut" | "hold";
+/** Cubic Bézier x control points must be in 0..1; y may overshoot. */
+export type Easing = "linear" | "easeIn" | "easeOut" | "easeInOut" | "hold"
+	| `cubic-bezier(${number},${number},${number},${number})`;
 export interface Keyframe<T extends MotionValue = MotionValue> {
 	/** Scene time in seconds; nonnegative and strictly increasing within a track. */
 	readonly at: number;
@@ -73,9 +75,7 @@ export function defineMotion<const D extends MotionDefinition>(
 				throw new Error(`${label}: expected a color`);
 			if (
 				key.easing !== undefined &&
-				!["linear", "easeIn", "easeOut", "easeInOut", "hold"].includes(
-					key.easing,
-				)
+				!isEasing(key.easing)
 			) {
 				throw new Error(`${label}: unsupported easing ${key.easing}`);
 			}