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

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.19",
+  "version": "0.1.20",
   "type": "module",
   "files": [
     "dist",

package/release.json

@@ -1,36 +1,36 @@
 {
-  "version": "0.1.19",
+  "version": "0.1.20",
   "package": "@osmo.inc/cli-linux-arm64",
   "platform": "linux-arm64",
   "channel": "latest",
-  "sourceCommit": "8256a0d29c67b090c37504207a379b0924c735e7",
+  "sourceCommit": "d884ae69ee0ce8f9171efbfcef5c5f9feb43c7e6",
   "sourceDirty": false,
   "signing": "unsigned",
   "licenseFileIncluded": false,
-  "dependencyCount": 232,
+  "dependencyCount": 297,
   "nativeDefaultFeatures": false,
   "contents": {
-    "totalBytes": 53140218,
-    "fileCount": 947,
+    "totalBytes": 53814153,
+    "fileCount": 1079,
     "groups": {
-      "vendor": 18350716,
-      "studio": 17122088,
+      "vendor": 18416740,
+      "studio": 17474729,
       "node_modules/typescript": 9913238,
-      "third-party": 4722136,
+      "third-party": 4936088,
       "src": 2622428,
-      "dist": 269721,
-      "runtime": 137987,
+      "dist": 293259,
+      "runtime": 155767,
       "THIRD_PARTY_NOTICES.md": 1090,
       "package.json": 814
     },
     "largestFiles": [
       {
         "path": "vendor/osmo-lite",
-        "bytes": 18314952
+        "bytes": 18376392
       },
       {
         "path": "studio/src/engine_bg.wasm",
-        "bytes": 12010921
+        "bytes": 12038924
       },
       {
         "path": "node_modules/typescript/lib/typescript.js",
@@ -38,7 +38,7 @@
       },
       {
         "path": "studio/src/app.js",
-        "bytes": 4767135
+        "bytes": 5055327
       },
       {
         "path": "node_modules/typescript/lib/lib.dom.d.ts",
@@ -65,12 +65,12 @@
         "bytes": 370430
       },
       {
-        "path": "third-party/rust-standard-library/COPYRIGHT-library.html",
-        "bytes": 279302
+        "path": "dist/studio.js",
+        "bytes": 293259
       },
       {
-        "path": "dist/studio.js",
-        "bytes": 269721
+        "path": "third-party/rust-standard-library/COPYRIGHT-library.html",
+        "bytes": 279302
       },
       {
         "path": "node_modules/typescript/lib/lib.es5.d.ts",
@@ -80,10 +80,18 @@
         "path": "src/starter/animations/osmo/shape34-0.tsx",
         "bytes": 139902
       },
+      {
+        "path": "studio/src/app.css",
+        "bytes": 131513
+      },
       {
         "path": "third-party/npm/mediabunny@1.52.2/source/src/isobmff/isobmff-demuxer.ts",
         "bytes": 118682
       },
+      {
+        "path": "third-party/inventory.json",
+        "bytes": 115089
+      },
       {
         "path": "src/starter/animations/osmo/shape8-83.tsx",
         "bytes": 112489
@@ -95,27 +103,19 @@
       {
         "path": "third-party/npm/mediabunny@1.52.2/source/src/media-source.ts",
         "bytes": 97606
-      },
-      {
-        "path": "studio/src/app.css",
-        "bytes": 95067
-      },
-      {
-        "path": "third-party/npm/mediabunny@1.52.2/source/src/codec-data.ts",
-        "bytes": 92683
       }
     ]
   },
   "hashes": {
-    "dist/studio.js": "be67ed4c321a22a87a446d893f89b4bd342f30290bf519a85c1aea784b612acd",
-    "vendor/osmo-lite": "4a81a51e3c3121597e64c3b2d9b06d72d471fd993a79af61086cebcb70fe3bf8",
-    "studio/src/engine_bg.wasm": "889927bd262b27f34e2495a90810fae3295adcfda80c7fda7b2dbd7d13eb8ee1",
-    "studio/src/app.js": "ca23cc9220cb68e3d23eb3c771c80b1221a971c1c1ace207ebf2acc4e1f24272",
-    "studio/src/app.css": "aa53a4e2206280c169981d9940f042539e70b2c665895a3e041830c6f41d8ffe",
-    "third-party/inventory.json": "fe5ca3c8784ad803bf5ecdc227071301115eec6ea2d220fe96aa2024f59902e6"
+    "dist/studio.js": "ae0b993f2af7d91678570c9b64b99b62f6c581982b56f2d7305e56516424ed2a",
+    "vendor/osmo-lite": "e2cfb28ea87859434bb19a6c381b7dba0767d2961c38182c21174f0b5011a35d",
+    "studio/src/engine_bg.wasm": "1a2f493e6ec26f178658c7d3f251b4f6e6ba62104da7735a346058754687eb2a",
+    "studio/src/app.js": "44a2284edc365d197450e286aaeda4dfcfa7e6f97385d7f0c98d7c32da9816df",
+    "studio/src/app.css": "1f57360a850bbbf2b51ebb0920c5b54c649b8e5d3bea7a6537b67befaa233906",
+    "third-party/inventory.json": "d0813172f555bb9547e7a23b1b23197b8264f1cd22e1fd75a73fa0ad73e847e0"
   },
   "lockfiles": {
-    "package-lock.json": "a7fb6b84762aeb4f3ce90166df48f53c2853d2684282ed1c019502f840602e28",
+    "package-lock.json": "e762e69bcb0bc3d88b7dc7b8ff81736790e2e05e992f42230378e5ef8373dc68",
     "apps/native/Cargo.lock": "cf31d67cf167c5f32438abfeb42159eb50da61d36e4e482bae50ed3d71241373",
     "packages/render-engine/Cargo.lock": "a1a68051e1eea30ef0fa46bf17cd0685bb2c6a327defed0405e0d63dd61017a7"
   }

package/runtime/apps/native/tools/compile.mjs

@@ -33,14 +33,15 @@ const result = await build({
 			const overridden = Object.hasOwn(sources, file);
 			const text = overridden ? sources[file] : await readFile(file, "utf8");
             const loader = /tsx$/.test(file) ? "tsx" : /jsx$/.test(file) ? "jsx" : /[cm]?ts$/.test(file) ? "ts" : "js";
-            if (!text.includes("defineEffect")) return overridden ? {contents:text,loader} : undefined;
+            if (!text.includes("defineEffect") && !text.includes("defineKnobs")) return overridden ? {contents:text,loader} : undefined;
 			const ast = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
-			const names = new Set(), namespaces = new Set();
+			const names = new Set(), knobNames = new Set(), namespaces = new Set();
 			for (const statement of ast.statements) {
 				if (!ts.isImportDeclaration(statement) || statement.moduleSpecifier.text !== "@osmo/scene") continue;
 				const imports = statement.importClause?.namedBindings;
 				if (imports && ts.isNamedImports(imports)) for (const item of imports.elements) {
 					if ((item.propertyName ?? item.name).text === "defineEffect") names.add(item.name.text);
+                    if ((item.propertyName ?? item.name).text === "defineKnobs") knobNames.add(item.name.text);
 				}
 				if (imports && ts.isNamespaceImport(imports)) namespaces.add(imports.name.text);
 			}
@@ -51,6 +52,12 @@ const result = await build({
 						ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.expression) && namespaces.has(node.expression.expression.text) && node.expression.name.text === "defineEffect")) {
 						return ts.factory.updateCallExpression(node, node.expression, node.typeArguments, [ts.visitNode(node.arguments[0], visit), ts.factory.createStringLiteral(file)]);
 					}
+                    if (ts.isCallExpression(node) && node.arguments.length <= 2 &&
+                        (ts.isIdentifier(node.expression) && knobNames.has(node.expression.text) ||
+                        ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.expression) && namespaces.has(node.expression.expression.text) && node.expression.name.text === "defineKnobs")) {
+                        return ts.factory.updateCallExpression(node, node.expression, node.typeArguments,
+                            [node.arguments[0], node.arguments[1] ?? ts.factory.createObjectLiteralExpression(), ts.factory.createStringLiteral(file)]);
+                    }
 					return ts.visitEachChild(node, visit, context);
 				};
 				return ts.visitNode(root, visit);
@@ -128,6 +135,7 @@ async function collectEffects(target) {
 async function collectFonts(nodes) {
 	for (const node of nodes) {
 		await collectEffects(node);
+        for (const state of node.animate?.states ?? []) await collectEffects(state);
         if(node.type === "composition") { await collectEffects(node.scene); await collectFonts(node.scene.children); }
 		if (["group","model","surface"].includes(node.type)) await collectFonts(node.children);
 		if (["image", "video", "audio", "model"].includes(node.type)) {

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

@@ -0,0 +1,27 @@
+/** Local asset contracts shared by authoring, evaluation and the editor. */
+export type AssetKind = "image" | "video" | "audio" | "font" | "model";
+/** Plain paths remain valid; typed knob references retain their asset kind. */
+export type AssetPath<K extends AssetKind> = string & {
+	readonly __assetKind?: K;
+};
+export const assetExtensions: Record<AssetKind, readonly string[]> = {
+	image: ["png", "jpg", "jpeg", "webp", "gif", "svg"],
+	video: ["mp4", "webm", "mov", "m4v"],
+	audio: ["wav", "mp3", "m4a", "aac", "ogg", "flac"],
+	font: ["ttf", "otf"],
+	model: ["glb"],
+};
+export function validAssetPath(
+	kind: AssetKind,
+	value: unknown,
+): value is string {
+	return (
+		Object.hasOwn(assetExtensions, kind) &&
+		typeof value === "string" &&
+		value.length > 0 &&
+		value.length <= 4096 &&
+		value === value.trim() &&
+		!/^[a-z][a-z0-9+.-]*:|^[/\\]|[\x00-\x1f?#\\]/i.test(value) &&
+		assetExtensions[kind].includes(value.split(".").at(-1)!.toLowerCase())
+	);
+}

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

@@ -1,3 +1,5 @@
+import type { AssetPath } from "./assets.js";
+import type { TextAnimation } from "./text-animation.js";
 import type { EffectInstance } from "./effects.js";
 import type { KnobRef, KnobSet, KnobBindings } from "./knobs.js";
 import type { Knobs } from "./knob-schema.js";
@@ -13,7 +15,7 @@ export type Input<T> = KnobRef<T> | (T extends number
 	? T | Motion<T>
 	: T extends readonly number[]
 		? T | Motion<T> | { readonly [K in keyof T]: Input<T[K]> }
-		: T extends object
+		: T extends string ? T : T extends object
 			? { readonly [K in keyof T]: Input<T[K]> }
 			: T);
 export type InputProps<P> = {
@@ -69,14 +71,14 @@ export interface TransformProps extends ClipProps {
 	z?: number;
 	/** Clockwise degrees around origin. Default: 0. */
 	rotation?: number;
-	/** Uniform factor or [x, y] factors. Default: 1. */
-	scale?: number | Vec2;
+	/** Uniform factor applied to both axes. Default: 1. */
+	scale?: number;
 	/** Local pivot in pixels, not a fraction. Default: [0, 0]. */
 	origin?: Vec2;
 	/** 0–1. Group opacity composites its children together. Default: 1. */
 	opacity?: number;
 }
-export interface SceneProps {
+export interface SceneStyleProps {
 	/** Optional lane metadata keyed by track number (0–99). Labels are static, one word maximum. Does not change paint order. */
 	tracks?: Readonly<Record<number, TrackMetadata>>;
 	/** Filter the complete viewport, including 3D surfaces; array order matters. */
@@ -90,9 +92,14 @@ export interface SceneProps {
 	/** Positive frames per second; static. Default: 30. */
 	fps?: number;
 	/** Fixed viewport backdrop, independent of camera and layout. Default: transparent. */
-	background?: Color;
+	background?: Input<Color>;
 	children?: Child;
 }
+/** Scene controls follow the same ownership and instance rules as Groups. */
+export type SceneProps<K extends Knobs = Knobs> = SceneStyleProps & (
+  | { knobs: KnobSet<K>; values?: KnobBindings<NoInfer<K>> }
+  | { knobs?: never; values?: never }
+);
 /** Timeline lane metadata; independent of the clips occupying the lane. */
 export interface TrackMetadata {
 	/** Optional static display name, one word maximum, e.g. "Titles". */
@@ -179,12 +186,16 @@ export type SceneInstanceProps = InputProps<TransformProps & {
     width?: number;
     /** Viewport height in pixels; defaults to the source scene height. Does not scale content. */
     height?: number;
-}> & { label?: string; hidden?: boolean; solo?: boolean; trimIn?: number };
+}> & {
+    label?: string; hidden?: boolean; solo?: boolean; trimIn?: number;
+    /** Overrides for the controls declared by the source Scene. */
+    values?: Readonly<Record<string, MotionValue | Motion | KnobRef>>;
+};
 /** JSX attribute contract for imported static Group documents (legacy) and Scenes. */
-export type GroupInstance = (props: GroupInstanceProps) => Element;
+export type GroupInstance = (props: GroupInstanceProps | SceneInstanceProps) => Element;
 export interface ImageProps extends TransformProps {
 	/** Local PNG/JPEG/WebP/SVG path, relative to this TSX file; no remote URLs. */
-	src: string;
+	src: AssetPath<"image">;
 	/** Positive box width in pixels. */
 	width: number;
 	/** Positive box height in pixels. */
@@ -214,7 +225,7 @@ export interface ShaderProps extends TransformProps {
 export type ModelSelector = string | number;
 export interface ModelProps extends ClipProps {
 	/** Local .glb path. Uses the default GLB scene; inspect node/material/clip names before targeting them. */
-	src: string;
+	src: AssetPath<"model">;
 	/** Composition [x, y] in pixels. Default: scene center. */
 	position?: Vec2;
 	/** Depth in pixels; positive toward the viewer. Default: 0. */
@@ -269,10 +280,10 @@ export interface MediaTiming extends ClipProps {
 	/** Gain from 0–1; animatable in JSX. Use 0 to mute video audio. Default: 1. */
 	volume?: number;
 }
-export interface VideoProps extends ImageProps, MediaTiming {}
+export interface VideoProps extends Omit<ImageProps, "src">, MediaTiming { src: AssetPath<"video"> }
 export interface AudioProps extends MediaTiming {
 	/** Local audio file path, relative to this TSX file. */
-	src: string;
+	src: AssetPath<"audio">;
 }
 
 /** SVG-style stroke painted along the contour, centered on its geometry. */
@@ -338,7 +349,7 @@ export interface TextStyleProps extends TransformProps {
 	/** Whole string or number; the renderer handles shaping, kerning and glyph placement. */
 	children: string | number;
 	/** Bundled Inter or a local .ttf/.otf path relative to this TSX file. Default: Inter. */
-	font?: string;
+	font?: AssetPath<"font">;
 	/** Positive size in pixels. Default: 48. */
 	fontSize?: number;
 	/** Requested font weight; omitted uses the selected face’s default. */
@@ -351,6 +362,8 @@ export interface TextStyleProps extends TransformProps {
 export type TextProps = TextStyleProps & (
 	| {
       path?: never;
+      /** Staggered post-layout character, word or visual-line animation. */
+      animate?: TextAnimation;
       /** Positive wrapping width in pixels; omitted uses natural text width. */
       width?: number;
       /** Positive text-box height. Overflow remains visible; use a clipping Group to crop. */
@@ -367,6 +380,7 @@ export type TextProps = TextStyleProps & (
 	| {
       /** Move a whole string along a curve by animating progress. No width, align, lineHeight or line breaks. */
       path: TextPath;
+      animate?: never;
       width?: never;
       height?: never;
       verticalAlign?: never;
@@ -402,6 +416,8 @@ export interface Element {
 	readonly props: Readonly<Record<string, unknown>>;
 	readonly key?: string | number;
 	readonly sourceFile?: string;
+    /** File supplying each literal instance override. */
+    readonly valueSources?: Readonly<Record<string, string>>;
 }
 export function element(
 	type: Element["type"],
@@ -418,7 +434,7 @@ export function element(
 /** Root composition with fixed dimensions, duration and FPS.
  * @example <Scene width={1080} height={1080} duration={4} fps={30} background="#141414"><Text track={0}>Hello</Text></Scene> */
 export const Scene = Object.assign(
-	(props: SceneProps): Element => element("scene", props),
+	<const K extends Knobs = Knobs>(props: SceneProps<K>): Element => element("scene", props),
 	{ sceneRoot: true as const },
 );
 /** Layout, transform and style children together; also draws boxes, ellipses and thin lines.

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,14 @@ 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));
  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`);
@@ -297,8 +322,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,
 	};
 }
@@ -404,7 +430,7 @@ function visit(
         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 +448,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)})};
+            ...(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 +479,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),
@@ -500,7 +535,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")}),
@@ -683,7 +718,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 +747,7 @@ function visit(
 			type,
 			...base,
 			src: props.src,
-			...(child.sourceFile ? { sourceFile: child.sourceFile } : {}),
+			...(assetSource("src") ? { sourceFile: assetSource("src") } : {}),
 		};
 		if (visual)
 			Object.assign(node, {
@@ -805,7 +840,7 @@ function visit(
 		];
 	}
 	if (type === "text") {
-		checkProps(props, "Text", ["height", "verticalAlign", "alignBounds",
+		checkProps(props, "Text", ["animate", "height", "verticalAlign", "alignBounds",
 			"children",
 			"font",
 			"fontSize",
@@ -817,6 +852,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 +899,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
 					? {}
 					: {

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") {