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

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}`);
 			}

package/runtime/packages/scene/src/text-animation.ts

@@ -0,0 +1,239 @@
+import type { Color, Vec2 } from "./elements.js";
+import type { Easing, MotionValue } from "./motion.js";
+import { sampleTrack, isEasing } from "./motion-sampling.mjs";
+import { parseColor } from "./color.js";
+import { blur, evaluateEffects, type EvaluatedEffect } from "./effects.js";
+
+/** Post-layout offsets; omitted properties keep their neutral value. */
+export interface TextAnimationStyle {
+  position?: Vec2;
+  z?: number;
+  rotation?: number;
+  scale?: number;
+  /** Pivot in unit-local pixels; omitted uses the unit's ink center. */
+  origin?: Vec2;
+  opacity?: number;
+  color?: Color;
+  /** Gaussian radius in pixels, 0–64. */
+  blur?: number;
+}
+export interface TextAnimation {
+  unit: "character" | "word" | "line";
+  /** Seconds between units, in reading/source order. Default: 0. */
+  stagger?: number;
+  /** Seconds before the first unit starts. Default: 0. */
+  delay?: number;
+  /** Seconds per unit. Default: 0.4. Use keyframes for multiple stages. */
+  duration?: number;
+  easing?: Easing;
+  from?: TextAnimationStyle;
+  to?: TextAnimationStyle;
+  /** Local seconds per unit; begin at 0. Replaces from/to/duration. */
+  keyframes?: readonly {
+    at: number;
+    value: TextAnimationStyle;
+    easing?: Easing;
+  }[];
+}
+export interface TextAnimationState {
+  position: Vec2;
+  z: number;
+  rotation: number;
+  scale: number;
+  origin?: Vec2;
+  opacity: number;
+  color: Color;
+  effects: EvaluatedEffect[];
+}
+export interface EvaluatedTextAnimation {
+  unit: TextAnimation["unit"];
+  /** UTF-8 ranges, matched against shaped clusters. Lines use visual line indices. */
+  ranges: readonly (readonly [number, number])[];
+  states: TextAnimationState[];
+}
+const properties = [
+  "position",
+  "z",
+  "rotation",
+  "scale",
+  "origin",
+  "opacity",
+  "color",
+  "blur",
+] as const;
+const fail = (message: string): never => {
+  throw new Error(`Text.animate: ${message}`);
+};
+function object(v: unknown): Record<string, unknown> {
+  if (!v || typeof v !== "object" || Array.isArray(v))
+    return fail("expected an object");
+  return v as Record<string, unknown>;
+}
+function finite(v: unknown, name: string, min = -1e6, max = 1e6): number {
+  if (typeof v !== "number" || !Number.isFinite(v) || v < min || v > max)
+    return fail(`${name} must be a finite number in ${min}..${max}`);
+  return v;
+}
+function easing(v: unknown): Easing {
+  if (
+    !isEasing(v)
+  )
+    return fail("unsupported easing");
+  return v as Easing;
+}
+function style(v: unknown): TextAnimationStyle {
+  const value = object(v);
+  for (const [key, x] of Object.entries(value)) {
+    if (!(properties as readonly string[]).includes(key))
+      fail(`unsupported per-unit property ${key}; layout belongs on Text`);
+    if (key === "position" || key === "origin") {
+      if (!Array.isArray(x) || x.length !== 2) fail(`${key} must be [x, y]`);
+      (x as unknown[]).forEach((n) => finite(n, key));
+    } else if (key === "color") {
+      if (!parseColor(x)) fail("color must be a hex color or transparent");
+    } else
+      finite(
+        x,
+        key,
+        key === "opacity" || key === "blur" ? 0 : -1e6,
+        key === "opacity" ? 1 : key === "blur" ? 64 : 1e6,
+      );
+  }
+  return value as TextAnimationStyle;
+}
+const bytes = (s: string) =>
+  Array.from(s).reduce(
+    (n, c) =>
+      n +
+      (c.codePointAt(0)! > 0xffff
+        ? 4
+        : c.charCodeAt(0) > 0x7ff
+          ? 3
+          : c.charCodeAt(0) > 0x7f
+            ? 2
+            : 1),
+    0,
+  );
+const segmenter = new Intl.Segmenter("en", { granularity: "grapheme" });
+export function evaluateTextAnimation(
+  input: unknown,
+  text: string,
+  time: number,
+  color: Color,
+): EvaluatedTextAnimation {
+  const a = object(input);
+  for (const name of Object.keys(a))
+    if (
+      ![
+        "unit",
+        "stagger",
+        "delay",
+        "duration",
+        "easing",
+        "from",
+        "to",
+        "keyframes",
+      ].includes(name)
+    )
+      fail(`unknown option ${name}`);
+  if (!["character", "word", "line"].includes(a.unit as string))
+    fail("unit must be character, word or line");
+  const unit = a.unit as TextAnimation["unit"];
+  const stagger = finite(a.stagger ?? 0, "stagger", 0),
+    delay = finite(a.delay ?? 0, "delay", 0);
+  const ease = easing(a.easing ?? "linear");
+  const neutral: TextAnimationStyle = {
+    position: [0, 0],
+    z: 0,
+    rotation: 0,
+    scale: 1,
+    opacity: 1,
+    color,
+    blur: 0,
+  };
+  let keys: { at: number; value: TextAnimationStyle; easing: Easing }[];
+  if (a.keyframes !== undefined) {
+    if (a.from !== undefined || a.to !== undefined || a.duration !== undefined)
+      fail("keyframes replace from/to/duration");
+    if (
+      !Array.isArray(a.keyframes) ||
+      a.keyframes.length < 2 ||
+      a.keyframes.length > 128
+    )
+      fail("expected 2–128 keyframes");
+    let previous = -1,
+      state = neutral;
+    keys = (a.keyframes as unknown[]).map((entry) => {
+      const key = object(entry);
+      if (Object.keys(key).some((k) => !["at", "value", "easing"].includes(k)))
+        fail("unknown keyframe property");
+      const at = finite(key.at, "keyframe.at", 0);
+      if (at <= previous || (previous === -1 && at !== 0))
+        fail("keyframes must start at 0 and increase strictly");
+      previous = at;
+      state = { ...state, ...style(key.value) };
+      return { at, value: state, easing: easing(key.easing ?? ease) };
+    });
+  } else {
+    const duration = finite(a.duration ?? 0.4, "duration", Number.EPSILON);
+    keys = [
+      { at: 0, value: { ...neutral, ...style(a.from ?? {}) }, easing: ease },
+      {
+        at: duration,
+        value: { ...neutral, ...style(a.to ?? {}) },
+        easing: ease,
+      },
+    ];
+  }
+  // An explicit origin is constant unless both endpoints supply it; never
+  // interpolate a pixel pivot against an unknown layout-dependent center.
+  const origin = keys.find((k) => k.value.origin)?.value.origin;
+  if (origin)
+    keys = keys.map((k) => ({
+      ...k,
+      value: { ...k.value, origin: k.value.origin ?? origin },
+    }));
+  const graphemes = Array.from(segmenter.segment(text));
+  if (graphemes.length > 512) fail("at most 512 graphemes per animated Text");
+  const spans =
+    unit === "word"
+      ? Array.from(text.matchAll(/\S+/gu), (m) => ({
+          index: m.index!,
+          segment: m[0],
+        }))
+      : graphemes;
+  const ranges = spans.map(
+    (s) =>
+      [
+        bytes(text.slice(0, s.index)),
+        bytes(text.slice(0, s.index + s.segment.length)),
+      ] as const,
+  );
+  const count = unit === "line" ? graphemes.length + 1 : ranges.length;
+  const states = Array.from({ length: count }, (_, i) => {
+    const value: Record<string, unknown> = {};
+    for (const name of properties) {
+      if (keys[0].value[name] === undefined) continue;
+      value[name] = sampleTrack(
+        {
+          default: keys[0].value[name],
+          keyframes: keys.map((k) => ({
+            at: k.at,
+            value: k.value[name] as MotionValue,
+            easing: k.easing,
+          })),
+        },
+        time - delay - i * stagger,
+      );
+    }
+    const { blur: radius, ...state } = value;
+    return {
+      ...state,
+      effects:
+        Number(radius) > 0
+          ? evaluateEffects([blur({ radius: Number(radius) })], time)
+          : [],
+    } as TextAnimationState;
+  });
+  return { unit, ranges: unit === "line" ? [] : ranges, states };
+}