@osmo.inc/cli 0.1.15

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

@@ -0,0 +1,69 @@
+export { Scene, Camera, Group, Rect, Path, Text, Image, Video, Audio, Shader, Fragment, Model, Surface } from "./elements.js";
+export type {
+	ClipProps,
+	RootClipProps,
+	PathProps,
+	PathStroke,
+	ModelProps,
+	SurfaceProps,
+	ModelSelector,
+	ShaderProps,
+	UniformValue,
+	SceneProps,
+	TrackMetadata,
+	CameraProps,
+	GroupProps,
+    Mask,
+	GroupInstanceProps,
+    SceneInstanceProps,
+	GroupInstance,
+	ImageProps,
+	VideoProps,
+	AudioProps,
+	MediaTiming,
+	Stroke,
+	RectProps,
+	TextProps,
+	TextPath,
+	TextStyleProps,
+	TransformProps,
+	FrameContext,
+	Component,
+	Element,
+	Child,
+	Color,
+	Vec2,
+	Vec3,
+	Input,
+} from "./elements.js";
+export { defineMotion, describeMotion, sampleMotion } from "./motion.js";
+export type {
+	Motion,
+	MotionValue,
+	TrackDefinition,
+	Keyframe,
+	Easing,
+	MotionDefinition,
+	Motions,
+} from "./motion.js";
+export { evaluateFrame } from "./evaluate.js";
+export type {
+	EvaluatedScene,
+	EvaluatedCamera,
+	SceneNode,
+	GroupNode,
+	RectNode,
+	PathNode,
+	TextNode,
+	MediaNode,
+	ShaderNode,
+	ModelNode,
+	SurfaceNode,
+	Transform,
+} from "./evaluate.js";
+
+export { defineEffect, describeEffect, blur, grain } from "./effects.js";
+export type { EffectPadding, Knob, KnobGroup, Knobs, KnobValues, EffectDefinition, EffectBindings, EffectFactory, EffectInstance, EvaluatedEffect } from "./effects.js";
+
+export { defineKnobs, describeKnobs } from "./knobs.js";
+export type { KnobRef, KnobSet, KnobBindings, KnobDescription } from "./knobs.js";

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

@@ -0,0 +1,73 @@
+import {
+	element,
+	type Element as SceneElement,
+	type InputProps,
+	type SceneProps,
+	type Component,
+    type GroupInstance,
+	Scene,
+	Group,
+} from "./elements.js";
+export { Fragment } from "./elements.js";
+
+export function jsx(
+	type: SceneElement["type"] | SceneElement,
+	props: object | null,
+	key?: string | number,
+): SceneElement {
+	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']);
+            for (const name of Object.keys(overrides)) if (!allowed.has(name))
+                throw new Error(`Scene instance.${name}: edit scene settings in the source file`);
+            return element("composition", {duration:type.props.duration, ...overrides, scene:type}, key);
+        }
+        if (type.type !== Group && type.type !== "group")
+			throw new Error("Reusable files must export a Scene (or legacy Group)");
+		const overrides = (props ?? {}) as Record<string, unknown>;
+		if ("children" in overrides || "knobs" in overrides)
+			throw new Error("An animation instance cannot replace children or knob definitions; use values or edit its source");
+		const values = overrides.values;
+		if (values !== undefined && (!values || typeof values !== "object" || Array.isArray(values)))
+			throw new Error("Animation values must be named knob bindings");
+		return Object.freeze({
+			...element(type.type, { ...type.props, ...overrides,
+				...(values === undefined ? {} : { values: { ...(type.props.values as object ?? {}), ...values } }),
+			}, key),
+			...(type.sourceFile ? { sourceFile: type.sourceFile } : {}),
+		});
+	}
+	return element(type, props ?? {}, key);
+}
+export const jsxs = jsx;
+export function jsxDEV(
+	type: SceneElement["type"] | SceneElement,
+	props: object | null,
+	key?: string | number,
+	_staticChildren?: boolean,
+	source?: { fileName?: string },
+): SceneElement {
+	return Object.freeze({
+		...jsx(type, props, key),
+		...(typeof type === "object" && type?.sourceFile && type.type!==Scene && type.type!=="scene" ? { sourceFile: type.sourceFile }
+			: source?.fileName ? { sourceFile: source.fileName } : {}),
+	});
+}
+
+export namespace JSX {
+	/** Static JSX documents can be used as tags by this runtime. The signature
+     * describes instance attributes for TypeScript; do not call documents as JS functions. */
+    export type Element = SceneElement & GroupInstance;
+	export type ElementType = Component<any> | (SceneElement & GroupInstance);
+	export interface ElementChildrenAttribute {
+		children: unknown;
+	}
+	export interface IntrinsicAttributes {
+		key?: string | number;
+	}
+	export interface IntrinsicElements {}
+	export type LibraryManagedAttributes<C, P> = C extends typeof Scene
+		? SceneProps
+		: InputProps<P>;
+}

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

