@osmo.inc/cli 0.1.18 → 0.1.19

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

@@ -1,213 +0,0 @@
-import { isKnobRef, resolveKnob, type KnobRef } from "./knobs.js";
-import { isMotion, sampleMotion, type Motion, type MotionValue, type TrackDefinition } from "./motion.js";
-import { parseColor } from "./color.js";
-import type { UniformValue } from "./elements.js";
-
-import { validateKnobSchema, validateKnobValue as validateValue } from "./knob-schema.js";
-import type { Knobs, KnobGroup, KnobValues, KnobValue } from "./knob-schema.js";
-export type { Knob, KnobGroup, Knobs, KnobValues } from "./knob-schema.js";
-
-const EFFECT = Symbol("osmo.effect");
-/** Knob overrides; values can be literals, motion tracks, or references from a containing Group. */
-export type EffectBindings<K extends Knobs> = { readonly [P in keyof K]?: KnobValue<K[P]> | Motion<KnobValue<K[P]>> | KnobRef<KnobValue<K[P]>> };
-/** Extra transparent rendering area in pixels; does not change layout or target dimensions. */
-export type EffectPadding = number | Readonly<{ top: number; right: number; bottom: number; left: number }>;
-export interface EffectDefinition<K extends Knobs = Knobs> {
-	/** Rendering space only; never changes layout. Declare 0 for bounds-preserving effects. */
-	padding: EffectPadding | ((values: KnobValues<K>) => EffectPadding);
-	/** Local .wgsl path; implement effect(uv: vec2f, time: f32) -> vec4f and sample eng_input(uv). */
-	src?: string;
-	/** Inline source is useful for small reusable built-in effects. Supply src or code, not both. */
-	code?: string;
-	/** Typed controls. Default uniform mapping: number→f32, boolean→0/1, color→RGBA, select→index, multiselect→bitmask. */
-	knobs: K;
-	groups?: Readonly<Record<string, KnobGroup>>;
-	/** Optional mapping for text, presets or derived uniforms; required for text knobs. Library API, not CLI Strict. */
-	uniforms?: (values: KnobValues<K>) => Readonly<Record<string, UniformValue>>;
-	/** Run the shader once per entry, in order, adding these uniforms to each run; a separable blur is two passes.
-	 * Padding is reserved once for the whole effect. Library API, at most 4 passes. */
-	passes?: readonly Readonly<Record<string, UniformValue>>[];
-}
-export interface EffectInstance {
-	readonly [EFFECT]: true;
-	readonly definition: EffectDefinition;
-	readonly sourceFile?: string;
-	readonly bindings: Readonly<Record<string, MotionValue | Motion | KnobRef>>;
-}
-export type EffectFactory<K extends Knobs> = ((values?: EffectBindings<K>) => EffectInstance) & {
-	readonly definition: EffectDefinition<K>;
-};
-export interface EvaluatedEffect {
-	padding: readonly [number, number, number, number];
-	src?: string;
-	code?: string;
-	sourceFile?: string;
-	uniforms: Readonly<Record<string, UniformValue>>;
-}
-function fail(message: string): never { throw new Error(`Effect: ${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); }
-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;
-}
-function normalizePadding(value: unknown): readonly [number, number, number, number] {
-	if (record(value)) keys(value, ["top", "right", "bottom", "left"], "padding");
-	const sides = typeof value === "number" ? [value, value, value, value] : record(value) ? [value.top, value.right, value.bottom, value.left] : [];
-	if (sides.length !== 4 || sides.some(v => !finite(v) || v < 0 || v > 16384))
-		fail("padding must be a nonnegative number or { top, right, bottom, left }, at most 16384 per side");
-	return Object.freeze(sides) as unknown as readonly [number, number, number, number];
-}
-/** Declare a custom effect factory; apply its instances through effects={[...]} in processing order.
- * CLI Strict supports literal defineEffect declarations. Callbacks remain library-only.
- * eng_input(uv) samples the preceding pass in original target coordinates; eng_box_size()
- * returns the unpadded size. Return straight-alpha sRGB. Declare enough padding for all displaced samples.
- * @example defineEffect({ src: "./tint.wgsl", padding: 0, knobs: { amount: { type: "number", default: 0.5, step: 0.1 } } })
- */
-export function defineEffect<const K extends Knobs>(definition: EffectDefinition<K>, sourceFile?: string): EffectFactory<K> {
-	if (!record(definition)) fail("expected a definition");
-	keys(definition, ["src", "code", "knobs", "groups", "uniforms", "padding", "passes"], "definition");
-	if (definition.passes !== undefined && (!Array.isArray(definition.passes) || !definition.passes.length || definition.passes.length > 4 || !definition.passes.every(record)))
-		fail("passes must be 1 to 4 sets of named uniforms");
-	if (!!definition.src === !!definition.code) fail("supply exactly one of src or code");
-	if (definition.src && (!/\.wgsl$/i.test(definition.src) || /^[a-z]+:/i.test(definition.src))) fail("src must be a local .wgsl path");
-	if (definition.code !== undefined && typeof definition.code !== "string") fail("code must be WGSL text");
-	validateKnobSchema(definition.knobs, definition.groups);
-	if (definition.uniforms !== undefined && typeof definition.uniforms !== "function") fail("uniforms must be a mapping function");
-	if (definition.padding === undefined) fail("padding is required: declare 0 for bounds-preserving effects, or derive it from knobs");
-	if (typeof definition.padding !== "function") normalizePadding(definition.padding);
-	for (const [name, knob] of Object.entries(definition.knobs))
-		if (knob.type === "multiselect" && Object.keys(knob.options).length > 24 && !definition.uniforms)
-			fail(`${name}: more than 24 choices needs a uniform mapping`);
-	// Copy metadata: modifying the caller's objects cannot change a loaded effect.
-	const frozen = freeze({ ...JSON.parse(JSON.stringify({ ...definition, uniforms: undefined })), ...(definition.uniforms ? { uniforms: definition.uniforms } : {}), ...(typeof definition.padding === "function" ? { padding: definition.padding } : {}) }) as EffectDefinition<K>;
-	const factory = (values: EffectBindings<K> = {}): EffectInstance => {
-		if (!record(values)) fail("expected named knob values");
-		const bindings: Record<string, MotionValue | Motion | KnobRef> = Object.create(null);
-		for (const [name, value] of Object.entries(values)) {
-			if (!Object.hasOwn(frozen.knobs, name)) fail(`unknown knob ${name}`);
-			if (isKnobRef(value)) { bindings[name] = value; continue; }
-			if (isMotion(value)) {
-				for (const v of [value.definition.default, ...(value.definition.keyframes ?? []).map(k => k.value)]) validateValue(frozen.knobs[name], v, name);
-			} else validateValue(frozen.knobs[name], value, name);
-			bindings[name] = Array.isArray(value) ? Object.freeze([...value]) : value as MotionValue | Motion;
-		}
-		return Object.freeze({ [EFFECT]: true as const, definition: frozen as EffectDefinition, bindings: Object.freeze(bindings), ...(sourceFile ? { sourceFile } : {}) });
-	};
-	return Object.freeze(Object.assign(factory, { definition: frozen }));
-}
-export function isEffect(value: unknown): value is EffectInstance { return record(value) && EFFECT in value; }
-export function describeEffect(instance: EffectInstance, time = 0, resolveBinding: (value: unknown) => unknown = v => isKnobRef(v) ? resolveKnob(v, []) : v) {
-	if (!isEffect(instance)) fail("effects must contain effect instances");
-	const { definition, bindings } = instance;
-	const values: Record<string, MotionValue> = Object.create(null);
-	const tracks: Record<string, TrackDefinition> = Object.create(null);
-	for (const [name, knob] of Object.entries(definition.knobs)) {
-		const binding = resolveBinding(bindings[name] ?? knob.default) as MotionValue | Motion;
-		values[name] = isMotion(binding) ? sampleMotion(binding, time, knob.type === "color" ? "color" : knob.type === "number" ? undefined : "discrete") : binding;
-		if (isMotion(binding)) tracks[name] = binding.definition;
-		validateValue(knob, values[name], name);
-	}
-	const visible = (when?: Readonly<Record<string, string | number | boolean>>) => !when || Object.entries(when).every(([key, value]) => values[key] === value);
-	const groups = definition.groups ?? {};
-	const visibleGroups: Record<string, boolean> = Object.create(null);
-	function groupVisible(name: string): boolean {
-		return 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(definition.knobs).map(([name, knob]) => [name,
-		visible(knob.visibleWhen) && (!knob.group || visibleGroups[knob.group])
-	]));
-	const padding = normalizePadding(typeof definition.padding === "function" ? definition.padding(values as KnobValues<Knobs>) : definition.padding);
-	return freeze({ padding, src: definition.src, knobs: definition.knobs, groups, values, tracks, visibleGroups, visibleKnobs });
-}
-export function evaluateEffects(effects: unknown, time: number, sourceFile?: string, resolveBinding?: (value: unknown) => unknown): EvaluatedEffect[] {
-	if (effects === undefined) return [];
-	if (!Array.isArray(effects) || effects.length > 32) fail("effects must be an array of at most 32 instances");
-	const evaluated = effects.flatMap((instance: EffectInstance) => {
-		const { values, padding } = describeEffect(instance, time, resolveBinding);
-		const def = instance.definition;
-		let uniforms: Readonly<Record<string, UniformValue>>;
-		if (def.uniforms) uniforms = def.uniforms(values as KnobValues<Knobs>);
-		else {
-			const mapped: Record<string, UniformValue> = Object.create(null);
-			for (const [name, knob] of Object.entries(def.knobs)) {
-				const v = values[name];
-				switch (knob.type) {
-					case "number": mapped[name] = v as number; break;
-					case "boolean": mapped[name] = v ? 1 : 0; break;
-					case "color": mapped[name] = parseColor(v)!; break;
-					case "select": mapped[name] = Object.keys(knob.options).indexOf(v as string); break;
-					case "multiselect": mapped[name] = (v as string[]).reduce((mask, value) => mask + 2 ** Object.keys(knob.options).indexOf(value), 0); break;
-					case "text": fail(`${name}: text needs an explicit uniforms mapping`);
-				}
-			}
-			uniforms = mapped;
-		}
-		if (!record(uniforms)) fail("uniforms mapping must return named numeric values");
-		// The first pass reserves the effect's padding; later passes work inside it.
-		return (def.passes ?? [{}]).map((extra, pass) => {
-			const all = { ...uniforms, ...extra };
-			for (const [name, value] of Object.entries(all)) {
-				const parts = Array.isArray(value) ? value : [value];
-				if (!/^[a-zA-Z][a-zA-Z0-9_]*$/.test(name) || (Array.isArray(value) && (parts.length < 2 || parts.length > 4)) || parts.some(n => !finite(n) || !Number.isFinite(Math.fround(n)))) fail(`invalid uniform ${name}`);
-			}
-			return { padding: pass === 0 ? padding : NO_PADDING, ...(def.src ? { src: def.src } : { code: def.code! }), sourceFile: instance.sourceFile ?? sourceFile, uniforms: all };
-		});
-	});
-	if (evaluated.length > 32) fail("effects expand to more than 32 passes");
-	return evaluated;
-}
-const NO_PADDING = Object.freeze([0, 0, 0, 0]) as unknown as readonly [number, number, number, number];
-
-/** Effects sample only their input image, never the scene behind the target. */
-export const EFFECT_INPUT = `
-fn eng_input(uv: vec2f) -> vec4f {
-  let padded = (uv * ENG_EFFECT_RECT.zw + ENG_EFFECT_RECT.xy) / ENG_EFFECT_SIZE;
-  if any(padded < vec2f(0.0)) || any(padded > vec2f(1.0)) { return vec4f(0.0); }
-  return eng_backdrop(padded);
-}
-`;
-/** Blur with automatically derived padding. radius is pixels (default 8); animatable.
- * @example <Text effects={[blur({ radius: 5 }), grain({ amount: 0.03 })]}>Soft focus</Text>
- */
-export const blur = defineEffect({
-	padding: ({ radius }) => Math.max(0, radius) * 2,
-	knobs: { radius: { type: "number", default: 8, min: 0, max: 64, step: 0.5 } },
-	// Separable Gaussian, sigma = radius, reaching two sigmas: a horizontal run,
-	// then a vertical one. 33 closely spaced taps each stay smooth at large radii,
-	// where a single 2D grid of the same cost left visible steps.
-	passes: [{ horizontal: 1 }, { horizontal: 0 }],
-	code: `struct Uniforms { radius: f32, horizontal: f32 }
-fn effect(uv: vec2f, time: f32) -> vec4f {
-  if uniforms.radius <= 0.0 { return eng_input(uv); }
-  let axis = select(vec2f(0.0, 1.0), vec2f(1.0, 0.0), uniforms.horizontal > 0.5);
-  let spacing = axis * uniforms.radius / 8.0 / eng_box_size();
-  var sum = vec4f(0.0); var weight = 0.0;
-  for (var i: i32 = -16; i <= 16; i++) {
-    let d = f32(i) / 8.0; let w = exp(-0.5 * d * d);
-    let c = eng_input(uv + spacing * f32(i));
-    sum += vec4f(c.rgb * c.a, c.a) * w; weight += w;
-  }
-  return vec4f(sum.rgb / max(sum.a, 0.00001), sum.a / weight);
-}`,
-});
-/** Animated grain; amount defaults to 0.04. Preserves alpha and bounds; animatable.
- * @example <Group effects={[grain({ amount: 0.05 })]}><Text>Texture</Text></Group>
- */
-export const grain = defineEffect({
-	padding: 0,
-	knobs: { amount: { type: "number", default: 0.04, min: 0, max: 1, step: 0.01 } },
-	code: `struct Uniforms { amount: f32 }
-fn effect(uv: vec2f, time: f32) -> vec4f {
-  let c = eng_input(uv);
-  let p = floor(uv * eng_box_size());
-  let n = fract(sin(dot(p,vec2f(12.9898,78.233)) + floor(time*24.0)*17.1)*43758.5453)-0.5;
-  return vec4f(clamp(c.rgb + n*uniforms.amount,vec3f(0.0),vec3f(1.0)), c.a);
-}`,
-});