@cutcraft/player 0.0.0-stage → 0.2.0

package/dist/warn-GHM3SBI2.d.mts

@@ -0,0 +1,892 @@
+import { AssetEntry, AssetManifest, DeclaredFont, EASING_FN, FitMode, LayerClock, Placement, ResolvedState, ResolvedTrack, Transform } from "@cutcraft/kit";
+import { Input, VideoSample } from "mediabunny";
+interface PlayerErrorEvent {
+  readonly id?: string;
+  readonly asset?: string;
+  readonly error: Error;
+  readonly fatal: boolean;
+}
+interface PlayerEvents {
+  frameupdate: {
+    readonly time: number;
+    readonly frame: number;
+  };
+  play: {
+    readonly time: number;
+  };
+  pause: {
+    readonly time: number;
+  };
+  seeked: {
+    readonly time: number;
+  };
+  ended: {
+    readonly time: number;
+  };
+  ratechange: {
+    readonly rate: number;
+  };
+  volumechange: {
+    readonly volume: number;
+    readonly muted: boolean;
+  };
+  error: PlayerErrorEvent;
+}
+type Ctx2D = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+type AnyCanvas = HTMLCanvasElement | OffscreenCanvas;
+type CreateCanvas = (width: number, height: number) => AnyCanvas;
+/**
+ * Where an asset's bytes come from. The player reads `blob` and `url`; `path` is a file on disk, which a Node host (the
+ * export's server) serves to the page as a URL.
+ */
+type MediaHandle = {
+  readonly kind: "blob";
+  readonly blob: Blob;
+} | {
+  readonly kind: "url";
+  readonly url: string;
+} | {
+  readonly kind: "path";
+  readonly path: string;
+};
+interface MediaResolver {
+  resolve(assetId: string): Promise<MediaHandle>;
+}
+interface FrameSourceInfo {
+  readonly width: number;
+  readonly height: number;
+  readonly duration: number;
+  readonly fps?: number;
+  readonly decodable: boolean;
+}
+/** One decoded picture. Frames handed out by a source belong to the caller, who closes them. */
+interface Frame {
+  readonly timestamp: number;
+  readonly duration: number;
+  readonly width: number;
+  readonly height: number;
+  draw(ctx: Ctx2D, dx: number, dy: number, dw: number, dh: number, crop?: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+  }): void;
+  /** A copy that outlives the source's pools and the original's `close()`. */
+  retain(): Frame;
+  close(): void;
+}
+interface FrameSource {
+  open(): Promise<FrameSourceInfo>;
+  /** The last frame at or before `sourceTime`, or null before the first frame. */
+  frameAt(sourceTime: number): Promise<Frame | null>;
+  /** Frames from `from` (the frame covering it first) up to `to`, in order. */
+  stream(from: number, to: number): AsyncGenerator<Frame, void, unknown>;
+  close(): void;
+}
+type FrameSourceFactory = (assetId: string, handle: MediaHandle, kind: AssetEntry["kind"]) => FrameSource;
+interface AudioSourceInfo {
+  readonly sampleRate: number;
+  readonly channels: number;
+  readonly duration: number;
+  readonly decodable: boolean;
+}
+interface AudioSource {
+  open(): Promise<AudioSourceInfo>;
+  /** PCM for [from, to) as one buffer whose first sample is `from`. */
+  range(from: number, to: number): Promise<AudioBuffer>;
+  close(): void;
+}
+type AudioSourceFactory = (assetId: string, handle: MediaHandle, context: BaseAudioContext) => AudioSource;
+interface Clock {
+  /** Monotonic seconds. */
+  now(): number;
+}
+interface EnvelopePoint {
+  /** Audio context seconds. */
+  readonly at: number;
+  readonly value: number;
+}
+interface ScheduledSource {
+  /** `${placementId}#${chunk}#${session}`. */
+  readonly key: string;
+  readonly buffer: AudioBuffer;
+  /** Audio context seconds. */
+  readonly when: number;
+  readonly offset: number;
+  readonly duration: number;
+  /** The rate at `when`; `rate`, when set, automates it from there. */
+  readonly playbackRate: number;
+  readonly rate?: readonly EnvelopePoint[];
+  readonly envelope: readonly EnvelopePoint[];
+  readonly pan?: readonly EnvelopePoint[];
+}
+interface AudioOutput {
+  readonly contextTime: number;
+  readonly running: boolean;
+  schedule(src: ScheduledSource): void;
+  /** Stop and disconnect every source whose key starts with `keyPrefix`. */
+  cancel(keyPrefix: string): void;
+  cancelAll(): void;
+  setMaster(gain: number): void;
+  resume(): Promise<void>;
+}
+declare class ManualClock implements Clock {
+  private t;
+  now(): number;
+  advance(dt: number): void;
+  set(t: number): void;
+}
+declare class PerformanceClock implements Clock {
+  now(): number;
+}
+/** Seconds before a clip starts at which its decoder is mounted. */
+declare const MOUNT_AHEAD_S = 2;
+/** Seconds after a clip ends for which its decoder is kept. */
+declare const UNMOUNT_BEHIND_S = 0.5;
+/** Seconds an unreferenced mediabunny Input stays open before it is disposed. */
+declare const INPUT_IDLE_CLOSE_S = 10;
+/** Hard cap on open Inputs; idle ones are evicted LRU first. */
+declare const MAX_OPEN_INPUTS = 6;
+/** Decoded frames a clip decoder keeps queued ahead of the play head. */
+declare const QUEUE_TARGET = 8;
+declare const QUEUE_MAX = 10;
+/** Effective speed (clip speed × rate) above which frames are fetched by seek per tick instead of streamed. */
+declare const SEEK_MODE_SPEED = 4;
+/** Reverse playback pre-decodes this window behind the cursor. */
+declare const REVERSE_WINDOW_S = 1;
+declare const REVERSE_WINDOW_FRAMES = 16;
+/** Longest wait for a frame in `wait` mode (seek, export) before drawing without it. */
+declare const FRAME_WAIT_MS = 250;
+/** Audio scheduler period and horizon. */
+declare const SCHEDULER_MS = 100;
+declare const LOOKAHEAD_S = 0.2;
+/** Source ranges longer than twice this are decoded in chunks of this length. */
+declare const AUDIO_CHUNK_S = 30;
+/** LRU cap, in decoded seconds, on cached PCM. */
+declare const AUDIO_CACHE_S = 600;
+/** Pre-decode window on play, and how long play() waits for it. */
+declare const AUDIO_PRIME_S = 0.5;
+declare const PLAY_PRIME_TIMEOUT_MS = 500;
+/** Ducking defaults. */
+declare const DUCK_ATTACK_S = 0.1;
+declare const DUCK_RELEASE_S = 0.3;
+/** Sampling step for multiplied gain ramps. */
+declare const ENVELOPE_STEP_S = 0.05;
+/** Playback rate clamp. */
+declare const MIN_RATE = 0.25;
+declare const MAX_RATE = 4;
+/** Quiet time after the last setState before a paused preview fetches its exact frame. */
+declare const SETTLE_MS = 120;
+/** Tolerance when rounding a time to a frame index. */
+declare const FRAME_EPS = 0.000001;
+/**
+ * Container timestamps are often rounded to the millisecond, so the frame for
+ * the exact time n/fps can sit a fraction of a millisecond after it. A frame
+ * is picked when its timestamp is at most this far past the wanted time.
+ */
+declare const PICK_EPS = 0.001;
+interface AssetSourceDeps {
+  readonly media: MediaResolver;
+  readonly manifest: AssetManifest;
+  readonly frameSourceFactory: FrameSourceFactory;
+  readonly clock: Clock;
+  readonly onError: (e: PlayerErrorEvent) => void;
+}
+/**
+ * One FrameSource per asset, shared by every clip of that asset and by nested
+ * compositors. Ref-counted; an unreferenced source stays open for a while
+ * (a seek back is cheap) and is closed when idle too long or when too many
+ * are open.
+ */
+declare class AssetSources {
+  private readonly deps;
+  private readonly entries;
+  private readonly errored;
+  constructor(deps: AssetSourceDeps);
+  /** Acquire a reference; the source opens lazily on first use. */
+  acquire(assetId: string): {
+    source: FrameSource;
+    info: Promise<FrameSourceInfo>;
+  };
+  release(assetId: string): void;
+  /** Close sources idle for too long, then the least recently used idle ones beyond the cap. */
+  sweep(): void;
+  get openCount(): number;
+  isOpen(assetId: string): boolean;
+  dispose(): void;
+  private close;
+  private open;
+}
+type DecodeMode = "forward" | "reverse" | "seek";
+/**
+ * Decoded frames for one placement. Forward playback streams from the source
+ * into a short queue; reverse pre-decodes windows behind the cursor; seek
+ * mode (high speeds, scrubbing) fetches single frames. Freezes hold one
+ * retained frame. The decoder never blocks a playing tick: when the frame for
+ * `t` is not ready it returns the last frame it delivered.
+ */
+declare class ClipDecoder {
+  private readonly source;
+  private readonly effectiveSpeed;
+  readonly id: string;
+  readonly sourceKey: string;
+  private queue;
+  private current;
+  private generation;
+  private gen;
+  private pumping;
+  private streamEnd;
+  private seekPending;
+  private reverseLow;
+  private reverseLoading;
+  private readonly freezes;
+  private disposed;
+  private primed;
+  private _placement;
+  private _children;
+  constructor(source: FrameSource, placement: Placement, children: readonly Placement[], effectiveSpeed: () => number);
+  /** Asset and direction: everything else (trim, speed, freezes) may change under a live decoder. */
+  static sourceKey(p: Placement): string;
+  get placement(): Placement;
+  get children(): readonly Placement[];
+  /**
+   * Take a new resolve of the same placement. A trim or speed change moves
+   * where source time lands; the queue is kept and the next `frameFor` reseeks
+   * only if the new source time falls outside what is queued.
+   */
+  update(placement: Placement, children: readonly Placement[]): void;
+  get mode(): DecodeMode;
+  get queued(): number;
+  get ready(): Promise<void>;
+  sourceTime(t: number): number;
+  /** Jump to composition time `t`: cancel streaming, fetch the frame, restart from there. */
+  prime(t: number): Promise<void>;
+  /**
+   * The frame to draw at composition time `t`. With `wait`, fetch it if it is
+   * not queued, for at most `FRAME_WAIT_MS`; with `exact` as well, for as long
+   * as it takes, so an export never draws a frame it did not wait for.
+   */
+  frameFor(t: number, wait: boolean, exact?: boolean): Promise<Frame | null>;
+  /** Close consumed frames; called after a frame was painted. */
+  advance(t: number): void;
+  dispose(): void;
+  private forwardFrame;
+  /** The newest queued frame at or before `st` becomes current; older ones are consumed. */
+  private forwardPick;
+  private primeAtSource;
+  private startStream;
+  private pump;
+  /** Pull frames until the queue is at target; a caller that finds a pump running awaits that one. */
+  private pumpOnce;
+  private seekFrame;
+  private reverseFrame;
+  private loadReverseWindow;
+  private activeFreeze;
+  private freezeFrame;
+  private setCurrent;
+  private cancelStream;
+}
+/**
+ * Keeps a ClipDecoder for every media placement near the play head and drops
+ * the rest. Asset sources are shared through `AssetSources`, so nested
+ * compositors handed the same registry never open an asset twice.
+ */
+declare class DecoderPool {
+  readonly sources: AssetSources;
+  private readonly decoders;
+  private rate;
+  constructor(sources: AssetSources);
+  setRate(rate: number): void;
+  /** Mount decoders for placements within the window around `t`; unmount the rest. */
+  sync(state: ResolvedState, t: number): void;
+  decoderFor(id: string): ClipDecoder | undefined;
+  get mounted(): string[];
+  /** After a seek: every decoder jumps to `t`. */
+  seekAll(t: number): Promise<void>;
+  /** Resolves when every decoder has its first frame. */
+  settle(): Promise<void>;
+  dispose(): void;
+  private unmount;
+}
+/** A face to add to the page's fonts, from a URL or the file's bytes. */
+interface FontFaceSource {
+  readonly family: string;
+  readonly weight?: number;
+  readonly style?: "normal" | "italic";
+  readonly source: string | ArrayBuffer;
+}
+/**
+ * Adds faces to `document.fonts` and resolves once every one has loaded. A URL source loads from that URL; bytes load as
+ * given. Does nothing where there is no `FontFace` (Node, tests).
+ */
+declare function addFontFaces(faces: readonly FontFaceSource[]): Promise<void>;
+/**
+ * Loads the faces a file declares (`state.fonts`) into the page: an `asset:` face is asked of `media` as an asset is,
+ * a Google face loads from Google's stylesheet. Resolves once all have loaded; a face that fails is reported through
+ * `onError` and the rest load. Does nothing where there is no `FontFace` (Node, tests).
+ */
+declare function loadFileFonts(faces: readonly DeclaredFont[], media: MediaResolver, onError: (family: string, error: Error) => void): Promise<void>;
+declare function defaultCreateCanvas(width: number, height: number): AnyCanvas;
+type Crop$1 = {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+};
+/** A frame backed by an image we own (canvas or bitmap); `retain` is free. */
+declare class ImageFrame implements Frame {
+  private readonly image;
+  readonly timestamp: number;
+  readonly duration: number;
+  private readonly owned;
+  constructor(image: CanvasImageSource & {
+    width: number;
+    height: number;
+  }, timestamp: number, duration: number, owned: boolean);
+  get width(): number;
+  get height(): number;
+  draw(ctx: Ctx2D, dx: number, dy: number, dw: number, dh: number, crop?: Crop$1): void;
+  retain(): Frame;
+  close(): void;
+}
+/** Copies any frame into a canvas we own. */
+declare function copyFrame(frame: Frame, createCanvas: CreateCanvas): Frame;
+/** Still images: one bitmap, returned for every time. */
+declare class ImageFrameSource implements FrameSource {
+  private readonly load;
+  private bitmap;
+  constructor(load: () => Promise<ImageBitmap | HTMLImageElement>);
+  open(): Promise<FrameSourceInfo>;
+  frameAt(): Promise<Frame | null>;
+  stream(): AsyncGenerator<Frame, void, unknown>;
+  close(): void;
+  private frame;
+}
+/** Draws a grey box with a label; used for missing or undecodable assets. */
+declare class ErrorFrame implements Frame {
+  readonly width: number;
+  readonly height: number;
+  private readonly label;
+  readonly timestamp = 0;
+  readonly duration: number;
+  constructor(width: number, height: number, label: string);
+  draw(ctx: Ctx2D, dx: number, dy: number, dw: number, dh: number): void;
+  retain(): Frame;
+  close(): void;
+}
+declare class ErrorFrameSource implements FrameSource {
+  private readonly frame;
+  constructor(label: string, width?: number, height?: number);
+  open(): Promise<FrameSourceInfo>;
+  frameAt(): Promise<Frame | null>;
+  stream(): AsyncGenerator<Frame, void, unknown>;
+  close(): void;
+}
+/** One mediabunny `Input` per asset, shared by the video and audio sources of that asset. */
+declare class MediabunnyInputs {
+  private readonly entries;
+  acquire(assetId: string, handle: MediaHandle): Input;
+  release(assetId: string): void;
+  get openCount(): number;
+  dispose(): void;
+}
+/** PCM ranges of one audio track, decoded on demand into AudioBuffers of the track's sample rate. */
+declare class MediabunnyAudioSource implements AudioSource {
+  private readonly assetId;
+  private readonly handle;
+  private readonly inputs;
+  private readonly context;
+  private readonly trackIndex;
+  private input;
+  private sink;
+  private sampleRate;
+  private channels;
+  constructor(assetId: string, handle: MediaHandle, inputs: MediabunnyInputs, context: BaseAudioContext, trackIndex?: number);
+  open(): Promise<AudioSourceInfo>;
+  range(from: number, to: number): Promise<AudioBuffer>;
+  close(): void;
+}
+declare function mediabunnyAudioSourceFactory(inputs: MediabunnyInputs): AudioSourceFactory;
+type Crop = {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+};
+/** A decoded `VideoSample`: GPU-backed, drawn straight to the context, closed when consumed. */
+declare class SampleFrame implements Frame {
+  private readonly sample;
+  private readonly createCanvas;
+  readonly timestamp: number;
+  readonly duration: number;
+  readonly width: number;
+  readonly height: number;
+  constructor(sample: VideoSample, createCanvas: CreateCanvas);
+  draw(ctx: Ctx2D, dx: number, dy: number, dw: number, dh: number, crop?: Crop): void;
+  retain(): Frame;
+  close(): void;
+}
+/** Frames of one video asset through a shared `VideoSampleSink`. */
+declare class MediabunnyFrameSource implements FrameSource {
+  private readonly assetId;
+  private readonly handle;
+  private readonly inputs;
+  private readonly createCanvas;
+  private input;
+  private track;
+  private sink;
+  private stillSink;
+  constructor(assetId: string, handle: MediaHandle, inputs: MediabunnyInputs, createCanvas: CreateCanvas);
+  private wrap;
+  open(): Promise<FrameSourceInfo>;
+  frameAt(sourceTime: number): Promise<Frame | null>;
+  stream(from: number, to: number): AsyncGenerator<Frame, void, unknown>;
+  /** A canvas copy of the frame at `sourceTime`, for freeze frames; pooled canvases are copied right away. */
+  still(sourceTime: number): Promise<Frame | null>;
+  close(): void;
+}
+declare function mediabunnyFrameSourceFactory(inputs: MediabunnyInputs, createCanvas: CreateCanvas): FrameSourceFactory;
+/** A resolver over a map of asset id → Blob or URL. */
+declare function fromMap(map: Readonly<Record<string, Blob | string>>): MediaResolver;
+declare function toResolver(media: MediaResolver | Readonly<Record<string, Blob | string>>): MediaResolver;
+interface FilterResult {
+  readonly filter: string;
+  readonly unsupported: readonly string[];
+}
+type Params = Readonly<Record<string, unknown>>;
+/** An effect's params with its keyframed ones (`effect.<id>.<param>` keyframes on the element) evaluated at element-relative `rel`. */
+declare function paramsAt(children: readonly Placement[], effect: Placement, rel: number): Params;
+/** A single canvas/CSS `filter` string for an element's effect and colour-grade children at element-relative `rel`; unsupported types are listed. */
+declare function filterString(children: readonly Placement[], elementId: string, rel: number,
+/** Effect types the file declares (`defineEffect()`), drawn as shaders rather than filters. */
+declared?: ReadonlySet<string>): FilterResult;
+type PostEffect = {
+  readonly type: "vignette";
+  readonly amount: number;
+} | {
+  readonly type: "grain";
+  readonly amount: number;
+  readonly seed: number;
+};
+/** Vignette and grain, in order, with `amount` on 0..1; grain is seeded by the frame, so a frame always looks the same. */
+declare function postEffects(children: readonly Placement[], frame: number, rel: number): PostEffect[] | undefined;
+interface DrawRect {
+  readonly x: number;
+  readonly y: number;
+  readonly w: number;
+  readonly h: number;
+}
+/** Row-major 2D affine matrix in the canvas/CSS `matrix(a, b, c, d, e, f)` convention. */
+interface Matrix2D {
+  readonly a: number;
+  readonly b: number;
+  readonly c: number;
+  readonly d: number;
+  readonly e: number;
+  readonly f: number;
+}
+interface Layout {
+  /** Where the element lands in composition pixels before its transform. */
+  readonly rect: DrawRect;
+  /** Maps local element coordinates (0..rect.w, 0..rect.h) to composition coordinates. */
+  readonly matrix: Matrix2D;
+  /** Source sub-rectangle in source pixels, when cropped. */
+  readonly crop?: DrawRect;
+  readonly opacity: number;
+}
+declare const IDENTITY: Matrix2D;
+declare function multiply(m: Matrix2D, n: Matrix2D): Matrix2D;
+declare const translate: (x: number, y: number) => Matrix2D;
+declare const scaleM: (sx: number, sy: number) => Matrix2D;
+declare function rotate(deg: number): Matrix2D;
+declare function matrixToCss(m: Matrix2D): string;
+interface Box {
+  readonly width: number;
+  readonly height: number;
+}
+/** The fitted rectangle of a source inside the composition, centred. */
+declare function fitRect(comp: Box, src: Box, fit: FitMode): DrawRect;
+/**
+ * Lay out a source of `src` pixels in the composition: crop, fit, then the
+ * element transform (position offset, scale, rotation about the anchor).
+ */
+declare function layoutRect(comp: Box, src: Box, fit: FitMode, transform?: Transform | undefined): Layout;
+/** The matrix mapping an element's local pixels to the composition, given its untransformed rect. */
+declare function transformMatrix(rect: DrawRect, t: Transform | undefined): Matrix2D;
+/** The upright box around `rect` after `m`: where a rectangle of an element's local pixels lands in the composition. */
+declare function boundsOf(rect: DrawRect, m: Matrix2D): DrawRect;
+/** The transform with its keyframed properties evaluated at element-relative time `rel`. */
+declare function animatedTransform(base: Transform | undefined, children: readonly Placement[], rel: number): Transform;
+/** CSS for a DOM element laid out like `layoutRect` does: it sits at the origin with `transform-origin: 0 0`. */
+declare function cssTransform(layout: Layout): string;
+/** An entrance or exit as the schema writes it. */
+interface GraphicAnimation {
+  readonly type: string;
+  readonly duration?: number;
+  readonly easing?: string;
+}
+/** A rectangle in the element's own pixels. */
+interface ClipRect {
+  readonly x: number;
+  readonly y: number;
+  readonly w: number;
+  readonly h: number;
+}
+/**
+ * What an element's entrance and exit do to it at one moment, in its own pixels:
+ * an opacity factor, a matrix applied before its layout, the part of it shown
+ * (null for all of it) and how much of its strokes are drawn (null when not drawing).
+ */
+interface Motion {
+  readonly opacity: number;
+  readonly matrix: Matrix2D;
+  readonly clip: readonly ClipRect[] | null;
+  readonly draw: number | null;
+}
+declare const STILL: Motion;
+/**
+ * The entrance and exit of an element `rel` seconds into its `duration`, for a
+ * `width` by `height` box. Both can play at once on a short element; their
+ * effects multiply. Pop, bounce and elastic carry their own curve; the others
+ * follow the animation's easing (default ease-out).
+ */
+declare function motionAt(enter: GraphicAnimation | undefined, exit: GraphicAnimation | undefined, rel: number, duration: number, width: number, height: number): Motion;
+/** One animation at raw progress `x` (0 hidden, 1 fully shown). */
+declare function effect(anim: GraphicAnimation, x: number, w: number, h: number): Motion;
+/** Both effects at once: opacities and draw amounts multiply, matrices compose, clips intersect. */
+declare function combine(a: Motion, b: Motion): Motion;
+interface TransitionRole {
+  readonly placement: Placement;
+  readonly role: "out" | "in";
+  /** 0..1 through the transition, eased by its curve. */
+  readonly progress: number;
+}
+interface VisibleItem {
+  readonly placement: Placement;
+  readonly track: ResolvedTrack;
+  readonly children: readonly Placement[];
+  readonly transition?: TransitionRole;
+}
+/** Visual, timed placements that show at `t`: tracks in document order (the first track is the bottom), items in track order. */
+declare function visiblePlacements(state: ResolvedState, t: number): VisibleItem[];
+declare function isVisibleAt(p: Placement, t: number, compositionDuration: number): boolean;
+/** Placements that sit on a track, in track order; a multicam's generated clips follow their parent. */
+declare function trackItems(state: ResolvedState, track: ResolvedTrack): Placement[];
+/** One declared effect (`defineEffect()`) to run over an element's picture, with its params at this moment. */
+interface ShaderPass {
+  readonly name: string;
+  readonly source: string;
+  readonly params: Readonly<Record<string, unknown>>;
+  /** Seconds into the element. */
+  readonly time: number;
+}
+/** A declared transition (`defineTransition()`) on one side of it at this moment. */
+interface TransitionPass {
+  /** The transition's id, which pairs the outgoing side with the incoming one. */
+  readonly id: string;
+  readonly name: string;
+  readonly source: string;
+  readonly params: Readonly<Record<string, unknown>>;
+  /** 0..1 through the transition, eased by its curve. */
+  readonly progress: number;
+  readonly time: number;
+  readonly role: "out" | "in";
+  /** Between two clips, whose pictures the shader blends; false for one clip's edge, blended with nothing. */
+  readonly paired: boolean;
+}
+interface MaskSpec {
+  readonly shape?: Record<string, unknown> | undefined;
+  readonly path?: {
+    points: {
+      x: number;
+      y: number;
+      handleIn?: {
+        x: number;
+        y: number;
+      };
+      handleOut?: {
+        x: number;
+        y: number;
+      };
+    }[];
+    closed: boolean;
+  } | undefined;
+  readonly feather: number;
+  readonly inverted: boolean;
+  readonly opacity: number;
+}
+interface DrawOp {
+  readonly id: string;
+  readonly kind: "video" | "image" | "nested" | "error" | "adjustment";
+  readonly asset?: string;
+  readonly sourceTime?: number;
+  readonly nested?: {
+    readonly state: ResolvedState;
+    readonly time: number;
+  };
+  readonly rect: DrawRect;
+  readonly matrix: Matrix2D;
+  readonly crop?: DrawRect;
+  /** Dimensions used to express crop pixels; decoded proxies can have another resolution. */
+  readonly cropReference?: {
+    readonly width: number;
+    readonly height: number;
+  };
+  readonly fit: FitMode;
+  readonly opacity: number;
+  readonly blend: GlobalCompositeOperation;
+  readonly filter: string;
+  readonly borderRadius: number;
+  readonly mask?: MaskSpec;
+  /** The part shown, in composition pixels (a wipe). */
+  readonly clip?: readonly ClipRect[];
+  /** Vignette and grain, drawn over the element's own pixels. */
+  readonly post?: readonly PostEffect[];
+  /** Effects the file declares (`defineEffect()`), run over the element's picture in order. */
+  readonly shaders?: readonly ShaderPass[];
+  /** A transition the file declares (`defineTransition()`) on this side of it; replaces the built-in look. */
+  readonly transition?: TransitionPass;
+}
+/** A composition background gradient, as the schema writes it. CSS angles: 0 points up, 180 (the default) runs down. */
+interface BackgroundGradient {
+  readonly type: "linear" | "radial" | "conic";
+  readonly angle?: number;
+  readonly center?: {
+    readonly x: number;
+    readonly y: number;
+  };
+  readonly stops: readonly {
+    readonly offset: number;
+    readonly color: string;
+    readonly opacity?: number;
+  }[];
+}
+interface FramePlan {
+  readonly time: number;
+  readonly frame: number;
+  readonly background: string;
+  /** A gradient that fills the frame instead of `background` (which is then its first colour). */
+  readonly backgroundGradient?: BackgroundGradient;
+  /** The footage goes over a transparent ground: overlays beneath it (see `backdropTracks`) and the background are drawn under the canvas. */
+  readonly clear?: true;
+  /** `background.mode: "blur"`: this op's picture, blurred to cover the frame, goes under everything. */
+  readonly backgroundBlur?: {
+    readonly id: string;
+  };
+  readonly ops: readonly DrawOp[];
+  readonly warnings: readonly string[];
+}
+type ResolveNested = (p: Placement) => ResolvedState | null;
+declare function blendOf(value: unknown): GlobalCompositeOperation;
+/**
+ * Everything the painter needs to draw composition time `t`, in draw order.
+ * Pure: the same state and time give a deep-equal plan. DOM-rendered kinds
+ * (title, shape, svg, sticker, layer, captions) are not in it; the DOM layer
+ * reads `visiblePlacements` itself.
+ */
+declare function buildFramePlan(state: ResolvedState, t: number, resolveNested?: ResolveNested): FramePlan;
+/** The composition's background as the painter draws it: a colour, or a gradient (whose first colour is `background`). */
+declare function compositionBackground(state: ResolvedState): {
+  background: string;
+  backgroundGradient?: BackgroundGradient;
+  blur: boolean;
+};
+/** A gain breakpoint in composition seconds. */
+type GainPoint = readonly [t: number, value: number];
+interface AudioOccurrence {
+  readonly id: string;
+  readonly asset: string;
+  readonly chunk: number;
+  /** Composition range of this chunk, unclipped; the engine clips to "now". */
+  readonly compStart: number;
+  readonly compEnd: number;
+  /** Source seconds of the chunk's buffer; stable across windows so decoded PCM caches. */
+  readonly bufferFrom: number;
+  readonly bufferTo: number;
+  /** Placement speed; the engine multiplies in the transport rate. Ignored when `rate` is set. */
+  readonly speed: number;
+  /** Speed-key ramp: buffer seconds per composition second, piecewise linear over [compStart, compEnd]. */
+  readonly rate?: readonly GainPoint[];
+  readonly gain: readonly GainPoint[];
+  readonly pan?: readonly GainPoint[];
+  /** The buffer plays backwards: the engine reverses the decoded PCM. */
+  readonly reverse?: true;
+}
+/** Every audio-bearing chunk that overlaps [from, to). */
+declare function buildAudioPlan(state: ResolvedState, from: number, to: number, resolveNested?: ResolveNested): AudioOccurrence[];
+/**
+ * Gain over [winFrom, winTo] in composition seconds: volume × keyframed
+ * `audio.volume` × fades × automation × ducking. The factors are multiplied
+ * and sampled at their breakpoints plus a fixed step inside ramps, so the
+ * product stays close to piecewise linear.
+ */
+declare function buildGainEnvelope(p: Placement, track: ResolvedTrack, state: ResolvedState, winFrom: number, winTo: number): GainPoint[];
+/** Composition intervals where sound plays on the track `under` names by id, else on the tracks of that role; silent assets and muted clips do not duck. */
+declare function duckIntervals(state: ResolvedState, under: string, exceptId: string): [number, number][];
+/** Kinds the overlay plane draws (as DOM, in the preview and the export) rather than the canvas. */
+declare const OVERLAY_KINDS: ReadonlySet<string>;
+/**
+ * The tracks whose overlays draw beneath the footage: those below every
+ * visible track that holds footage, when one of them holds an overlay (a
+ * background graphic under the cut, say). Empty otherwise, and then every
+ * overlay draws above the footage as before. When it is not empty, the canvas
+ * holds only the footage over a transparent ground, and the composition
+ * background is painted beneath the backdrop instead.
+ */
+declare function backdropTracks(state: ResolvedState): ReadonlySet<string>;
+declare function ease(name: string | undefined, x: number): number;
+/**
+ * The keyframed value of `property` at element-relative time `rel`. Holds
+ * before the first and after the last key; the segment between two keys uses
+ * the easing of the key it leaves. Non-numeric values step.
+ */
+declare function keyframedValue<T>(children: readonly Placement[], property: string, rel: number, fallback: T): T;
+declare function hasKeyframes(children: readonly Placement[], property: string): boolean;
+declare function frameIndex(t: number, fps: number): number;
+declare function frameTime(frame: number, fps: number): number;
+/** `mm:ss.ff` for a composition time, what the controls show and the contact sheet labels. */
+declare function timecode(t: number, fps: number): string;
+/** 0..1 progress through a placement, what `useT()` returns inside a Layer. */
+declare function localT(p: Placement, t: number): number;
+/** What `useLayer()` returns inside a Layer: progress plus real seconds. */
+declare function layerClock(p: Placement, t: number, fps: number): LayerClock;
+/**
+ * Source seconds a media placement shows at composition time `t`: in/out
+ * trim, constant speed or a speed-key ramp, reverse, and freeze holds.
+ * A freeze is an insert hold: it shows `at` over its window, then the clip
+ * resumes from where it stopped; the result is clamped to the trimmed range.
+ */
+declare function placementSourceTime(p: Placement, children: readonly Placement[], t: number): number;
+declare function nestedSourceTime(p: Placement, t: number): number;
+/**
+ * Resolves `<Nested of={Helper}>` through the kit's `resolveScene`, once per
+ * helper. File references (`of="file:..."`) have no loader yet and resolve
+ * to nothing.
+ */
+declare function makeNestedResolver(parent: () => ResolvedState): ResolveNested;
+interface CompositorDeps {
+  readonly sources: AssetSources;
+  readonly createCanvas: CreateCanvas;
+  readonly resolveNested?: ResolveNested | undefined;
+  /** Called after a frame was painted with a new frame index. */
+  readonly onFrame?: ((time: number, frame: number) => void) | undefined;
+}
+interface TickOptions {
+  /** Fetch missing frames before painting (seek, export). */
+  readonly wait: boolean;
+  /** With `wait`: no deadline. An export waits for every frame instead of drawing a stale one. */
+  readonly exact?: boolean;
+}
+/**
+ * One tick: plan the frame, sync decoders, gather frames, paint. A tick that
+ * arrives while another is in flight is coalesced into one re-run; a tick on
+ * the same frame index as the last paint only keeps decoders prefetching.
+ */
+declare class Compositor {
+  private readonly deps;
+  readonly pool: DecoderPool;
+  private painter;
+  private ctx;
+  private state;
+  private inFlight;
+  private pending;
+  private lastFrame;
+  private lastPlan;
+  private readonly nested;
+  private disposed;
+  constructor(state: ResolvedState, deps: CompositorDeps);
+  attach(ctx: Ctx2D | null): void;
+  get renderedFrame(): number;
+  get attachedContext(): Ctx2D | null;
+  get lastPlanBuilt(): FramePlan | null;
+  get currentState(): ResolvedState;
+  setState(state: ResolvedState): void;
+  setRate(rate: number): void;
+  plan(t: number): FramePlan;
+  /** Jump every decoder (nested ones too) to `t`. */
+  seek(t: number): Promise<void>;
+  /**
+   * The next frame of a sequential render (export): decoders keep streaming
+   * from where they are instead of being re-primed, and every frame is waited
+   * for. Paint order and output are the same as `seek` then `tick`, at a
+   * fraction of the decode work.
+   */
+  step(t: number): Promise<void>;
+  tick(t: number, opts: TickOptions): Promise<void>;
+  dispose(): void;
+  private run;
+  private syncNested;
+}
+/**
+ * Trace the mask outline onto the context's current path, in local element
+ * pixels. Shape coordinates are fractions of the element box; bezier paths
+ * are in pixels with handles. Returns false when the spec has no usable shape.
+ */
+declare function traceMask(ctx: Ctx2D, mask: MaskSpec, rect: DrawRect): boolean;
+declare function roundedRect(ctx: Ctx2D, x: number, y: number, w: number, h: number, r: number): void;
+interface PaintInputs {
+  readonly frames: ReadonlyMap<string, Frame | null>;
+  readonly nested: ReadonlyMap<string, AnyCanvas>;
+}
+/**
+ * Executes a FramePlan on a 2D context of composition size. Each op is
+ * drawn under its own transform, alpha, blend and filter; masks clip; an
+ * adjustment op re-filters everything drawn so far through a scratch canvas.
+ */
+declare class CanvasPainter {
+  readonly width: number;
+  readonly height: number;
+  private readonly createCanvas;
+  private scratch;
+  /** An element drawn on its own before compositing: a feathered mask, vignette, grain. */
+  private layer;
+  private grain;
+  /** Runs the effects and transitions the file declares; made on first use. */
+  private shaders;
+  /** The outgoing side of a declared transition between two clips, waiting for the incoming side. */
+  private outgoing;
+  private outgoingPicture;
+  constructor(width: number, height: number, createCanvas: CreateCanvas);
+  paint(ctx: Ctx2D, plan: FramePlan, inputs: PaintInputs): void;
+  private drawOp;
+  /**
+   * An element with effects or a transition the file declares: drawn alone, run through its shaders, then composited.
+   * The outgoing side of a transition between two clips is kept until the incoming side arrives, and the two are
+   * blended in one pass.
+   */
+  private drawShaded;
+  private runner;
+  private outgoingCanvas;
+  /** The footage's picture, blurred and scaled to cover the frame, under everything; skipped when the footage covers the frame itself. */
+  private blurBackground;
+  private blit;
+  /** Applies the border radius and mask as a clip in local coordinates. Returns true when a mask clip was set. */
+  private clip;
+  /**
+   * The element alone on the layer canvas, then composited: a feathered mask punches it out with a
+   * blurred alpha there, and vignette and grain darken or speckle only its own pixels.
+   */
+  private drawLayered;
+  /** The element drawn alone on the layer canvas, at its place in the frame, its mask and vignette or grain applied. */
+  private alone;
+  /** A picture of the whole frame composited as the op: its opacity, blend, filter, wipe and rounded corners. */
+  private composite;
+  /** A tile of black and white specks, the same for the same seed; alpha up to `amount`. */
+  private noise;
+  private adjust;
+  /** An adjustment with declared effects: everything drawn so far, through the shaders, back over itself. */
+  private adjustShaded;
+}
+declare function setMatrix(ctx: Ctx2D, m: Matrix2D): void;
+/** Whether a draw op puts its picture over the whole canvas as it is: no transform, crop, clip, fade, filter or blend. */
+declare function coversCanvas(op: DrawOp, width: number, height: number): boolean;
+/** The composition background (a colour or a gradient) over the whole frame. */
+declare function paintBackground(ctx: Ctx2D, plan: Pick<FramePlan, "background" | "backgroundGradient">, w: number, h: number): void;
+/** The same background as CSS, for the preview's ground under backdrop overlays. */
+declare function backgroundCss(plan: Pick<FramePlan, "background" | "backgroundGradient">): string;
+/** A canvas gradient for the frame, laid out the way CSS lays out the same gradient on a box of this size. */
+declare function backgroundFill(ctx: Ctx2D, g: BackgroundGradient, w: number, h: number): CanvasGradient | string;
+/** Warn once per key. Tests capture warnings with `captureWarnings`. */
+declare function devWarn(key: string, message: string): void;
+declare function captureWarnings(fn: ((message: string) => void) | null): void;
+export { motionAt as $, MAX_OPEN_INPUTS as $t, GainPoint as A, PlayerErrorEvent as An, ErrorFrameSource as At, buildFramePlan as B, DecodeMode as Bt, EASING_FN as C, EnvelopePoint as Cn, MediabunnyFrameSource as Ct, OVERLAY_KINDS as D, FrameSourceInfo as Dn, mediabunnyAudioSourceFactory as Dt, keyframedValue as E, FrameSourceFactory as En, MediabunnyAudioSource as Et, DrawOp as F, FontFaceSource as Ft, trackItems as G, AUDIO_PRIME_S as Gt, TransitionRole as H, AssetSources as Ht, FramePlan as I, addFontFaces as It, GraphicAnimation as J, ENVELOPE_STEP_S as Jt, visiblePlacements as K, DUCK_ATTACK_S as Kt, MaskSpec as L, loadFileFonts as Lt, buildGainEnvelope as M, ScheduledSource as Mn, ImageFrameSource as Mt, duckIntervals as N, copyFrame as Nt, backdropTracks as O, MediaHandle as On, MediabunnyInputs as Ot, BackgroundGradient as P, defaultCreateCanvas as Pt, effect as Q, LOOKAHEAD_S as Qt, ResolveNested as R, DecoderPool as Rt, timecode as S, Ctx2D as Sn, toResolver as St, hasKeyframes as T, FrameSource as Tn, mediabunnyFrameSourceFactory as Tt, VisibleItem as U, AUDIO_CACHE_S as Ut, compositionBackground as V, AssetSourceDeps as Vt, isVisibleAt as W, AUDIO_CHUNK_S as Wt, STILL as X, FRAME_WAIT_MS as Xt, Motion as Y, FRAME_EPS as Yt, combine as Z, INPUT_IDLE_CLOSE_S as Zt, frameTime as _, AudioSource as _n, PostEffect as _t, backgroundCss as a, QUEUE_MAX as an, animatedTransform as at, nestedSourceTime as b, Clock as bn, postEffects as bt, paintBackground as c, REVERSE_WINDOW_S as cn, fitRect as ct, traceMask as d, SETTLE_MS as dn, multiply as dt, MAX_RATE as en, Box as et, Compositor as f, UNMOUNT_BEHIND_S as fn, rotate as ft, frameIndex as g, AudioOutput as gn, FilterResult as gt, makeNestedResolver as h, AnyCanvas as hn, translate as ht, PaintInputs as i, PLAY_PRIME_TIMEOUT_MS as in, Matrix2D as it, buildAudioPlan as j, PlayerEvents as jn, ImageFrame as jt, AudioOccurrence as k, MediaResolver as kn, ErrorFrame as kt, setMatrix as l, SCHEDULER_MS as ln, layoutRect as lt, TickOptions as m, PerformanceClock as mn, transformMatrix as mt, devWarn as n, MOUNT_AHEAD_S as nn, IDENTITY as nt, backgroundFill as o, QUEUE_TARGET as on, boundsOf as ot, CompositorDeps as p, ManualClock as pn, scaleM as pt, ClipRect as q, DUCK_RELEASE_S as qt, CanvasPainter as r, PICK_EPS as rn, Layout as rt, coversCanvas as s, REVERSE_WINDOW_FRAMES as sn, cssTransform as st, captureWarnings as t, MIN_RATE as tn, DrawRect as tt, roundedRect as u, SEEK_MODE_SPEED as un, matrixToCss as ut, layerClock as v, AudioSourceFactory as vn, filterString as vt, ease as w, Frame as wn, SampleFrame as wt, placementSourceTime as x, CreateCanvas as xn, fromMap as xt, localT as y, AudioSourceInfo as yn, paramsAt as yt, blendOf as z, ClipDecoder as zt };