@@ -0,0 +1,115 @@
+import { parseColor } from "./color.js";
+type When = Readonly<Record<string, string | number | boolean>>;
+interface Control {
+  /** Display label; optional, otherwise use the knob name. */
+  label?: string;
+  /** Named group from the declaration’s groups map. */
+  group?: string;
+  /** UI visibility: all named scalar knobs must equal these values. Does not disable rendering or animation. */
+  visibleWhen?: When;
+}
+/** Typed control schema. Number step is required; min/max are UI bounds, not runtime clamping.
+ * select/multiselect options map stored values to display labels; text needs a uniform mapping in custom effects.
+ */
+export type Knob = Control & (
+	| {
+      type: "number";
+      default: number;
+      /** Positive drag/slider increment, e.g. 0.1 or 1. Does not quantize animation. */
+      step: number;
+      /** Optional UI lower bound; min and max together enable a bounded slider. */
+      min?: number;
+      /** Optional UI upper bound; must exceed min if both are supplied. */
+      max?: number;
+    }
+	| { type: "color" | "text"; 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>> }
+);
+/** Foldable UI section; groups can nest and depend on preset/boolean knob values. */
+export interface KnobGroup {
+  label?: string;
+  /** Parent group name; cycles are rejected. */
+  parent?: string;
+  /** Initial folded state. */
+  collapsed?: boolean;
+  /** Same equality conditions as Knob.visibleWhen; parent visibility also applies. */
+  visibleWhen?: When;
+}
+export type Knobs = Readonly<Record<string, Knob>>;
+export type KnobValue<K extends Knob> = K extends { type: "number" } ? number : K extends { type: "boolean" } ? boolean
+	: K extends { type: "multiselect" } ? readonly string[] : string;
+export type KnobValues<K extends Knobs> = { readonly [P in keyof K]: KnobValue<K[P]> };
+
+function fail(message: string): never { throw new Error(`Knobs: ${message}`); }
+function record(value: unknown): value is Record<string, any> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function keys(value: object, allowed: readonly string[], label: string) {
+	for (const key of Object.keys(value)) if (!allowed.includes(key)) fail(`${label}: unsupported property ${key}`);
+}
+function finite(value: unknown): value is number { return typeof value === "number" && Number.isFinite(value); }
+export function freeze<T>(value: T): T {
+	if (value && typeof value === "object") { for (const child of Object.values(value)) freeze(child); Object.freeze(value); }
+	return value;
+}
+
+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 "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;
+		case "multiselect":
+			if (!Array.isArray(value) || value.some(v => typeof v !== "string" || !Object.hasOwn(knob.options, v)) || new Set(value).size !== value.length)
+				fail(`${name}: expected unique known choices`);
+	}
+}
+
+
+export function validateKnobSchema(knobs: Knobs, inputGroups: Readonly<Record<string, KnobGroup>> = {}) {
+	if (!record(knobs) || Object.keys(knobs).length > 32) fail("expected at most 32 named knobs");
+	const groups = inputGroups;
+	if (!record(groups)) fail("groups must be named definitions");
+	const condition = (when: When | undefined) => {
+		if (when === undefined) return;
+		if (!record(when)) fail("visibleWhen must be a condition object");
+		for (const [name, expected] of Object.entries(when)) {
+			if (!Object.hasOwn(knobs, name)) fail(`visibleWhen: unknown knob ${name}`);
+			if (!["number", "boolean", "text", "select"].includes(knobs[name].type)) fail(`visibleWhen: ${name} must be a scalar knob`);
+			validateKnobValue(knobs[name], expected, `visibleWhen.${name}`);
+		}
+	};
+	for (const [name, group] of Object.entries(groups)) {
+		if (!record(group)) fail(`group ${name}: expected a definition`);
+		keys(group, ["label", "parent", "collapsed", "visibleWhen"], name);
+		if (group.label !== undefined && typeof group.label !== "string") fail(`${name}.label: expected text`);
+		if (group.collapsed !== undefined && typeof group.collapsed !== "boolean") fail(`${name}.collapsed: expected boolean`);
+		const seen = new Set([name]); let parent = group.parent;
+		while (parent !== undefined) {
+			if (!Object.hasOwn(groups, parent)) fail(`${name}: unknown parent group ${parent}`);
+			if (seen.has(parent)) fail(`${name}: group cycle`);
+			seen.add(parent); parent = groups[parent].parent;
+		}
+		condition(group.visibleWhen);
+	}
+	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"] : [];
+		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 (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") {
+			if (!finite(knob.step) || knob.step <= 0) fail(`${name}: step must be positive`);
+			for (const bound of [knob.min, knob.max]) if (bound !== undefined && !finite(bound)) fail(`${name}: invalid bound`);
+			if (knob.min !== undefined && knob.max !== undefined && knob.min >= knob.max) fail(`${name}: min must be below max`);
+		}
+		if (knob.type === "select" || knob.type === "multiselect") {
+			if (!record(knob.options) || !Object.keys(knob.options).length || Object.values(knob.options).some(v => typeof v !== "string")) fail(`${name}: options must map values to labels`);
+		}
+		validateKnobValue(knob, knob.default, name); condition(knob.visibleWhen);
+	}
+}

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

