@osmo.inc/cli 0.1.15

package/runtime/packages/scene/scripts/validate-strict.mjs

@@ -0,0 +1,246 @@
+// Static authoring contract, not a security sandbox. Runtime/type validation is separate.
+import fs from 'node:fs';
+import path from 'node:path';
+import ts from 'typescript';
+import {isClipPrimitive} from '../src/clip.mjs';
+import {readGroupLabel, readGroupPlayback, readSceneTracks} from '../src/metadata.mjs';
+export function resolveGroupImport(file, specifier) {
+    if (!specifier.startsWith('./') && !specifier.startsWith('../')) throw new Error('Group imports must use relative local TSX paths');
+    const candidate = path.resolve(path.dirname(file), specifier.endsWith('.tsx') ? specifier : specifier.endsWith('.js') ? specifier.slice(0, -3) + '.tsx' : specifier + '.tsx');
+    if (!candidate.endsWith('.tsx')) throw new Error('Group imports must reference .tsx files');
+    return fs.realpathSync(candidate);
+}
+function projectDirectory(file) {
+    let dir = path.dirname(file);
+    while (true) {
+        if (fs.existsSync(path.join(dir, '.osmo/project.json'))) return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir) return path.dirname(file);
+        dir = parent;
+    }
+}
+export function validate(file, mode, options = {}) {
+    file = fs.realpathSync(file);
+    const root = options.root ?? projectDirectory(file);
+    const stack = options.stack ?? [];
+    if (stack.includes(file)) return { ok:false, errors:[`Cyclic Group import: ${[...stack,file].map(p=>path.basename(p)).join(' → ')}`], bytes:0 };
+    if (stack.length > 32) return {ok:false,errors:['Group import nesting exceeds 32 files'],bytes:0};
+    const text = options.text ?? options.sources?.[file] ?? fs.readFileSync(file, 'utf8');
+    const ast = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const errors = [];
+    const fail = (n, msg) => { const p = ast.getLineAndCharacterOfPosition(n.getStart(ast)); errors.push(`${p.line + 1}:${p.character + 1} ${msg}`); };
+    for (const d of ast.parseDiagnostics)
+        errors.push(ts.flattenDiagnosticMessageText(d.messageText, '\n'));
+    const allowed = new Set(['Scene', 'Camera', 'Group', 'Rect', 'Path', 'Text', 'Image', 'Video', 'Audio', 'Model', 'Surface', 'Fragment', 'defineMotion', 'defineKnobs', 'Shader', 'sampleMotion', 'describeMotion', 'blur', 'grain']);
+    allowed.add('defineEffect');
+    const importedGroups = new Set(), sourceIds = new Set(), effects = new Set();
+    const tracks = new Map();
+    const knobSets = new Set();
+    const literal = n => ts.isStringLiteral(n) || ts.isNumericLiteral(n) || [ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.FalseKeyword, ts.SyntaxKind.NullKeyword].includes(n.kind) || ts.isPrefixUnaryExpression(n) && [ts.SyntaxKind.PlusToken, ts.SyntaxKind.MinusToken].includes(n.operator) && ts.isNumericLiteral(n.operand);
+    function metadataLiteral(n) {
+        if (n && (ts.isJsxExpression(n) || ts.isParenthesizedExpression(n))) return metadataLiteral(n.expression);
+        if (n && ts.isStringLiteral(n)) return n.text;
+        if (n?.kind === ts.SyntaxKind.TrueKeyword) return true;
+        if (n?.kind === ts.SyntaxKind.FalseKeyword) return false;
+        if (n && ts.isObjectLiteralExpression(n)) return Object.fromEntries(n.properties.map(p => {
+            if (!ts.isPropertyAssignment(p) || ts.isComputedPropertyName(p.name)) throw new Error('Labels require explicit literal properties');
+            return [p.name.text, metadataLiteral(p.initializer)];
+        }));
+        throw new Error('Editor metadata must use static string/boolean literals and literal objects');
+    }
+    function value(n, refs = true) {
+        if (literal(n))
+            return;
+        if (ts.isArrayLiteralExpression(n)) {
+            n.elements.forEach(e => value(e, refs));
+            return;
+        }
+        if (ts.isObjectLiteralExpression(n)) {
+            for (const p of n.properties) {
+                if (!ts.isPropertyAssignment(p) || ts.isComputedPropertyName(p.name))
+                    fail(p, 'Only explicit literal object properties are allowed');
+                else
+                    value(p.initializer, refs);
+            }
+            return;
+        }
+        if (refs && ts.isIdentifier(n) && knobSets.has(n.text)) return;
+        if (refs && ts.isPropertyAccessExpression(n) && ts.isIdentifier(n.expression) && tracks.get(n.expression.text)?.has(n.name.text))
+            return;
+        if (refs && ts.isCallExpression(n) && ts.isIdentifier(n.expression) && (['blur', 'grain'].includes(n.expression.text)||effects.has(n.expression.text)) && n.arguments.length <= 1) {
+            if(n.arguments[0])value(n.arguments[0]);
+            return;
+        }
+        fail(n, 'Strict accepts literals, literal collections, declared motion/knob references, declared effects, blur and grain only');
+    }
+    for (const st of ast.statements) {
+        if (ts.isImportDeclaration(st)) {
+            if (st.moduleSpecifier.text !== '@osmo/scene') {
+                const clause = st.importClause;
+                if (!clause?.name || clause.namedBindings || clause.isTypeOnly) {
+                    fail(st, 'Reusable Groups use a default import from a local TSX file');
+                    continue;
+                }
+                importedGroups.add(clause.name.text);
+                try {
+                    const imported = resolveGroupImport(file, st.moduleSpecifier.text);
+                    const relative = path.relative(root, imported);
+                    if (relative === '..' || relative.startsWith('..' + path.sep) || path.isAbsolute(relative)) throw new Error('Group imports must stay inside the project');
+                    const result = validate(imported, mode, {root, stack:[...stack,file], group:true, sources:options.sources});
+                    for (const error of result.errors) fail(st, `${path.relative(root, imported)}: ${error}`);
+                } catch (error) { fail(st, error.message); }
+                continue;
+            }
+            const b = st.importClause?.namedBindings;
+            if (!b || !ts.isNamedImports(b))
+                fail(st, 'Use named imports');
+            else
+                for (const e of b.elements) {
+                    if (e.propertyName)
+                        fail(e, 'Import aliases are not allowed');
+                    if (!st.importClause.isTypeOnly && !e.isTypeOnly && !allowed.has(e.name.text))
+                        fail(e, `Unsupported import ${e.name.text}`);
+                }
+        }
+        if (mode === 'strict' && ts.isVariableStatement(st)) {
+            if (!(st.declarationList.flags & ts.NodeFlags.Const))
+                fail(st, 'Only const motion/knob/effect declarations are allowed');
+            for (const d of st.declarationList.declarations) {
+                const call = d.initializer;
+                if (!ts.isIdentifier(d.name) || !call || !ts.isCallExpression(call) || !ts.isIdentifier(call.expression) || !['defineMotion','defineKnobs','defineEffect'].includes(call.expression.text) || (call.expression.text !== 'defineKnobs' ? call.arguments.length !== 1 : call.arguments.length < 1 || call.arguments.length > 2) || !ts.isObjectLiteralExpression(call.arguments[0])) {
+                    fail(d, 'Variables may only name defineMotion, defineKnobs or defineEffect declarations');
+                    continue;
+                }
+                value(call.arguments[0], false);
+                if(call.expression.text==='defineEffect') {
+                    effects.add(d.name.text);
+                    const src=call.arguments[0].properties.find(p=>p.name?.text==='src')?.initializer;
+                    if(src&&(!ts.isStringLiteral(src)||!src.text.endsWith('.wgsl')||path.isAbsolute(src.text)||/^[a-z]+:/i.test(src.text)))fail(src,'Effect.src must be a static relative local .wgsl path');
+                }
+                if (call.arguments[1]) value(call.arguments[1], false);
+                if (call.expression.text === 'defineKnobs') knobSets.add(d.name.text);
+                if(call.expression.text!=='defineEffect') tracks.set(d.name.text, new Set(call.arguments[0].properties.filter(ts.isPropertyAssignment).map(p => p.name.text)));
+            }
+        }
+        else if (mode === 'strict' && !ts.isImportDeclaration(st) && !ts.isExportAssignment(st) && !ts.isEmptyStatement(st))
+            fail(st, 'Strict permits imports, const defineMotion/defineKnobs/defineEffect declarations, and export default JSX only');
+    }
+    function jsx(n, parent = null) {
+        if (ts.isParenthesizedExpression(n)) {
+            jsx(n.expression, parent);
+            return;
+        }
+        if (ts.isJsxFragment(n)) {
+            n.children.forEach(c => child(c, parent));
+            return;
+        }
+        if (!ts.isJsxElement(n) && !ts.isJsxSelfClosingElement(n)) {
+            fail(n, 'Scene structure must be explicit JSX');
+            return;
+        }
+        const el = ts.isJsxElement(n) ? n.openingElement : n;
+        const tag = el.tagName.getText(ast);
+        const clip = isClipPrimitive(tag) || importedGroups.has(tag);
+        const track = el.attributes.properties.find(a => ts.isJsxAttribute(a) && a.name.text === 'track');
+        if (options.requireTracks && parent === 'Scene' && clip && !track)
+            fail(el, `${tag}: root clips require track. Open Studio in interactive mode to assign tracks to an existing scene.`);
+        if (track) {
+            if (!clip || parent !== 'Scene') fail(track, 'track belongs to root clips only; nested elements use their parent clip');
+            const v = track.initializer && (ts.isJsxExpression(track.initializer) ? track.initializer.expression : track.initializer);
+            const lane = v && ts.isNumericLiteral(v) ? Number(v.text) : NaN;
+            if (!Number.isInteger(lane) || lane < 0 || lane > 99) fail(track, 'track must be a literal integer from 0 to 99');
+        }
+        if ((!allowed.has(tag) && !importedGroups.has(tag)) || ['defineMotion', 'defineKnobs', 'defineEffect', 'sampleMotion', 'describeMotion', 'blur', 'grain'].includes(tag))
+            fail(el, 'Use public visual primitives only');
+        if (importedGroups.has(tag) && ts.isJsxElement(n) && n.children.some(c => !ts.isJsxText(c) || c.text.trim()))
+            fail(n, 'Animation instances cannot replace children; edit the original Group file');
+        for (const a of el.attributes.properties) {
+            if (!ts.isJsxAttribute(a)) {
+                fail(a, 'Spreads are forbidden in Strict');
+                continue;
+            }
+            if (importedGroups.has(tag) && ['knobs', 'children'].includes(a.name.text))
+                fail(a, 'Animation instances customize values, not knob definitions or children');
+            if (a.name.text === 'label' || a.name.text === 'tracks') {
+                try {
+                    if (a.name.text === 'label') {
+                        if (tag !== 'Group' && !importedGroups.has(tag)) throw new Error('label belongs to Groups only');
+                        readGroupLabel(metadataLiteral(a.initializer));
+                    } else {
+                        if (tag !== 'Scene') throw new Error('tracks metadata belongs to Scene only');
+                        readSceneTracks(metadataLiteral(a.initializer));
+                    }
+                } catch (error) { fail(a, error.message); }
+            }
+            if (['hidden', 'solo'].includes(a.name.text)) {
+                try {
+                    if (tag !== 'Group' && !importedGroups.has(tag)) throw new Error('hidden and solo belong to Groups only');
+                    readGroupPlayback({[a.name.text]: a.initializer ? metadataLiteral(a.initializer) : true});
+                } catch (error) { fail(a, error.message); }
+            }
+            if (['id','start','duration','track'].includes(a.name.text) && a.initializer) {
+                const v = ts.isJsxExpression(a.initializer) ? a.initializer.expression : a.initializer;
+                if (v) value(v, false);
+            }
+            if (a.name.text === 'id') {
+                const id = a.initializer && (ts.isJsxExpression(a.initializer) ? a.initializer.expression : a.initializer);
+                if (!id || !ts.isStringLiteral(id) || !id.text.trim()) fail(a, 'id must be a nonempty literal string');
+                else if (sourceIds.has(id.text)) fail(a, 'IDs must be unique within their source file');
+                else sourceIds.add(id.text);
+            }
+            if (tag === 'Shader' && a.name.text === 'src') {
+                const src = a.initializer && (ts.isJsxExpression(a.initializer) ? a.initializer.expression : a.initializer);
+                if (!src || !ts.isStringLiteral(src) || !src.text.trim() || /^[a-z]+:/i.test(src.text) || path.isAbsolute(src.text) || !/\.wgsl$/i.test(src.text))
+                    fail(a, 'Shader.src must be a static relative local .wgsl path');
+            }
+            if (tag === 'Path' && a.name.text === 'd' && a.initializer) {
+                const d = ts.isJsxExpression(a.initializer) ? a.initializer.expression : a.initializer;
+                if (!d || !ts.isStringLiteral(d)) fail(a, 'Path.d must be a static SVG string literal');
+            }
+            if (a.initializer) {
+                if (ts.isJsxExpression(a.initializer)) {
+                    if (a.initializer.expression)
+                        value(a.initializer.expression);
+                }
+                else
+                    value(a.initializer);
+            }
+        }
+        if (ts.isJsxElement(n))
+            n.children.forEach(c => child(c, tag === "Fragment" ? parent : tag));
+    }
+    function child(n, parent) { if (ts.isJsxText(n))
+        return; if (ts.isJsxExpression(n)) {
+        if (n.expression)
+            value(n.expression);
+        return;
+    } jsx(n, parent); }
+    if (mode === 'strict') {
+        const exports = ast.statements.filter(ts.isExportAssignment);
+        if (exports.length !== 1) errors.push('Export exactly one default Scene or Group');
+        for (const st of exports) {
+            let n = st.expression;
+            while (ts.isParenthesizedExpression(n)) n = n.expression;
+            const tag = ts.isJsxElement(n) ? n.openingElement.tagName.getText(ast) : ts.isJsxSelfClosingElement(n) ? n.tagName.getText(ast) : '';
+            if (!options.group && !['Scene','Group'].includes(tag)) fail(st, 'The entry must export a Scene or Group');
+            if (options.group && !['Scene','Group'].includes(tag)) fail(st, 'Reusable files must export a Scene (or legacy Group)');
+            jsx(st.expression);
+        }
+    }
+    function audit(n) {
+        if (ts.isImportEqualsDeclaration(n))
+            fail(n, 'Import-equals is forbidden');
+        if (ts.isCallExpression(n) && n.expression.kind === ts.SyntaxKind.ImportKeyword)
+            fail(n, 'Dynamic imports are forbidden');
+        if (ts.isIdentifier(n) && ['require', 'eval', 'Function', 'process', 'globalThis', 'fetch', 'WebSocket', 'Date'].includes(n.text))
+            fail(n, 'Submitted animation must be deterministic and self-contained');
+        ts.forEachChild(n, audit);
+    }
+    audit(ast);
+    return { ok: errors.length === 0, errors: errors.slice(0, 40), bytes: Buffer.byteLength(text) };
+}
+if (process.argv[1] === new URL(import.meta.url).pathname) {
+    const result = validate(path.resolve(process.argv[2]), process.argv[3] ?? "strict");
+    console.log(JSON.stringify(result));
+    process.exitCode = result.ok ? 0 : 1;
+}

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

