@pixerate/flair 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1431 @@
+import { C as ControlValue, a as ControlDef } from './controls-DdXMbovi.js';
+export { c as ControlCheck, b as ControlType, T as TextureSettings, d as checkControlValue, e as coerceControlValue, f as componentCount, g as controlValue, h as describeValue, i as hexToRgb, j as humanise, k as imageUrls, l as isImageUrl, p as parseControls, r as rgbToHex } from './controls-DdXMbovi.js';
+export { B as BUILTIN_UNIFORMS, C as CompileError, b as CompileResult, a as CompileStatus, c as CompiledShader, F as FrameState, I as ImageLoadError, R as RendererStats, S as SVG_EDGE, d as ShaderCompileError, e as ShaderRenderer, T as TextureCache, f as TextureSource, V as VERTEX_SOURCE, g as applyTextureSettings, h as compileShader, i as createContext, j as drawFrame, k as formatCompileError, l as isSvgUrl, m as loadImage, p as parseCompileLog, n as preloadImages, r as releaseImages, o as resetGlCaches, s as sizeSvg, w as wrapSource } from './renderer-Oyynz-fs.js';
+import { C as Clock } from './clock-BhdXWH-n.js';
+export { M as ManualClock, j as jitter, p as pageHidden, r as realClock } from './clock-BhdXWH-n.js';
+export { D as DataKey, E as EASES, a as EaseName, b as STEP_MS, c as SVG_PICTURE, d as SvgAnimation, e as SvgBox, f as SvgElementFrame, S as SvgMotion, g as defaultDataKey, l as lerpAttr, h as lerpData, s as stepData, i as stepProgress, j as stepStart, k as svgFrame, m as svgMotionIssues, n as svgOpeningTag } from './motion-D0TVv2CF.js';
+export { SvgPlayer, SvgPlayerOptions, SvgView, SvgViewOptions, parseSvg, svgDuration, svgView } from './vector/index.js';
+
+/** Controls a registered thumbnail. */
+interface ThumbnailHandle {
+    /** Shows another source or other values. A new source is recompiled; new values only redraw. */
+    update(source: string, values?: Record<string, ControlValue>): void;
+    /** With reduced motion, a hovered thumbnail animates and the others hold a still frame. */
+    setHovered(hovered: boolean): void;
+    /** Stops drawing into the canvas and frees its program. */
+    dispose(): void;
+}
+interface ThumbnailPoolOptions {
+    /** Size of the shared render canvas (default 480 × 270). Thumbnails are drawn at most this large, then scaled. */
+    renderWidth?: number;
+    renderHeight?: number;
+    /** Animation rate (default 30). */
+    fps?: number;
+    /** `iTime` of the still frame shown with reduced motion (default 2). */
+    stillTime?: number;
+    /** Hold still frames unless hovered (default: the `prefers-reduced-motion` media query). */
+    reducedMotion?: boolean;
+}
+/**
+ * Animated thumbnails from a single WebGL context. Browsers cap live WebGL
+ * contexts (about 16), so a gallery cannot give every card its own: the pool
+ * renders each visible thumbnail in turn on one hidden canvas and copies the
+ * frame into the thumbnail's own 2D canvas, cropped to its aspect ratio like
+ * `object-fit: cover`. Thumbnails off screen (by `IntersectionObserver`) cost
+ * nothing, and programs compile once per source.
+ *
+ * Nothing is created until the first `register`.
+ */
+declare class ThumbnailPool {
+    private readonly renderWidth;
+    private readonly renderHeight;
+    private readonly interval;
+    private readonly fps;
+    private readonly stillTime;
+    private readonly reducedMotion;
+    private readonly entries;
+    private readonly byCanvas;
+    private observer;
+    private glCanvas;
+    private gl;
+    private textures;
+    private raf;
+    private last;
+    private start;
+    constructor(options?: ThumbnailPoolOptions);
+    /**
+     * Starts drawing `source` into `canvas`, which should be sized with CSS; its
+     * drawing buffer follows its CSS size and the device pixel ratio (up to 2).
+     * `onStatus` hears whether the source compiled (and `false` without WebGL2).
+     */
+    register(canvas: HTMLCanvasElement, source: string, values?: Record<string, ControlValue>, onStatus?: (ok: boolean) => void): ThumbnailHandle;
+    /** The number of registered thumbnails. */
+    get size(): number;
+    private intersection;
+    private context;
+    private textureCache;
+    /** Frees the textures no thumbnail shows any more. */
+    private retainTextures;
+    private release;
+    private compile;
+    private renderEntry;
+    private schedule;
+    private tick;
+}
+/** The pool `registerThumbnail` uses, created on first use. */
+declare function sharedThumbnailPool(): ThumbnailPool;
+/** Registers a thumbnail with the shared pool. See {@link ThumbnailPool.register}. */
+declare function registerThumbnail(canvas: HTMLCanvasElement, source: string, values?: Record<string, ControlValue>, onStatus?: (ok: boolean) => void): ThumbnailHandle;
+
+interface ShaderFramesOptions {
+    source: string;
+    values?: Record<string, ControlValue>;
+    width: number;
+    height: number;
+    /** Draw on this canvas instead of a new, detached one. It is resized to `width` × `height`. */
+    canvas?: HTMLCanvasElement;
+}
+interface RenderOptions {
+    /** `iFrame` (default: the number of frames rendered so far). */
+    frame?: number;
+    /** `iTimeDelta` in seconds (default: the time since the previous `render`, else 0). */
+    delta?: number;
+    /** `iMouse` (default: all zero, as on a page nobody has touched). */
+    mouse?: [number, number, number, number];
+}
+/**
+ * Renders a shader at exact times you choose, off screen. There is no
+ * animation loop and no clock: frame `n` of a recording at `fps` is
+ * `render(start + n / fps)`, so the output is the same on any machine. It
+ * suits recorders, video pipelines and anything else stepped by its own
+ * clock. The constructor throws a {@link ShaderCompileError} when the source
+ * does not compile.
+ *
+ * Image controls load in the background: `await frames.ready()` before the
+ * first `render`, or the frames show black where the images go.
+ */
+declare class ShaderFrames {
+    readonly canvas: HTMLCanvasElement;
+    readonly width: number;
+    readonly height: number;
+    readonly controls: ControlDef[];
+    private gl;
+    private shader;
+    private textures;
+    private values;
+    private rendered;
+    private lastTime;
+    private pixels;
+    constructor(options: ShaderFramesOptions);
+    /** Changes control values for the frames that follow. */
+    setValues(values: Record<string, ControlValue> | undefined): void;
+    /**
+     * Settles once every image the controls show has loaded. Rejects with an
+     * {@link ImageLoadError} when one cannot be.
+     */
+    ready(): Promise<void>;
+    /** Draws the frame at `time` seconds onto `canvas`. */
+    render(time: number, options?: RenderOptions): void;
+    /**
+     * The last rendered frame as RGBA bytes, rows top down (as in `ImageData`;
+     * WebGL itself reads bottom up). Pass `out` to reuse a buffer of
+     * `width * height * 4` bytes.
+     */
+    readPixels(out?: Uint8Array | Uint8ClampedArray): Uint8Array | Uint8ClampedArray;
+    /** Releases the GL context now rather than at garbage collection (browsers cap live contexts). */
+    dispose(): void;
+    private syncTextures;
+    private context;
+}
+
+interface GifOptions {
+    source: string;
+    values?: Record<string, ControlValue>;
+    width: number;
+    height: number;
+    /** Frames per second. GIF delays are whole hundredths of a second, so 10, 20, 25 and 50 play back exactly. */
+    fps: number;
+    /** Seconds of animation to record. */
+    duration: number;
+    /** `iTime` of the first frame (default 0). */
+    start?: number;
+    /** Called after each frame with the frames done and the total. */
+    onProgress?: (done: number, total: number) => void;
+    /** Aborting rejects with an `AbortError` `DOMException`. */
+    signal?: AbortSignal;
+}
+/**
+ * Records a shader as an animated GIF that loops forever. Frames are rendered
+ * off screen at exact time steps (`start + i / fps`), so the result is smooth
+ * whatever the page's frame rate, and nothing on screen is disturbed. Each
+ * frame gets its own 256-colour palette. The encoder,
+ * [gifenc](https://github.com/mattdesl/gifenc), is loaded on first use.
+ *
+ * Image controls are loaded before the first frame. Rejects with a
+ * `ShaderCompileError` when the source does not compile, and an
+ * `ImageLoadError` when an image cannot be loaded.
+ */
+declare function recordGif(options: GifOptions): Promise<Blob>;
+
+interface StandaloneOptions {
+    /** The comment at the top of the script, saying where the page came from. */
+    credit?: string;
+}
+/**
+ * A self-contained HTML page that runs the shader full-window, with the
+ * control values baked in. It has no dependencies and opens from disk. Like
+ * the live preview, it feeds `iMouse` from pointer drags and caps the pixel
+ * ratio at 2.
+ *
+ * Images are loaded by URL when the page opens: a `data:` URL travels with
+ * the page, an `https:` one needs the network and CORS, and a `blob:` one
+ * only lives as long as the page that made it. SVGs are sized to
+ * {@link SVG_EDGE} pixels before they are decoded, as `loadImage` does.
+ */
+declare function standaloneHtml(title: string, source: string, values?: Record<string, ControlValue>, options?: StandaloneOptions): string;
+
+/**
+ * 38 Layer Blend Modes for Compositing and WebGL Shader Generation.
+ * Mathematically matching Adobe After Effects & EffectCraft blending standards.
+ */
+type BlendMode = 'normal' | 'dissolve' | 'dancingDissolve' | 'darken' | 'multiply' | 'colorBurn' | 'classicColorBurn' | 'linearBurn' | 'darkerColor' | 'add' | 'lighten' | 'screen' | 'colorDodge' | 'classicColorDodge' | 'linearDodge' | 'lighterColor' | 'overlay' | 'softLight' | 'hardLight' | 'linearLight' | 'vividLight' | 'pinLight' | 'hardMix' | 'difference' | 'classicDifference' | 'exclusion' | 'subtract' | 'divide' | 'hue' | 'saturation' | 'color' | 'luminosity' | 'stencilAlpha' | 'stencilLuma' | 'silhouetteAlpha' | 'silhouetteLuma' | 'alphaAdd' | 'luminescentPremul';
+declare const ALL_BLEND_MODES: readonly BlendMode[];
+type ColorRgba = [number, number, number, number];
+/**
+ * Evaluates CPU compositing of premultiplied RGBA source onto premultiplied RGBA destination.
+ *
+ * @param mode Blend mode to apply.
+ * @param dst Destination premultiplied RGBA [r, g, b, a] in [0, 1].
+ * @param src Source premultiplied RGBA [r, g, b, a] in [0, 1].
+ * @param noise Per-pixel noise parameter in [0, 1] for Dissolve modes (default: 0).
+ */
+declare function blendRgba(mode: BlendMode, dst: ColorRgba, src: ColorRgba, noise?: number): ColorRgba;
+/**
+ * Returns a self-contained GLSL shader function for blending two vec4 colors.
+ * Useful for runtime GPU compositing across multiple shader layers or passes.
+ */
+declare function getGlslBlendFunction(mode: BlendMode): string;
+
+/**
+ * Procedural WebGL Fragment Shader Transitions & CPU Compositing.
+ * Inspired by professional NLE/After Effects/EffectCraft transitions:
+ * Linear Wipe, Radial Iris, Block Dissolve, Grid Wipe, Glass Wipe,
+ * Twister, Light Leak, and Cross Zoom.
+ */
+type TransitionType = 'linearWipe' | 'radialIris' | 'blockDissolve' | 'gridWipe' | 'glassWipe' | 'twister' | 'lightLeak' | 'crossZoom';
+declare const ALL_TRANSITION_TYPES: readonly TransitionType[];
+interface LinearWipeOptions {
+    /** Angle in degrees clockwise from right (0 = left-to-right, 90 = top-to-bottom). Default: 0 */
+    angle?: number;
+    /** Feather softness width [0..1]. Default: 0.1 */
+    feather?: number;
+}
+interface RadialIrisOptions {
+    /** Center point in normalized UV coordinates [0..1]. Default: [0.5, 0.5] */
+    center?: [number, number];
+    /** Geometric iris shape. Default: 'circle' */
+    shape?: 'circle' | 'box' | 'diamond';
+    /** Feather softness [0..1]. Default: 0.1 */
+    feather?: number;
+}
+interface BlockDissolveOptions {
+    /** Block cell count along width. Default: 32 */
+    blockCount?: number;
+    /** Pseudo-random seed integer. Default: 1337 */
+    seed?: number;
+    /** Softness of dissolve per block. Default: 0.05 */
+    feather?: number;
+}
+interface GridWipeOptions {
+    /** Number of grid cells [x, y]. Default: [16, 10] */
+    gridSize?: [number, number];
+    /** Order in which cells wipe: 'ltr' | 'diagonal' | 'radial' | 'random'. Default: 'diagonal' */
+    order?: 'ltr' | 'diagonal' | 'radial' | 'random';
+}
+interface GlassWipeOptions {
+    /** Angle in degrees. Default: 45 */
+    angle?: number;
+    /** Wave displacement amplitude. Default: 0.08 */
+    amplitude?: number;
+    /** Wave frequency. Default: 12.0 */
+    frequency?: number;
+}
+interface TwisterOptions {
+    /** Maximum twist angle in radians. Default: Math.PI * 2 */
+    twist?: number;
+    /** Center of swirl. Default: [0.5, 0.5] */
+    center?: [number, number];
+}
+interface LightLeakOptions {
+    /** Leak tint RGB [0..1]. Default: [1.0, 0.85, 0.6] (warm golden light) */
+    color?: [number, number, number];
+    /** Peak intensity of light bloom at progress 0.5. Default: 1.5 */
+    intensity?: number;
+}
+interface CrossZoomOptions {
+    /** Zoom strength. Default: 0.3 */
+    strength?: number;
+    /** Center of zoom. Default: [0.5, 0.5] */
+    center?: [number, number];
+}
+type TransitionOptions = LinearWipeOptions | RadialIrisOptions | BlockDissolveOptions | GridWipeOptions | GlassWipeOptions | TwisterOptions | LightLeakOptions | CrossZoomOptions;
+interface TransitionSample {
+    /** Weight of scene B in [0..1] (0 = fully A, 1 = fully B). */
+    weight: number;
+    /** Sample coordinate for scene A [u, v]. */
+    uvA: [number, number];
+    /** Sample coordinate for scene B [u, v]. */
+    uvB: [number, number];
+    /** Additive color light bloom [r, g, b]. */
+    additive: [number, number, number];
+}
+/**
+ * Evaluates the transition at a given UV coordinate and progress [0..1].
+ * Returns displaced UVs, B weight, and any additive optical bloom.
+ */
+declare function sampleTransition(type: TransitionType, uv: [number, number], progress: number, options?: TransitionOptions): TransitionSample;
+/**
+ * CPU Compositing: blends two RGBA pixels across a transition.
+ */
+declare function blendTransitionPixel(colA: [number, number, number, number], colB: [number, number, number, number], sample: TransitionSample): [number, number, number, number];
+/**
+ * Returns self-contained WebGL GLSL fragment shader code implementing
+ * the selected transition function.
+ * Signature: `vec4 flair_transition(sampler2D texA, sampler2D texB, vec2 uv, float progress)`
+ */
+declare function getTransitionGLSL(type: TransitionType): string;
+
+/**
+ * Perceptual Color Science & Film Grading Engine.
+ *
+ * Implements:
+ * - Oklab & Oklch: Perceptually uniform color spaces that eliminate hue shifts and gray dead zones.
+ * - Standard Color Spaces: sRGB, Linear sRGB, Rec.709, Display P3, and ACEScg.
+ * - Film Color Grading: ASC CDL (Slope, Offset, Power), Lift/Gamma/Gain, Vibrance (skin tone protection),
+ *   and White Balance (Kelvin color temperature & tint).
+ * - GLSL code generators for real-time WebGL fragment shader execution.
+ */
+type ColorRGB = [number, number, number];
+type ColorRGBA = [number, number, number, number];
+declare function srgbToLinear(c: number): number;
+declare function linearToSrgb(c: number): number;
+declare function srgbToLinearRgb(rgb: ColorRGB): ColorRGB;
+declare function linearRgbToSrgb(rgb: ColorRGB): ColorRGB;
+declare function linearSrgbToOklab(rgb: ColorRGB): [number, number, number];
+declare function oklabToLinearSrgb(lab: [number, number, number]): ColorRGB;
+declare function srgbToOklab(rgb: ColorRGB): [number, number, number];
+declare function oklabToSrgb(lab: [number, number, number]): ColorRGB;
+declare function oklabToOklch(lab: [number, number, number]): [number, number, number];
+declare function oklchToOklab(lch: [number, number, number]): [number, number, number];
+/**
+ * Perceptually uniform color interpolation using Oklab space.
+ * Prevents intermediate grayish dead spots.
+ */
+declare function interpolateOklab(c1: ColorRGB, c2: ColorRGB, t: number): ColorRGB;
+/**
+ * Perceptually uniform color interpolation using Oklch cylindrical space.
+ * Interpolates along the shortest hue arc for vibrant gradients.
+ */
+declare function interpolateOklch(c1: ColorRGB, c2: ColorRGB, t: number): ColorRGB;
+type ColorSpace = 'srgb' | 'linear-srgb' | 'rec709' | 'display-p3' | 'acescg';
+/**
+ * Converts a color between standard imaging color spaces.
+ */
+declare function convertColorSpace(color: ColorRGB, from: ColorSpace, to: ColorSpace): ColorRGB;
+interface AscCdl {
+    /** Multiplicative scaling (default [1, 1, 1]) */
+    slope?: ColorRGB;
+    /** Additive offset (default [0, 0, 0]) */
+    offset?: ColorRGB;
+    /** Exponential power (default [1, 1, 1]) */
+    power?: ColorRGB;
+    /** Master saturation (default 1.0) */
+    saturation?: number;
+}
+/**
+ * Standard ASC CDL (American Society of Cinematographers Color Decision List).
+ * Formula: out = (in * slope + offset)^power, followed by Rec.709 luma-weighted saturation.
+ */
+declare function applyAscCdl(color: ColorRGB, cdl: AscCdl): ColorRGB;
+interface LiftGammaGain {
+    /** Shadows adjustment (default [0, 0, 0]) */
+    lift?: ColorRGB;
+    /** Midtones gamma adjustment (default [1, 1, 1]) */
+    gamma?: ColorRGB;
+    /** Highlights gain adjustment (default [1, 1, 1]) */
+    gain?: ColorRGB;
+}
+/**
+ * Three-way Lift / Gamma / Gain film color grading.
+ * Formula: out = (gain * (in + lift * (1 - in)))^(1 / gamma)
+ */
+declare function applyLiftGammaGain(color: ColorRGB, lgg: LiftGammaGain): ColorRGB;
+/**
+ * Vibrance adjustment with skin tone protection.
+ * Selectively boosts muted colors while preventing already saturated colors and skin tones
+ * from clipping.
+ * @param amount Vibrance delta in [-1..1]
+ */
+declare function applyVibrance(color: ColorRGB, amount: number): ColorRGB;
+/**
+ * Calculates RGB multiplier from Kelvin blackbody color temperature and green/magenta tint.
+ * @param kelvin Temperature in Kelvin [2000..12000], D65 neutral is 6500K.
+ * @param tint Green/magenta shift in [-100..100] (0 = neutral).
+ */
+declare function getWhiteBalanceGains(kelvin: number, tint?: number): ColorRGB;
+/**
+ * Self-contained GLSL functions for fast Oklab <-> Linear sRGB transforms.
+ */
+declare function getOklabGLSL(): string;
+/**
+ * Self-contained GLSL functions for ASC CDL and Lift/Gamma/Gain grading.
+ */
+declare function getColorGradingGLSL(): string;
+
+/**
+ * Retiming math engine inspired by Apple Motion's RetimingMath framework.
+ * Provides deterministic time transformation functors for looping, bouncing (ping-pong),
+ * freezing (hold), posterizing/stepping (strobe), and non-linear speed ramps.
+ */
+type EasingCurve = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut';
+/**
+ * Loops time within [start, start + duration).
+ * Handles negative time values smoothly.
+ */
+declare function loopTime(t: number, duration: number, start?: number): number;
+/**
+ * Reflects time back and forth (triangle wave) between start and start + duration.
+ */
+declare function pingPongTime(t: number, duration: number, start?: number): number;
+/**
+ * Freezes time at a specified timestamp.
+ */
+declare function holdTime(_t: number, holdAt: number): number;
+/**
+ * Quantizes continuous time into discrete intervals matching a target frame rate (posterize time).
+ * @param t Current timestamp.
+ * @param fps Target stepped frame rate (e.g. 12 for stop-motion).
+ * @param unit 'ms' (default) if t is in milliseconds, or 'sec' if t is in seconds.
+ */
+declare function strobeTime(t: number, fps: number, unit?: 'ms' | 'sec'): number;
+/**
+ * Applies a non-linear speed ramp curve to time progression within an interval [start, start + duration].
+ */
+declare function speedRampTime(t: number, start: number, duration: number, ease?: EasingCurve): number;
+
+/**
+ * Keyframe velocity and cubic Bezier easing engine matching Adobe After Effects interpolation semantics.
+ *
+ * Temporal interpolation between two keyframes is characterized by:
+ * - Speed (units / second)
+ * - Influence (fraction 0..1, corresponding to 0.1%..100% in the Keyframe Velocity dialog)
+ *
+ * For normalized values going from 0 to 1 over a segment, easeProgress(outSpeedNorm, outInf, inSpeedNorm, inInf, x)
+ * solves the monotone cubic Bezier root x(u) = x and computes value y(u).
+ */
+interface KeyframeEase {
+    /** Speed in value units per second (or normalized speed if evaluating normalized segment). */
+    speed: number;
+    /** Influence as a fraction between 0.0 and 1.0 (e.g. 0.3333 for 33.33%). */
+    influence: number;
+}
+/** Easy Ease preset: 0 speed, 33.333% influence. */
+declare const EASY_EASE: KeyframeEase;
+/** Evaluates a 1D cubic Bezier polynomial at parameter u in [0, 1]. */
+declare function bez1d(p0: number, p1: number, p2: number, p3: number, u: number): number;
+/** Evaluates the first derivative of a 1D cubic Bezier polynomial at parameter u. */
+declare function bez1dDerivative(p0: number, p1: number, p2: number, p3: number, u: number): number;
+/**
+ * Solves bez1d(x0, x1, x2, x3, u) = x for u in [0, 1] assuming x(u) is monotone.
+ * Uses closed-form inverse for 100% influence midpoint, Newton-Raphson iteration,
+ * and high-precision bisection fallback.
+ */
+declare function solveBezierU(x0: number, x1: number, x2: number, x3: number, x: number): number;
+/**
+ * Fraction of progress 0..1 through a 1D Bezier temporal segment whose value goes from 0 to 1,
+ * with normalized out/in speeds (speed * duration / deltaValue) and influences.
+ *
+ * @param outSpeedNorm Normalized outgoing speed (speed * duration / deltaValue).
+ * @param outInfluence Outgoing influence fraction [0, 1].
+ * @param inSpeedNorm Normalized incoming speed (speed * duration / deltaValue).
+ * @param inInfluence Incoming influence fraction [0, 1].
+ * @param x Normalized time progress in segment [0, 1].
+ */
+declare function easeProgress(outSpeedNorm: number, outInfluence: number, inSpeedNorm: number, inInfluence: number, x: number): number;
+/**
+ * Evaluates an interpolated keyframe segment between two values over duration.
+ *
+ * @param from Starting value at t = 0.
+ * @param to Ending value at t = duration.
+ * @param duration Duration of the keyframe segment in seconds.
+ * @param t Current elapsed time in seconds (0 <= t <= duration).
+ * @param outEase Outgoing ease specification at start keyframe.
+ * @param inEase Incoming ease specification at end keyframe.
+ */
+declare function evaluateKeyframeSegment(from: number, to: number, duration: number, t: number, outEase?: KeyframeEase, inEase?: KeyframeEase): number;
+
+/**
+ * Deterministic pseudo-random number generator, hash mixing, and C2-continuous smooth value noise.
+ * Based on 64-bit SplitMix64 mixing and quintic Hermite interpolation.
+ *
+ * Produces deterministic, platform-independent outputs for wiggle, organic turbulence, and camera shake.
+ */
+/**
+ * SplitMix64 mixing finalizer: maps any 64-bit integer to a high-quality pseudorandom 64-bit integer.
+ */
+declare function hash64(x: bigint): bigint;
+/**
+ * Combines multiple seed numbers/bigints into a single mixed 64-bit seed.
+ */
+declare function mixSeeds(parts: (bigint | number)[]): bigint;
+/**
+ * Maps a 64-bit seed to a uniform float in [0, 1).
+ */
+declare function unitFloat(seed: bigint | number): number;
+/**
+ * Quintic Hermite interpolant fade function: 6t^5 - 15t^4 + 10t^3.
+ * First and second derivatives are zero at t = 0 and t = 1, ensuring C2 continuity.
+ */
+declare function quinticFade(t: number): number;
+/**
+ * 1D C2-continuous smooth value noise in [-1, 1].
+ * Guaranteed bounded by lattice values, smooth without sudden velocity spikes.
+ */
+declare function noise1d(seed: bigint | number, x: number): number;
+/**
+ * 3D C2-continuous smooth value noise in [-1, 1].
+ */
+declare function noise3d(x: number, y: number, z: number, seed?: bigint | number): number;
+/**
+ * Evaluates multi-octave fractal noise wiggle:
+ * sum_{k=0}^{octaves-1} amp * (ampMult^k) * noise1d(freq * (2^k) * t)
+ *
+ * Matches the mathematical formulation of After Effects / EffectCraft wiggle().
+ *
+ * @param freq Oscillation frequency in Hz (cycles per second).
+ * @param amp Maximum deviation amplitude.
+ * @param octaves Number of noise detail octaves (default: 3).
+ * @param ampMult Amplitude multiplier per octave (default: 0.5).
+ * @param t Elapsed time in seconds.
+ * @param seed Random seed (default: 42).
+ * @param dimension Dimension index (0, 1, 2) to ensure decorrelated multi-axis wiggle.
+ */
+declare function fractalWiggle(freq: number, amp: number, octaves?: number, ampMult?: number, t?: number, seed?: number, dimension?: number): number;
+
+/**
+ * SMPTE 12M Timecode engine and broadcast frame-rate converter.
+ *
+ * Supports non-drop-frame (NDF) and drop-frame (DF) timecode for broadcast standards
+ * (23.976, 24, 25, 29.97, 30, 48, 50, 59.94, 60, 120 fps).
+ *
+ * Drop-frame timecode drops frames 00 and 01 at the start of each minute,
+ * except every 10th minute (e.g. 00:01:00;02 instead of 00:01:00;00).
+ */
+interface RationalFrameRate {
+    readonly num: number;
+    readonly den: number;
+}
+declare const COMMON_FRAME_RATES: {
+    readonly FPS_23_976: {
+        readonly num: 24000;
+        readonly den: 1001;
+    };
+    readonly FPS_24: {
+        readonly num: 24;
+        readonly den: 1;
+    };
+    readonly FPS_25: {
+        readonly num: 25;
+        readonly den: 1;
+    };
+    readonly FPS_29_97: {
+        readonly num: 30000;
+        readonly den: 1001;
+    };
+    readonly FPS_30: {
+        readonly num: 30;
+        readonly den: 1;
+    };
+    readonly FPS_48: {
+        readonly num: 48;
+        readonly den: 1;
+    };
+    readonly FPS_50: {
+        readonly num: 50;
+        readonly den: 1;
+    };
+    readonly FPS_59_94: {
+        readonly num: 60000;
+        readonly den: 1001;
+    };
+    readonly FPS_60: {
+        readonly num: 60;
+        readonly den: 1;
+    };
+    readonly FPS_120: {
+        readonly num: 120;
+        readonly den: 1;
+    };
+};
+type StandardFrameRateKey = keyof typeof COMMON_FRAME_RATES;
+/** Creates a reduced rational frame rate. */
+declare function createFrameRate(num: number, den?: number): RationalFrameRate;
+/** Returns the timecode base (frames counted per second in timecode display). */
+declare function getTimecodeBase(rate: RationalFrameRate): number;
+/** Whether a given frame rate supports drop-frame counting (29.97, 59.94, etc.). */
+declare function supportsDropFrame(rate: RationalFrameRate): boolean;
+/** Number of dropped frames per minute (e.g. 2 for 29.97, 4 for 59.94). */
+declare function getDropFrameCount(rate: RationalFrameRate): number;
+interface SMPTEFields {
+    negative: boolean;
+    hours: number;
+    minutes: number;
+    seconds: number;
+    frames: number;
+}
+/**
+ * Converts a continuous frame count to SMPTE fields (hours, minutes, seconds, frames).
+ */
+declare function framesToSMPTE(frame: number, rate?: RationalFrameRate, dropFrame?: boolean): SMPTEFields;
+/**
+ * Converts SMPTE fields back to a continuous frame number.
+ */
+declare function smpteToFrames(fields: {
+    hours: number;
+    minutes: number;
+    seconds: number;
+    frames: number;
+}, rate?: RationalFrameRate, dropFrame?: boolean): number;
+/**
+ * Formats a frame number as standard SMPTE timecode (HH:MM:SS:FF or HH;MM;SS;FF).
+ */
+declare function formatTimecode(frame: number, rate?: RationalFrameRate, dropFrame?: boolean): string;
+/**
+ * Parses user or NLE input into a frame number.
+ * Supports:
+ * - Standard timecodes: `01:00:00:00`, `01;00;00;00`, `00.01.20.15`
+ * - Right-aligned numbers: `1000` -> `00:00:10:00`
+ * - Relative offsets: `+15` (+15 frames), `-1.00` (-1 second)
+ *
+ * @param input The timecode string to parse.
+ * @param rate Rational frame rate (default: 30 fps).
+ * @param dropFrame Whether drop-frame arithmetic applies.
+ * @param currentFrame Current playhead position for relative additions.
+ */
+declare function parseTimecode(input: string, rate?: RationalFrameRate, dropFrame?: boolean, currentFrame?: number): number;
+
+type Point = [number, number];
+interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** An element placed or animated in a scene. */
+interface SceneElement {
+    id: string;
+    type: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    points?: readonly (readonly [number, number])[];
+    fontSize?: number;
+    text?: string;
+    containerId?: string | null;
+    isDeleted?: boolean;
+    opacity?: number;
+}
+/** Bounds in scene units, ignoring rotation. */
+declare function boundsOf(e: SceneElement): Rect;
+/** Area of the overlap of two rectangles (0 when they do not meet). */
+declare function overlapArea(a: Rect, b: Rect): number;
+declare const areaOf: (r: Rect) => number;
+
+interface Stage {
+    width: number;
+    height: number;
+    caption?: number;
+}
+declare const DEFAULT_STAGE: Stage;
+declare const CAMERA_MS = 600;
+/** Camera view into the scene: drawn at (point + scroll) × zoom. */
+interface View {
+    zoom: number;
+    scrollX: number;
+    scrollY: number;
+}
+declare const boardHeight: (stage: Stage) => number;
+/** View with `(cx, cy)` in the middle of the board at `zoom`. */
+declare function viewAt(cx: number, cy: number, zoom: number, stage: Stage): View;
+/** Scene point in the middle of the board. */
+declare function centreOf(view: View, stage: Stage): [number, number];
+/** The view that fits `rect` on the board, centred and with its aspect kept. */
+declare function frame(rect: Rect, stage: Stage): View;
+interface FramingOptions {
+    /** Proportional padding added to all sides (e.g., 0.15 for 15%). Default: 0.15 */
+    padding?: number;
+    /** Minimum width in scene units. */
+    minWidth?: number;
+    /** Minimum height in scene units. */
+    minHeight?: number;
+}
+/**
+ * Calculates a camera framing rectangle that encloses target elements
+ * while preserving the stage aspect ratio and applying optional margin padding.
+ */
+declare function calculateFramingRect(elements: readonly SceneElement[], stage: Stage, options?: FramingOptions): Rect;
+/**
+ * The view part-way (`t` from 0 to 1) from one view to another.
+ * Centre moves linearly and zoom scales exponentially for smooth motion.
+ */
+declare function between(from: View, to: View, t: number, stage: Stage): View;
+/** The part of the scene the camera currently shows. */
+declare function visibleRect(view: View, stage: Stage): Rect;
+/** Smooth cubic ease in / ease out. */
+declare const easeInOutCubic: (t: number) => number;
+
+interface EffectBase {
+    /** Unique identifier for the effect so it can be stopped or updated. */
+    id: string;
+    /** End the effect when this many subsequent shots begin. */
+    shots?: number;
+    /** Duration in milliseconds after which the effect stops automatically. */
+    duration?: number;
+    /** When to start: 'start' of shot or after commands are 'drawn'. Default: 'drawn'. */
+    at?: 'start' | 'drawn';
+}
+interface GradientEffect extends EffectBase {
+    type: 'gradient';
+    colors: string[];
+    rect?: Rect;
+    ids?: string[];
+    angle?: number;
+    period?: number;
+    opacity?: number;
+}
+interface FlowEffect extends EffectBase {
+    type: 'flow';
+    along: string;
+    color?: string;
+    dots?: number;
+    period?: number;
+    size?: number;
+    direction?: 'forward' | 'back' | 'both';
+    label?: string;
+}
+interface GlowEffect extends EffectBase {
+    type: 'glow';
+    ids: string[];
+    color?: string;
+    size?: number;
+    pulse?: boolean;
+}
+interface SpotlightEffect extends EffectBase {
+    type: 'spotlight';
+    ids: string[];
+    dim?: number;
+    padding?: number;
+}
+interface ShimmerEffect extends EffectBase {
+    type: 'shimmer';
+    ids: string[];
+    color?: string;
+    period?: number;
+}
+interface RippleEffect extends EffectBase {
+    type: 'ripple';
+    ids: string[];
+    color?: string;
+    period?: number;
+    size?: number;
+    times?: number;
+}
+interface TimerEffect extends EffectBase {
+    type: 'timer';
+    ids: string[];
+    time?: number;
+    fill?: boolean;
+    repeat?: boolean;
+    color?: string;
+    size?: number;
+}
+interface CounterEffect extends EffectBase {
+    type: 'counter';
+    to: number;
+    from?: number;
+    time?: number;
+    text?: string;
+    decimals?: number;
+    near?: string;
+    x?: number;
+    y?: number;
+    color?: string;
+    size?: number;
+}
+interface HighlightEffect extends EffectBase {
+    type: 'highlight';
+    ids: string[];
+    style?: 'marker' | 'underline';
+    color?: string;
+}
+interface BlurEffect extends EffectBase {
+    type: 'blur';
+    ids: string[];
+    amount?: number;
+    padding?: number;
+}
+interface BurstEffect extends EffectBase {
+    type: 'burst';
+    ids: string[];
+    color?: string;
+    sparks?: number;
+    size?: number;
+}
+/** Media layer effect driving a WebGL shader (or other media stream) under or over the scene. */
+interface MediaEffect extends EffectBase {
+    type: 'media';
+    /** ID in Scene.media. */
+    media: string;
+    rect?: Rect;
+    ids?: string[];
+    padding?: number;
+    layer?: 'under' | 'over';
+    opacity?: number;
+}
+type Effect = GradientEffect | FlowEffect | GlowEffect | SpotlightEffect | ShimmerEffect | RippleEffect | TimerEffect | CounterEffect | HighlightEffect | BlurEffect | BurstEffect | MediaEffect;
+declare const EFFECT_TYPES: readonly ["gradient", "flow", "glow", "spotlight", "shimmer", "ripple", "timer", "counter", "highlight", "blur", "burst", "media"];
+declare const EFFECT_FADE_MS = 300;
+interface RunningEffect {
+    effect: Effect;
+    /** Timestamp when started (ms). */
+    from: number;
+    /** Timestamp when stopping/fading begins (ms). */
+    until?: number;
+}
+/** Returns true if the effect has completely expired and finished fading out. */
+declare function effectGone(running: RunningEffect, now: number): boolean;
+/** Returns current opacity multiplier (0 to 1) accounting for fade in / fade out. */
+declare function effectOpacity(running: RunningEffect, now: number): number;
+
+interface BehaviorBase {
+    id?: string;
+    /** Target element ID or media ID. */
+    target: string;
+    /** Property on element (e.g. 'x', 'y', 'scale', 'rotation', 'opacity') or uniform on media. */
+    property: string;
+}
+interface OscillateBehavior extends BehaviorBase {
+    type: 'oscillate';
+    wave?: 'sine' | 'square' | 'triangle' | 'sawtooth';
+    amplitude: number;
+    /** Frequency in Hz (cycles per second). */
+    frequency: number;
+    /** Phase offset in radians (default 0). */
+    phase?: number;
+    /** Base center value. If undefined, treated as relative offset added to current base value. */
+    center?: number;
+}
+interface RampBehavior extends BehaviorBase {
+    type: 'ramp';
+    from?: number;
+    to: number;
+    ease?: EasingCurve;
+}
+interface RateBehavior extends BehaviorBase {
+    type: 'rate';
+    /** Rate of change per second (e.g. degrees/sec or units/sec). */
+    rate: number;
+}
+interface WriggleBehavior extends BehaviorBase {
+    type: 'wriggle';
+    /** Maximum amplitude of deviation. */
+    amount: number;
+    /** Speed / frequency of variation in Hz. */
+    frequency: number;
+    /** Number of noise octaves for organic complexity (default: 3). */
+    octaves?: number;
+    /** Deterministic random seed. */
+    seed?: number;
+}
+interface OvershootBehavior extends BehaviorBase {
+    type: 'overshoot';
+    targetValue: number;
+    startValue?: number;
+    /** Oscillation frequency / cycles (default: 3). */
+    cycles?: number;
+    /** Damping factor (higher settles faster, default: 4.0). */
+    damping?: number;
+}
+interface ThrowBehavior extends BehaviorBase {
+    type: 'throw';
+    /** Initial speed in units per second. */
+    initialVelocity: number;
+    /** Friction / deceleration factor (default: 2.0). */
+    friction?: number;
+}
+type Behavior = OscillateBehavior | RampBehavior | RateBehavior | WriggleBehavior | OvershootBehavior | ThrowBehavior;
+/**
+ * Evaluates the new numeric value for a behavior at a given elapsed time.
+ * @param behavior The behavior specification.
+ * @param elapsedSec Elapsed time within the shot/behavior duration (in seconds).
+ * @param durationSec Total duration of the shot/behavior (in seconds).
+ * @param baseValue Initial or fallback value before behavior was applied.
+ */
+declare function evaluateBehavior(behavior: Behavior, elapsedSec: number, durationSec: number, baseValue?: number): number;
+
+interface SliderSnapshot {
+    at: number;
+    values: Record<string, number | string>;
+}
+interface SliderWidget {
+    type: 'slider';
+    name: string;
+    value: number;
+    snapshots: SliderSnapshot[];
+}
+interface PopupWidget {
+    type: 'popup';
+    name: string;
+    selected: string;
+    options: Record<string, Record<string, number | string>>;
+}
+interface ToggleWidget {
+    type: 'toggle';
+    name: string;
+    enabled: boolean;
+    on: Record<string, number | string>;
+    off: Record<string, number | string>;
+}
+type RigWidget = SliderWidget | PopupWidget | ToggleWidget;
+interface SceneRig {
+    widgets: Record<string, RigWidget>;
+}
+/**
+ * Updates a widget within a SceneRig and returns the updated SceneRig.
+ */
+declare function setRigWidget(rig: SceneRig, widgetName: string, value: number | string | boolean): SceneRig;
+/**
+ * Propagates rig widget state into the scene's shader uniforms and elements.
+ */
+declare function applyRig(rig: SceneRig, scene: Scene): Scene;
+
+/** Shader or external visual stream in the scene. */
+interface SceneMedia {
+    type: 'shader' | string;
+    source?: string;
+    values?: Record<string, unknown>;
+    [field: string]: unknown;
+}
+interface ElementCommand {
+    type: 'element';
+    element: SceneElement;
+}
+interface UpdateCommand {
+    type: 'update';
+    id: string;
+    props: Partial<SceneElement>;
+}
+interface DeleteCommand {
+    type: 'delete';
+    id: string;
+}
+interface ClearCommand {
+    type: 'clear';
+}
+interface CustomCommand {
+    type: string;
+    [key: string]: unknown;
+}
+/** A command to add, move, or style elements in a shot. */
+type SceneCommand = ElementCommand | UpdateCommand | DeleteCommand | ClearCommand | CustomCommand;
+declare function isElementCommand(cmd: SceneCommand): cmd is ElementCommand;
+declare function isUpdateCommand(cmd: SceneCommand): cmd is UpdateCommand;
+declare function isDeleteCommand(cmd: SceneCommand): cmd is DeleteCommand;
+interface DynamicFraming {
+    /** Element IDs to frame. */
+    frame: string[];
+    /** Proportional padding (default 0.15 for 15%). */
+    padding?: number;
+    /** Minimum width in scene units. */
+    minWidth?: number;
+    /** Minimum height in scene units. */
+    minHeight?: number;
+}
+type ShotCamera = Rect | DynamicFraming;
+/** One beat of a scene: camera framing, title, narration/caption, commands, and procedural effects. */
+interface Shot {
+    /** Narration / caption spoken or displayed during this beat. */
+    caption?: string;
+    /** High-level title or callout displayed on screen. */
+    title?: string;
+    /** Camera framing box in scene units, or dynamic auto-framing target. */
+    camera?: ShotCamera;
+    /** Pause/dwell duration after this shot's actions run (in milliseconds). Default: 800ms. */
+    hold?: number;
+    /** Drawing or state change commands played during this shot. */
+    run?: SceneCommand[];
+    /** Procedural visual effects started in this shot. */
+    effects?: Effect[];
+    /** IDs of active effects to stop/fade at the start of this shot. */
+    stopEffects?: string[];
+    /** Continuous procedural parameter and physics behaviors played during this shot. */
+    behaviors?: Behavior[];
+}
+/** Complete animated scene specification. */
+interface Scene {
+    name: string;
+    title?: string;
+    description?: string;
+    stage?: Partial<Stage>;
+    /** Embedded media (e.g. bespoke WebGL fragment shaders). */
+    media?: Record<string, SceneMedia>;
+    /** Target duration [minSeconds, maxSeconds]. */
+    target?: [number, number];
+    /** Interactive macro rigs binding high-level controls to uniforms or element properties. */
+    rig?: SceneRig;
+    shots: Shot[];
+}
+
+interface ShotCheck {
+    /** Elements this shot drew or changed that the camera frame leaves out ("outside") or cuts ("cut"). */
+    framing: {
+        id: string;
+        how: 'outside' | 'cut';
+    }[];
+    /** Elements this shot drew that overlap each other significantly. */
+    overlaps: [string, string][];
+    /** Smallest text size on screen in CSS px. */
+    smallestText?: {
+        id: string;
+        text: string;
+        px: number;
+    };
+    /** Any text smaller than min readable threshold (e.g. 18px). */
+    smallTexts?: {
+        id: string;
+        text: string;
+        px: number;
+    }[];
+    /** Elements clipped by the screen edges. */
+    edges: string[];
+    /** Elements covered by the title bar. */
+    underTitle: string[];
+}
+declare const NO_CHECK: ShotCheck;
+declare const SMALL_TEXT_PX = 24;
+declare function titleBox(title: string, stage: Stage): Rect;
+declare function touchedIds(shot: Shot): string[];
+/** Evaluates the elements on stage against the current camera view and shot settings. */
+declare function checkShot(shot: Shot, elements: readonly SceneElement[], view: View, stage: Stage, title?: string): ShotCheck;
+
+interface SceneIssue {
+    /** 1-based shot index (0 indicates whole scene level). */
+    shot: number;
+    message: string;
+}
+/** Validates a Scene before running or rendering it. */
+declare function validateScene(scene: Scene): SceneIssue[];
+
+interface ShotLog extends ShotCheck {
+    index: number;
+    start: number;
+    drawn: number;
+    end: number;
+    caption?: string;
+    title?: string;
+    failed: string[];
+    effects?: string[];
+}
+interface ReviewOptions {
+    target?: [number, number];
+    minTextPx?: number;
+}
+interface Review {
+    totalMs: number;
+    warnings: string[];
+    notes: string[];
+    markdown: string;
+}
+/** Formats a structured diagnostic report of scene playback. */
+declare function reviewScene(scene: Scene, logs: readonly ShotLog[], options?: ReviewOptions): Review;
+
+interface SceneBoard {
+    getView(): View;
+    setView(view: View): void;
+    elements(): readonly SceneElement[];
+    runCommand(cmd: SceneCommand): void | Promise<void>;
+    setTitle?(text: string, opacity: number): void;
+    setCaption?(text: string): void;
+    setEffects?(effects: readonly RunningEffect[]): void;
+    setMediaTime?(mediaId: string, timeSeconds: number): void;
+}
+/** Pure in-memory board implementation suitable for headless simulation, testing, and SSR. */
+declare class MemorySceneBoard implements SceneBoard {
+    private view;
+    private elMap;
+    private currentTitle;
+    private currentCaption;
+    private runningEffects;
+    constructor(stage?: Stage);
+    getView(): View;
+    setView(view: View): void;
+    elements(): readonly SceneElement[];
+    runCommand(cmd: SceneCommand): void;
+    setTitle(text: string): void;
+    setCaption(text: string): void;
+    setEffects(effects: readonly RunningEffect[]): void;
+}
+interface PlayOptions {
+    check?: boolean;
+    afterShot?: (log: ShotLog) => void | Promise<void>;
+}
+interface PlayResult {
+    ok: boolean;
+    duration: number;
+    shots: ShotLog[];
+}
+/**
+ * Plays a scene's shots sequentially on `board` driven by `clock`.
+ * When using a `ManualClock`, the execution is completely deterministic and stepped.
+ */
+declare function playScene(scene: Scene, board: SceneBoard, clock: Clock, options?: PlayOptions): Promise<PlayResult>;
+/**
+ * Simulates a scene instantaneously using a ManualClock and MemorySceneBoard,
+ * returning full timing details, layout checks, and diagnostic report.
+ */
+declare function simulateScene(scene: Scene, options?: {
+    minTextPx?: number;
+}): Promise<{
+    result: PlayResult;
+    review: Review;
+}>;
+
+/**
+ * Generates a self-contained, standalone HTML player for an animated scene.
+ * Includes interactive playback controls, camera panning/zooming, title and caption rendering,
+ * and embedded WebGL fragment shaders for bespoke motion graphics.
+ */
+declare function standaloneSceneHtml(scene: Scene): string;
+
+type ReplicatorPattern = 'grid' | 'line' | 'circle' | 'spiral';
+interface ReplicatorSequence {
+    /** Property to modulate per item. */
+    property?: 'opacity' | 'rotation' | 'scale' | 'x' | 'y';
+    /** Incremental offset or delta added per instance. */
+    offset?: number;
+    /** Milliseconds delay per instance for staggered triggers. */
+    delayPerItem?: number;
+}
+interface ReplicatorConfig {
+    pattern: ReplicatorPattern;
+    count: number;
+    /** Origin point [x, y] to anchor the layout (defaults to prototype.x, prototype.y). */
+    origin?: [number, number];
+    columns?: number;
+    rows?: number;
+    columnSpacing?: number;
+    rowSpacing?: number;
+    startPoint?: [number, number];
+    endPoint?: [number, number];
+    spacing?: number;
+    radius?: number;
+    startAngle?: number;
+    spiralTightness?: number;
+    sequence?: ReplicatorSequence;
+}
+/**
+ * Procedurally replicates a prototype SceneElement into an array of positioned
+ * and sequenced instances (grid, circular array, line, or spiral).
+ */
+declare function expandReplicator(prototype: SceneElement, config: ReplicatorConfig): SceneElement[];
+
+/**
+ * Constant-Velocity Spatial Motion Paths & Arc-Length Parameterization.
+ *
+ * Implements multi-segment cubic Bezier spatial trajectories with numerical
+ * arc-length integration, ensuring constant pixel-speed traversal, tangent heading,
+ * normal vectors, curvature, and seamless combination with temporal AE keyframe easing.
+ */
+
+type Vec2 = [number, number];
+type Vec3 = [number, number, number];
+interface PathWaypoint {
+    /** Anchor position in 2D or 3D scene coordinates [x, y] or [x, y, z]. */
+    point: Vec2 | Vec3;
+    /** In-tangent handle relative to anchor point (vector pointing from handle to anchor or vice-versa). Default: [0, 0, 0] */
+    inTangent?: Vec2 | Vec3;
+    /** Out-tangent handle relative to anchor point (vector pointing from anchor toward next handle). Default: [0, 0, 0] */
+    outTangent?: Vec2 | Vec3;
+}
+interface SpatialPathSample {
+    /** Position on curve [x, y, z]. */
+    position: Vec3;
+    /** Normalized unit tangent vector [dx, dy, dz]. */
+    tangent: Vec3;
+    /** 2D heading angle in radians (atan2(dy, dx)). */
+    heading: number;
+    /** 2D unit normal vector [-dy, dx, 0]. */
+    normal: Vec3;
+    /** Instantaneous curvature kappa (1 / radius of curvature). */
+    curvature: number;
+    /** Distance traversed along the path in absolute units. */
+    distance: number;
+}
+interface SegmentSample {
+    t: number;
+    s: number;
+    pos: Vec3;
+}
+interface PathSegment {
+    p0: Vec3;
+    p1: Vec3;
+    p2: Vec3;
+    p3: Vec3;
+    length: number;
+    samples: SegmentSample[];
+}
+interface SpatialMotionPath {
+    waypoints: PathWaypoint[];
+    closed: boolean;
+    totalLength: number;
+    segments: PathSegment[];
+}
+/**
+ * Creates and compiles a constant-velocity SpatialMotionPath from a sequence of waypoints.
+ * Computes fine-grained arc-length tables along all Bezier segments.
+ */
+declare function createMotionPath(waypoints: PathWaypoint[], options?: {
+    closed?: boolean;
+    resolution?: number;
+}): SpatialMotionPath;
+/**
+ * Samples the spatial motion path at a normalized distance fraction [0..1].
+ * Guarantees strictly constant pixel speed regardless of control handle asymmetry.
+ */
+declare function sampleMotionPath(path: SpatialMotionPath, distanceFraction: number): SpatialPathSample;
+/**
+ * Samples a spatial motion path driven by elapsed time and AE keyframe velocity easing.
+ * Combines spatial arc-length constancy with temporal speed curves.
+ */
+declare function sampleMotionPathAtTime(path: SpatialMotionPath, time: number, duration: number, ease?: {
+    easeIn?: KeyframeEase;
+    easeOut?: KeyframeEase;
+}): SpatialPathSample;
+
+interface AgentToolDefinition {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}
+declare const FLAIR_AGENT_TOOLS: AgentToolDefinition[];
+type SceneToolResult = {
+    ok: true;
+    scene: Scene;
+    issues: SceneIssue[];
+    review?: Review;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Pure state machine that applies tool operations to a Scene.
+ */
+declare function applySceneTool(scene: Scene, toolName: string, input?: Record<string, any>): Promise<SceneToolResult>;
+
+/**
+ * Atomic Agent Multi-Tool Batching with Result Variable Substitution.
+ * Inspired by EffectCraft's atomic batch execution protocol.
+ *
+ * Allows AI agents to execute multi-step modifications to a Scene in a single turn,
+ * with atomic rollback on failure and cross-step variable substitution ($1.prop, $2.prop).
+ */
+
+interface BatchCommand {
+    /** Name of the tool to execute (e.g. 'update_shot', 'insert_shots', 'set_rig_widget'). */
+    tool: string;
+    /** Parameters for the tool call. */
+    params?: Record<string, any>;
+}
+interface BatchExecutionStepResult {
+    step: number;
+    tool: string;
+    result: SceneToolResult;
+}
+interface BatchExecutionResult {
+    ok: boolean;
+    scene: Scene;
+    steps: BatchExecutionStepResult[];
+    error?: string;
+    failedStep?: number;
+}
+/**
+ * Recursively substitutes `$stepIndex.path` references in parameters using previous step results.
+ * E.g., "$1.scene.shots[0].duration" -> substituted with the duration value from step 1 result.
+ */
+declare function substituteVariables(value: any, stepResults: Map<number, SceneToolResult>): any;
+/**
+ * Executes an atomic batch of scene tools with transactional rollback.
+ * If any step fails, the scene rolls back to the initial state and returns the failure.
+ *
+ * @param scene Initial scene state before batch.
+ * @param commands Ordered array of tool commands to execute.
+ */
+declare function applySceneBatch(scene: Scene, commands: BatchCommand[]): Promise<BatchExecutionResult>;
+
+interface MotnExportOptions {
+    frameRate?: number;
+}
+/**
+ * Serializes a Flair Scene into Apple Motion ozml 4.0 XML document format (.motn).
+ */
+declare function exportMotn(scene: Scene, options?: MotnExportOptions): string;
+
+/**
+ * Lottie JSON Vector Animation Exporter.
+ *
+ * Converts Flair scenes, elements, shapes, transforms, and keyframes into
+ * official Lottie JSON format (v5.5.2) compatible with Airbnb Lottie-Web,
+ * iOS/Android Lottie, Figma, and Telegram.
+ */
+
+interface LottieExportOptions {
+    /** Target framerate in fps. Default: 30 */
+    frameRate?: number;
+}
+interface LottieKeyframe<T> {
+    t: number;
+    s: T;
+    e?: T;
+    o?: {
+        x: number | number[];
+        y: number | number[];
+    };
+    i?: {
+        x: number | number[];
+        y: number | number[];
+    };
+    h?: number;
+}
+interface LottieAnimatable<T, K = T> {
+    a: 0 | 1;
+    k: T | LottieKeyframe<K>[];
+}
+interface LottieTransform {
+    p: LottieAnimatable<[number, number, number], [number, number, number]>;
+    a: LottieAnimatable<[number, number, number], [number, number, number]>;
+    s: LottieAnimatable<[number, number, number], [number, number, number]>;
+    r: LottieAnimatable<number, [number]>;
+    o: LottieAnimatable<number, [number]>;
+}
+interface LottieShapeItem {
+    ty: string;
+    nm?: string;
+    [key: string]: unknown;
+}
+interface LottieLayer {
+    ddd: 0 | 1;
+    ind: number;
+    ty: number;
+    nm: string;
+    sr: number;
+    ks: LottieTransform;
+    ao: 0 | 1;
+    ip: number;
+    op: number;
+    st: number;
+    bm: number;
+    shapes?: LottieShapeItem[];
+    sw?: number;
+    sh?: number;
+    sc?: string;
+}
+interface LottieAnimation {
+    v: string;
+    fr: number;
+    ip: number;
+    op: number;
+    w: number;
+    h: number;
+    nm: string;
+    ddd: 0;
+    assets: unknown[];
+    layers: LottieLayer[];
+}
+/**
+ * Maps AE speed and influence into normalized Lottie Bezier ease control points (o.x, o.y, i.x, i.y).
+ */
+declare function createLottieEase(durationFrames: number, deltaVal: number, outEase?: KeyframeEase, inEase?: KeyframeEase): {
+    o: {
+        x: number;
+        y: number;
+    };
+    i: {
+        x: number;
+        y: number;
+    };
+};
+/**
+ * Serializes a Flair Scene into standard Lottie JSON animation.
+ */
+declare function exportLottie(scene: Scene, options?: LottieExportOptions): LottieAnimation;
+
+interface Fcp7ExportOptions {
+    /** Timeline timebase / frame rate (default 30). */
+    frameRate?: number;
+    /** NTSC flag (default false, or true if 29.97 / 59.94). */
+    ntsc?: boolean;
+    /** Starting timecode (default "00:00:00:00"). */
+    timecodeStart?: string;
+    /** Sequence name override. */
+    sequenceName?: string;
+    /** Media path prefix or file base URL (default "file://localhost/media/"). */
+    mediaPathPrefix?: string;
+    /** Include text generator overlay track for titles/captions (default true). */
+    includeTextTrack?: boolean;
+    /** Include timeline sequence markers (default true). */
+    includeMarkers?: boolean;
+}
+interface EdlExportOptions {
+    /** Timeline timebase / frame rate (default 30). */
+    frameRate?: number;
+    /** Drop frame flag (default false). */
+    dropFrame?: boolean;
+    /** Starting timecode (default "01:00:00:00" as per standard broadcast EDL practice). */
+    timecodeStart?: string;
+    /** Reel name identifier (default "AX", max 8 chars). */
+    reel?: string;
+}
+interface ShotTiming {
+    shot: Shot;
+    index: number;
+    startFrame: number;
+    endFrame: number;
+    durationFrames: number;
+    startMs: number;
+    durationMs: number;
+}
+/**
+ * Calculates start and duration frame boundaries for each shot in a scene.
+ */
+declare function calculateShotTimings(scene: Scene, frameRate?: number): ShotTiming[];
+/**
+ * Converts frame count to standard SMPTE timecode HH:MM:SS:FF.
+ */
+declare function framesToTimecode(frame: number, timebase?: number, dropFrame?: boolean): string;
+/**
+ * Converts standard SMPTE timecode HH:MM:SS:FF to frame count.
+ */
+declare function timecodeToFrames(timecode: string, timebase?: number, dropFrame?: boolean): number;
+/**
+ * Serializes a Flair Scene into Apple Final Cut Pro 7 XML Interchange Format (xmeml v4).
+ * Compatible with Premiere Pro, DaVinci Resolve, and Final Cut Pro.
+ */
+declare function exportFcp7Xml(scene: Scene, options?: Fcp7ExportOptions): string;
+/**
+ * Serializes a Flair Scene into standard CMX 3600 Edit Decision List (EDL).
+ * Fully readable by DaVinci Resolve, Premiere Pro, Avid, and Lightworks.
+ */
+declare function exportCmx3600Edl(scene: Scene, options?: EdlExportOptions): string;
+
+export { ALL_BLEND_MODES, ALL_TRANSITION_TYPES, type AgentToolDefinition, type AscCdl, type BatchCommand, type BatchExecutionResult, type BatchExecutionStepResult, type Behavior, type BehaviorBase, type BlendMode, type BlockDissolveOptions, type BlurEffect, type BurstEffect, CAMERA_MS, COMMON_FRAME_RATES, type ClearCommand, Clock, type ColorRGB, type ColorRGBA, type ColorRgba, type ColorSpace, ControlDef, ControlValue, type CounterEffect, type CrossZoomOptions, type CustomCommand, DEFAULT_STAGE, type DeleteCommand, type DynamicFraming, EASY_EASE, EFFECT_FADE_MS, EFFECT_TYPES, type EasingCurve, type EdlExportOptions, type Effect, type EffectBase, type ElementCommand, FLAIR_AGENT_TOOLS, type Fcp7ExportOptions, type FlowEffect, type FramingOptions, type GifOptions, type GlassWipeOptions, type GlowEffect, type GradientEffect, type GridWipeOptions, type HighlightEffect, type KeyframeEase, type LiftGammaGain, type LightLeakOptions, type LinearWipeOptions, type LottieAnimatable, type LottieAnimation, type LottieExportOptions, type LottieKeyframe, type LottieLayer, type LottieShapeItem, type LottieTransform, type MediaEffect, MemorySceneBoard, type MotnExportOptions, NO_CHECK, type OscillateBehavior, type OvershootBehavior, type PathWaypoint, type PlayOptions, type PlayResult, type Point, type PopupWidget, type RadialIrisOptions, type RampBehavior, type RateBehavior, type RationalFrameRate, type Rect, type RenderOptions, type ReplicatorConfig, type ReplicatorPattern, type ReplicatorSequence, type Review, type ReviewOptions, type RigWidget, type RippleEffect, type RunningEffect, SMALL_TEXT_PX, type SMPTEFields, type Scene, type SceneBoard, type SceneCommand, type SceneElement, type SceneIssue, type SceneMedia, type SceneRig, type SceneToolResult, ShaderFrames, type ShaderFramesOptions, type ShimmerEffect, type Shot, type ShotCamera, type ShotCheck, type ShotLog, type ShotTiming, type SliderSnapshot, type SliderWidget, type SpatialMotionPath, type SpatialPathSample, type SpotlightEffect, type Stage, type StandaloneOptions, type StandardFrameRateKey, type ThrowBehavior, type ThumbnailHandle, ThumbnailPool, type ThumbnailPoolOptions, type TimerEffect, type ToggleWidget, type TransitionOptions, type TransitionSample, type TransitionType, type TwisterOptions, type UpdateCommand, type Vec2, type Vec3, type View, type WriggleBehavior, applyAscCdl, applyLiftGammaGain, applyRig, applySceneBatch, applySceneTool, applyVibrance, areaOf, between, bez1d, bez1dDerivative, blendRgba, blendTransitionPixel, boardHeight, boundsOf, calculateFramingRect, calculateShotTimings, centreOf, checkShot, convertColorSpace, createFrameRate, createLottieEase, createMotionPath, easeInOutCubic, easeProgress, effectGone, effectOpacity, evaluateBehavior, evaluateKeyframeSegment, expandReplicator, exportCmx3600Edl, exportFcp7Xml, exportLottie, exportMotn, formatTimecode, fractalWiggle, frame, framesToSMPTE, framesToTimecode, getColorGradingGLSL, getDropFrameCount, getGlslBlendFunction, getOklabGLSL, getTimecodeBase, getTransitionGLSL, getWhiteBalanceGains, hash64, holdTime, interpolateOklab, interpolateOklch, isDeleteCommand, isElementCommand, isUpdateCommand, linearRgbToSrgb, linearSrgbToOklab, linearToSrgb, loopTime, mixSeeds, noise1d, noise3d, oklabToLinearSrgb, oklabToOklch, oklabToSrgb, oklchToOklab, overlapArea, parseTimecode, pingPongTime, playScene, quinticFade, recordGif, registerThumbnail, reviewScene, sampleMotionPath, sampleMotionPathAtTime, sampleTransition, setRigWidget, sharedThumbnailPool, simulateScene, smpteToFrames, solveBezierU, speedRampTime, srgbToLinear, srgbToLinearRgb, srgbToOklab, standaloneHtml, standaloneSceneHtml, strobeTime, substituteVariables, supportsDropFrame, timecodeToFrames, titleBox, touchedIds, unitFloat, validateScene, viewAt, visibleRect };