@@ -0,0 +1,118 @@
+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";
+
+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
+  : K extends { type: "select"; options: infer O } ? keyof O & string
+  : K extends { type: "multiselect"; options: infer O } ? readonly (keyof O & string)[]
+  : KnobValue<K>;
+
+/** Bind to a compatible descendant prop; resolved by the nearest owning Group, never used in arithmetic. */
+export interface KnobRef<T = unknown> {
+  readonly [REF]: { readonly set: KnobSet; readonly name: string };
+  readonly [VALUE]?: T;
+}
+export type KnobSet<K extends Knobs = Knobs> = {
+  readonly [SET]: { readonly knobs: K; readonly groups: Readonly<Record<string, KnobGroup>> };
+} & { 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]>>;
+};
+export interface KnobDescription {
+  readonly knobs: Knobs;
+  readonly groups: Readonly<Record<string, KnobGroup>>;
+  readonly values: Readonly<Record<string, MotionValue>>;
+  readonly tracks: Readonly<Record<string, TrackDefinition>>;
+  readonly visibleGroups: Readonly<Record<string, boolean>>;
+  readonly visibleKnobs: Readonly<Record<string, boolean>>;
+}
+export type KnobScope = readonly { set: KnobSet; description: KnobDescription }[];
+
+/** Declare convenience controls shared by any number of descendant props.
+ * Attach with Group.knobs; override defaults with Group.values. Nesting the same
+ * set creates a new scope; nesting a different set retains access to parent refs.
+ * @example
+ * 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> {
+  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 set = Object.create(null);
+  Object.defineProperty(set, SET, { value: definition });
+  for (const name of Object.keys(knobs)) {
+    set[name] = Object.freeze({
+      [REF]: Object.freeze({ set, name }),
+      [Symbol.toPrimitive]() { throw new Error(`Knob ${name} is a reference, not a value; bind it to a prop`); },
+    });
+  }
+  return Object.freeze(set);
+}
+export function isKnobSet(value: unknown): value is KnobSet {
+  return !!value && typeof value === "object" && SET in value;
+}
+export function isKnobRef(value: unknown): value is KnobRef {
+  return !!value && typeof value === "object" && REF in value;
+}
+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`);
+}
+
+// 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 (!isMotion(binding)) { validateKnobValue(knob, binding, name); return; }
+  let checked = validatedTracks.get(binding);
+  if (checked?.has(knob)) return;
+  for (const value of [binding.definition.default, ...(binding.definition.keyframes ?? []).map(k => k.value)])
+    validateKnobValue(knob, value, name);
+  if (!checked) { checked = new WeakSet(); validatedTracks.set(binding, checked); }
+  checked.add(knob);
+}
+
+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 {
+  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];
+  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);
+  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;
+    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")
+      : binding as MotionValue;
+    validateKnobValue(knob, value, name);
+    values[name] = Array.isArray(value) ? [...value] : value;
+    if (isMotion(binding)) tracks[name] = binding.definition;
+  }
+  const visible = (when?: Readonly<Record<string, unknown>>) => !when || Object.entries(when).every(([k,v]) => values[k] === v);
+  const visibleGroups: Record<string, boolean> = Object.create(null);
+  const groupVisible = (name: string): boolean => visibleGroups[name] ??= visible(groups[name].visibleWhen)
+    && (!groups[name].parent || groupVisible(groups[name].parent!));
+  for (const name of Object.keys(groups)) groupVisible(name);
+  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 });
+}

package/runtime/packages/scene/src/mask.d.mts

@@ -0,0 +1,6 @@
+export function readMask(value: any): {
+    source: any;
+    mode: any;
+    invert: any;
+} | null;
+export function maskSourceIndex(children: any, mask: any): any;

package/runtime/packages/scene/src/mask.mjs

@@ -0,0 +1,17 @@
+// A mask names one direct child. Its pixels are evaluated in the group's clock.
+export function readMask(value) {
+  if (value === undefined || value === false) return null;
+  const mask = typeof value === 'string' ? {source:value} : value;
+  if (!mask || typeof mask !== 'object' || Array.isArray(mask) ||
+      Object.keys(mask).some(k=>!['source','mode','invert'].includes(k)) ||
+      typeof mask.source !== 'string' || !mask.source.trim() ||
+      !['alpha','vector','luminance'].includes(mask.mode ?? 'alpha') ||
+      (mask.invert !== undefined && typeof mask.invert !== 'boolean'))
+    throw new Error('Group.mask: expected a child id or { source, mode: "alpha" | "vector" | "luminance", invert?: boolean }');
+  return {source:mask.source,mode:mask.mode ?? 'alpha',invert:mask.invert ?? false};
+}
+export function maskSourceIndex(children, mask) {
+  const matches=children.map((c,i)=>c?.props?.id===mask.source?i:-1).filter(i=>i>=0);
+  if(matches.length!==1)throw new Error(`Group.mask: "${mask.source}" must identify exactly one direct child`);
+  return matches[0];
+}

package/runtime/packages/scene/src/metadata.d.mts

@@ -0,0 +1,23 @@
+/** @param {{hidden?: unknown, solo?: unknown}} props */
+export function readGroupPlayback(props: {
+    hidden?: unknown;
+    solo?: unknown;
+}): {
+    hidden: boolean;
+    solo: boolean;
+};
+/** Optional lane metadata indexed by the same 0–99 numbers as clip.track.
+ * @param {unknown} value @returns {Record<number, {label?: string, hidden?: boolean, solo?: boolean, muted?: boolean}>} */
+export function readSceneTracks(value: unknown): Record<number, {
+    label?: string;
+    hidden?: boolean;
+    solo?: boolean;
+    muted?: boolean;
+}>;
+/** Effective playback state without removing nodes or changing their identity.
+ * @param {ReturnType<typeof readSceneTracks>} tracks @param {number | undefined} track */
+export function trackPlayback(tracks: ReturnType<typeof readSceneTracks>, track: number | undefined): {
+    visible: boolean;
+    audible: boolean;
+};
+export function readGroupLabel(value: unknown): string | undefined;