@@ -0,0 +1,14 @@
+/** @param {{start?: unknown, duration?: unknown, track?: unknown}} props
+ * @param {number} parentDuration @param {number} fps @param {string} label */
+export function clipTiming(props: {
+    start?: unknown;
+    duration?: unknown;
+    track?: unknown;
+}, parentDuration: number, fps: number, label: string): {
+    start: number;
+    duration: number;
+    track: number | undefined;
+};
+export const clipPrimitives: readonly string[];
+export const clipFields: readonly string[];
+export function isClipPrimitive(name: string): boolean;

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

@@ -0,0 +1,15 @@
+// Shared by evaluation, Strict validation, outline inspection and source editing.
+export const clipPrimitives = Object.freeze(['Group', 'Rect', 'Path', 'Text', 'Image', 'Video', 'Audio', 'Shader', 'Model', 'Composition']);
+export const clipFields = Object.freeze(['id', 'track', 'start', 'duration']);
+export const isClipPrimitive = (/** @type {string} */ name) => clipPrimitives.some(tag => tag.toLowerCase() === name.toLowerCase());
+
+/** @param {{start?: unknown, duration?: unknown, track?: unknown}} props
+ * @param {number} parentDuration @param {number} fps @param {string} label */
+export function clipTiming(props, parentDuration, fps, label) {
+  const start = props.start ?? 0, duration = props.duration ?? Math.max(parentDuration - Number(start), 1 / fps);
+  if (typeof start !== 'number' || !Number.isFinite(start) || start < 0) throw new Error(`${label}.start: expected a finite nonnegative number`);
+  if (typeof duration !== 'number' || !Number.isFinite(duration) || duration <= 0) throw new Error(`${label}.duration: expected a positive finite number`);
+  const track = props.track;
+  if (track !== undefined && (typeof track !== 'number' || !Number.isInteger(track) || track < 0 || track > 99)) throw new Error(`${label}.track: expected an integer from 0 to 99`);
+  return {start, duration, track};
+}

