@cutcraft/player 0.0.0-stage → 0.1.0

package/dist/nested-Bd4Y7qrF.d.mts

@@ -0,0 +1,720 @@
+import { d as DrawRect, m as Matrix2D, r as ClipRect } from "./backdrop-BqrzCzTB.mjs";
+import { AssetEntry, AssetManifest, EASING_FN, FitMode, Placement, ResolvedState, ResolvedTrack } from "@cutcraft/kit";
+import { Input, VideoSample } from "mediabunny";
+/** 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;
+/** 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;
+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. `path` is a file on disk, for the Node renderer; browsers use `blob` or `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;
+  /**
+   * Optional fast path for a picture that covers the whole `width`×`height` canvas, untransformed, opaque and
+   * normally blended: replace the canvas content with it and return true, or return false to be drawn with `draw`.
+   */
+  paintFull?(ctx: Ctx2D, width: number, height: number): boolean;
+  /**
+   * Makes the picture drawable, for a frame that defers work until it is drawn (the Node renderer converts decoded
+   * pictures to RGBA only then). The compositor awaits it before painting the frame.
+   */
+  prepare?(): Promise<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 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;
+interface FilterResult {
+  readonly filter: string;
+  readonly unsupported: readonly string[];
+}
+/** 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): 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 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[];
+}
+/** 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][];
+declare class ManualClock implements Clock {
+  private t;
+  now(): number;
+  advance(dt: number): void;
+  set(t: number): void;
+}
+declare class PerformanceClock implements Clock {
+  now(): number;
+}
+/** 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;
+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;
+}
+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;
+}
+/** 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;
+}
+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;
+}
+/** How a host customises decoding: the Node renderer converts samples itself and decodes in software. */
+interface FrameSourceHooks {
+  /** Turns a decoded sample into a frame; may convert eagerly (the sample is closed by the frame). */
+  readonly makeFrame?: (sample: VideoSample) => Promise<Frame> | Frame;
+  /** Loads a still image asset. */
+  readonly loadImage?: (handle: MediaHandle) => Promise<ImageBitmap | HTMLImageElement>;
+  readonly hardwareAcceleration?: "no-preference" | "prefer-hardware" | "prefer-software";
+}
+/** 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 readonly hooks;
+  private input;
+  private track;
+  private sink;
+  private stillSink;
+  constructor(assetId: string, handle: MediaHandle, inputs: MediabunnyInputs, createCanvas: CreateCanvas, hooks?: FrameSourceHooks);
+  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, hooks?: FrameSourceHooks): FrameSourceFactory;
+/** 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 track;
+  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;
+/**
+ * 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;
+  constructor(width: number, height: number, createCanvas: CreateCanvas);
+  paint(ctx: Ctx2D, plan: FramePlan, inputs: PaintInputs): void;
+  private drawOp;
+  /** 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;
+  /** A tile of black and white specks, the same for the same seed; alpha up to `amount`. */
+  private noise;
+  private adjust;
+}
+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;
+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;
+}
+/**
+ * Sees a frame's plan and its pictures before they are painted. Returning true means the host takes this frame as it
+ * is (an export handing a decoded picture straight to its encoder): nothing is prepared or painted.
+ */
+type FrameIntercept = (plan: FramePlan, frames: ReadonlyMap<string, Frame | null>) => boolean;
+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;
+  /** This composition's frames only; nested compositions paint as usual. */
+  readonly intercept?: FrameIntercept;
+}
+/**
+ * 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, intercept?: FrameIntercept): Promise<void>;
+  tick(t: number, opts: TickOptions): Promise<void>;
+  dispose(): void;
+  private run;
+  private syncNested;
+}
+/**
+ * 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;
+export { postEffects as $, ImageFrameSource as A, FRAME_EPS as At, buildGainEnvelope as B, QUEUE_MAX as Bt, ClipDecoder as C, devWarn as Ct, ErrorFrame as D, DUCK_ATTACK_S as Dt, AssetSources as E, AUDIO_PRIME_S as Et, ManualClock as F, MAX_RATE as Ft, MaskSpec as G, SEEK_MODE_SPEED as Gt, BackgroundGradient as H, REVERSE_WINDOW_FRAMES as Ht, PerformanceClock as I, MIN_RATE as It, buildFramePlan as J, ResolveNested as K, SETTLE_MS as Kt, AudioOccurrence as L, MOUNT_AHEAD_S as Lt, defaultCreateCanvas as M, INPUT_IDLE_CLOSE_S as Mt, fromMap as N, LOOKAHEAD_S as Nt, ErrorFrameSource as O, DUCK_RELEASE_S as Ot, toResolver as P, MAX_OPEN_INPUTS as Pt, filterString as Q, GainPoint as R, PICK_EPS as Rt, DecoderPool as S, captureWarnings as St, AssetSourceDeps as T, AUDIO_CHUNK_S as Tt, DrawOp as U, REVERSE_WINDOW_S as Ut, duckIntervals as V, QUEUE_TARGET as Vt, FramePlan as W, SCHEDULER_MS as Wt, FilterResult as X, compositionBackground as Y, PostEffect as Z, FrameSourceHooks as _, MediaHandle as _t, TickOptions as a, AudioOutput as at, mediabunnyFrameSourceFactory as b, PlayerEvents as bt, backgroundCss as c, AudioSourceInfo as ct, paintBackground as d, Ctx2D as dt, EASING_FN as et, setMatrix as f, EnvelopePoint as ft, mediabunnyAudioSourceFactory as g, FrameSourceInfo as gt, MediabunnyAudioSource as h, FrameSourceFactory as ht, FrameIntercept as i, AnyCanvas as it, copyFrame as j, FRAME_WAIT_MS as jt, ImageFrame as k, ENVELOPE_STEP_S as kt, backgroundFill as l, Clock as lt, traceMask as m, FrameSource as mt, Compositor as n, hasKeyframes as nt, CanvasPainter as o, AudioSource as ot, roundedRect as p, Frame as pt, blendOf as q, UNMOUNT_BEHIND_S as qt, CompositorDeps as r, keyframedValue as rt, PaintInputs as s, AudioSourceFactory as st, makeNestedResolver as t, ease as tt, coversCanvas as u, CreateCanvas as ut, MediabunnyFrameSource as v, MediaResolver as vt, DecodeMode as w, AUDIO_CACHE_S as wt, MediabunnyInputs as x, ScheduledSource as xt, SampleFrame as y, PlayerErrorEvent as yt, buildAudioPlan as z, PLAY_PRIME_TIMEOUT_MS as zt };