package/runtime/packages/scene/src/metadata.mjs

@@ -0,0 +1,44 @@
+// Static editor metadata, shared by Strict validation, evaluation and the editor.
+/** @param {unknown} value @param {number} maxWords @param {string} field */
+function readLabel(value, maxWords, field) {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string' || !value.trim() || value.trim().split(/\s+/u).length > maxWords)
+    throw new Error(`${field}: expected a nonempty static string of at most ${maxWords} ${maxWords === 1 ? 'word' : 'words'}`);
+  return value.trim().replace(/\s+/gu, ' ');
+}
+/** Optional Group display name. IDs remain independent of labels. @param {unknown} value */
+export const readGroupLabel = value => readLabel(value, 2, 'Group.label');
+
+/** @param {{hidden?: unknown, solo?: unknown}} props */
+export function readGroupPlayback(props) {
+  for (const field of ['hidden', 'solo'])
+    if (props[field] !== undefined && typeof props[field] !== 'boolean')
+      throw new Error(`Group.${field}: expected a static boolean`);
+  return {hidden: props.hidden === true, solo: props.solo === true};
+}
+
+/** Optional lane metadata indexed by the same 0–99 numbers as clip.track.
+ * @param {unknown} value @returns {Record<number, {label?: string, hidden?: boolean, solo?: boolean, muted?: boolean}>} */
+export function readSceneTracks(value) {
+  if (value === undefined) return {};
+  if (!value || typeof value !== 'object' || Array.isArray(value))
+    throw new Error('Scene.tracks: expected an object keyed by track numbers (0–99)');
+  return Object.fromEntries(Object.entries(value).map(([key, metadata]) => {
+    if (!/^(?:0|[1-9]\d?)$/.test(key)) throw new Error('Scene.tracks: track numbers must be integers from 0 to 99');
+    if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata) || Object.keys(metadata).some(key => !['label','hidden','solo','muted'].includes(key)))
+      throw new Error(`Scene.tracks.${key}: expected label, hidden, solo or muted metadata`);
+    const label = readLabel(metadata.label, 1, `Scene.tracks.${key}.label`);
+    for (const field of ['hidden','solo','muted'])
+      if (metadata[field] !== undefined && typeof metadata[field] !== 'boolean')
+        throw new Error(`Scene.tracks.${key}.${field}: expected a static boolean`);
+    return [key, {...metadata, ...(label === undefined ? {} : {label})}];
+  }));
+}
+
+/** Effective playback state without removing nodes or changing their identity.
+ * @param {ReturnType<typeof readSceneTracks>} tracks @param {number | undefined} track */
+export function trackPlayback(tracks, track) {
+  const own = track === undefined ? {} : tracks[track] ?? {};
+  const excluded = Object.values(tracks).some(t => t.solo) && !own.solo;
+  return {visible: !own.hidden && !excluded, audible: !own.muted && !excluded};
+}

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