package/runtime/packages/scene/src/color-value.d.mts

@@ -0,0 +1,5 @@
+/** sRGBA authoring colors. Interpolation is in linear light, premultiplied by alpha. */
+/** @param {unknown} value @returns {readonly [number, number, number, number] | undefined} */
+export function parseColor(value: unknown): readonly [number, number, number, number] | undefined;
+/** @param {string} a @param {string} b @param {number} t */
+export function mixColor(a: string, b: string, t: number): string;

package/runtime/packages/scene/src/color-value.mjs

@@ -0,0 +1,19 @@
+/** sRGBA authoring colors. Interpolation is in linear light, premultiplied by alpha. */
+/** @param {unknown} value @returns {readonly [number, number, number, number] | undefined} */
+export function parseColor(value) {
+	if (value === "transparent") return [0, 0, 0, 0];
+	if (typeof value !== "string" || !/^#(?:[\da-f]{3,4}|[\da-f]{6}|[\da-f]{8})$/i.test(value)) return;
+	let hex = value.slice(1);
+	if (hex.length <= 4) hex = [...hex].map(c => c + c).join("");
+	if (hex.length === 6) hex += "ff";
+	return /** @type {[number, number, number, number]} */ ([0, 2, 4, 6].map(i => parseInt(hex.slice(i, i + 2), 16) / 255));
+}
+/** @param {string} a @param {string} b @param {number} t */
+export function mixColor(a, b, t) {
+	const x = parseColor(a), y = parseColor(b);
+	const linear = (v) => v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+	const srgb = (v) => v <= 0.0031308 ? v * 12.92 : 1.055 * v ** (1 / 2.4) - 0.055;
+	const alpha = x[3] + (y[3] - x[3]) * t;
+	const values = [0, 1, 2].map(i => srgb(alpha > 0 ? (linear(x[i]) * x[3] * (1 - t) + linear(y[i]) * y[3] * t) / alpha : 0));
+	return "#" + [...values, alpha].map(v => Math.round(Math.min(1, Math.max(0, v)) * 255).toString(16).padStart(2, "0")).join("");
+}

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

@@ -0,0 +1 @@
+export { parseColor, mixColor } from "./color-value.mjs";

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

@@ -0,0 +1,213 @@
+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);
+}`,
+});