@@ -0,0 +1,2 @@
+/** @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

@@ -0,0 +1,50 @@
+import {parseColor, mixColor} from "./color-value.mjs";
+function ease(t, easing) {
+	switch (easing) {
+		case "linear":
+			return t;
+		case "easeIn":
+			return t * t;
+		case "easeOut":
+			return 1 - (1 - t) ** 2;
+		case "easeInOut":
+			return t < 0.5 ? 2 * t * t : 1 - (-2 * t + 2) ** 2 / 2;
+		case "hold":
+			return 0;
+	}
+}
+
+
+/** @param {any} definition @param {number} time @param {"color" | "discrete"} [interpolation] @returns {any} */
+export function sampleTrack(definition, time, interpolation) {
+	if (!Number.isFinite(time)) throw new Error("Motion time must be finite");
+	const { default: initial, keyframes = [] } = definition;
+	if (keyframes.length === 0) return initial;
+	const color = interpolation !== "discrete" && definition.type !== "discrete" && typeof initial === "string" && !!parseColor(initial);
+	const discrete = interpolation === "discrete" || definition.type === "discrete" || typeof initial === "boolean" ||
+		(typeof initial === "string" && !color) || (Array.isArray(initial) && (!initial.length || typeof initial[0] === "string"));
+	if (time < keyframes[0].at) return discrete ? initial : keyframes[0].value;
+	if (time === keyframes[0].at) return keyframes[0].value;
+	if (time >= keyframes[keyframes.length - 1].at)
+		return keyframes[keyframes.length - 1].value;
+	let lo = 0;
+	let hi = keyframes.length - 1;
+	while (hi - lo > 1) {
+		const mid = (lo + hi) >>> 1;
+		if (keyframes[mid].at <= time) lo = mid;
+		else hi = mid;
+	}
+	const a = keyframes[lo];
+	const b = keyframes[hi];
+	if (discrete) return a.value;
+	const amount = ease((time - a.at) / (b.at - a.at), b.easing ?? "linear");
+	if (typeof a.value === "number" && typeof b.value === "number") {
+		return (a.value + (b.value - a.value) * amount);
+	}
+	if (color) return mixColor(a.value, b.value, amount);
+	const start = a.value;
+	const end = b.value;
+	return Object.freeze(
+		start.map((v, i) => v + (end[i] - v) * amount),
+	);
+}

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

@@ -0,0 +1,121 @@
+import { parseColor } from "./color.js";
+import { sampleTrack } 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";
+export interface Keyframe<T extends MotionValue = MotionValue> {
+	/** Scene time in seconds; nonnegative and strictly increasing within a track. */
+	readonly at: number;
+	/** Must match the default’s type and tuple length. */
+	readonly value: T;
+	/** Easing into this keyframe from the previous one. Default: linear. */
+	readonly easing?: Easing;
+}
+export interface TrackDefinition<T extends MotionValue = MotionValue> {
+	/** Value without keys. For continuous tracks, add a key at 0 to define the starting value. */
+	readonly default: T;
+	/** Override inference for text/choices that resemble color literals. */
+	readonly type?: "color" | "discrete";
+	/** Holds the last value after the final key; no automatic looping. */
+	readonly keyframes?: readonly Keyframe<T>[];
+}
+export interface Motion<T extends MotionValue = MotionValue> {
+	readonly [TRACK]: true;
+	readonly definition: TrackDefinition<T>;
+}
+type Widen<T extends MotionValue> = T extends number ? number : T extends boolean ? boolean
+	: T extends string ? string : T extends readonly [] ? readonly string[]
+	: T extends readonly number[] ? { readonly [K in keyof T]: number } : readonly string[];
+export type MotionDefinition = Readonly<Record<string, TrackDefinition>>;
+export type Motions<D extends MotionDefinition> = {
+	readonly [K in keyof D]: Motion<Widen<D[K]["default"]>>;
+};
+
+function copyValue(value: MotionValue, label: string): MotionValue {
+	if (typeof value === "boolean" || typeof value === "string") return value;
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (Array.isArray(value) && (value.every(v => typeof v === "string") ||
+		(value.length > 0 && value.every(v => typeof v === "number" && Number.isFinite(v)))))
+		return Object.freeze([...value]);
+	throw new Error(`${label}: expected a finite number, numeric tuple, string, boolean or string array`);
+}
+function shape(value: MotionValue): string {
+	return Array.isArray(value) ? (value.length && typeof value[0] === "number" ? `vector:${value.length}` : "choices") : typeof value;
+}
+
+/** Declare reusable keyframes; bind a track directly to a compatible JSX prop.
+ * The variable name is arbitrary. CLI Strict uses references, not sampleMotion calls.
+ * @example
+ * const motion = defineMotion({ lap: { default: 0, keyframes: [{ at: 0, value: 0 }, { at: 4, value: 1 }] } });
+ * // <Text path={{ shape: "ellipse", radius: [180, 120], progress: motion.lap }}>ONE WHOLE STRING</Text>
+ */
+export function defineMotion<const D extends MotionDefinition>(
+	definition: D,
+): Motions<D> {
+	const result: Record<string, Motion> = Object.create(null);
+	for (const [name, track] of Object.entries(definition)) {
+		const initial = copyValue(track.default, `${name}.default`);
+		if (track.type !== undefined && track.type !== "color" && track.type !== "discrete") throw new Error(`${name}: invalid motion type`);
+		if (track.type === "color" && !parseColor(initial)) throw new Error(`${name}.default: expected a color`);
+		let previous = -Infinity;
+		const keyframes = (track.keyframes ?? []).map((key, i) => {
+			const label = `${name}.keyframes[${i}]`;
+			if (!Number.isFinite(key.at) || key.at < 0 || key.at <= previous) {
+				throw new Error(
+					`${label}: times must be finite, nonnegative and strictly increasing`,
+				);
+			}
+			previous = key.at;
+			const value = copyValue(key.value, label);
+			if (shape(value) !== shape(initial)) throw new Error(`${label}: value must match the default's type/tuple shape`);
+			if ((track.type === "color" || (track.type !== "discrete" && typeof initial === "string" && parseColor(initial))) && !parseColor(value))
+				throw new Error(`${label}: expected a color`);
+			if (
+				key.easing !== undefined &&
+				!["linear", "easeIn", "easeOut", "easeInOut", "hold"].includes(
+					key.easing,
+				)
+			) {
+				throw new Error(`${label}: unsupported easing ${key.easing}`);
+			}
+			return Object.freeze({
+				at: key.at,
+				value,
+				...(key.easing === undefined ? {} : { easing: key.easing }),
+			});
+		});
+		result[name] = Object.freeze({
+			[TRACK]: true as const,
+			definition: Object.freeze({
+				default: initial,
+				...(track.type ? { type: track.type } : {}),
+				keyframes: Object.freeze(keyframes),
+			}),
+		});
+	}
+	return Object.freeze(result) as Motions<D>;
+}
+
+export function isMotion(value: unknown): value is Motion {
+	return typeof value === "object" && value !== null && TRACK in value;
+}
+
+/** Stateless sampling shared by rendering and editing. */
+export function sampleMotion<T extends MotionValue>(motion: Motion<T>, time: number, interpolation?: "color" | "discrete"): T {
+  return sampleTrack(motion.definition, time, interpolation) as T;
+}
+
+/** Plain serializable data for inspectors; source rewriting is a separate future layer. */
+export function describeMotion(
+	motions: Readonly<Record<string, Motion>>,
+): MotionDefinition {
+	return Object.freeze(
+		Object.fromEntries(
+			Object.entries(motions).map(([name, motion]) => [
+				name,
+				motion.definition,
+			]),
+		),
+	);
+}