@cutcraft/player 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bohdan Snisar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+<p align="center"><img src="https://raw.githubusercontent.com/prefix-tree/cutcraft/main/docs/public/logo.svg" width="64" alt="CutCraft"></p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @cutcraft/player
+
+Plays a [CutCraft](https://prefix-tree.github.io/cutcraft/) video file in the browser. Footage is decoded with
+WebCodecs through [mediabunny](https://mediabunny.dev) and drawn on one canvas, overlays are React DOM on top of it,
+and Web Audio mixes the sound and keeps the time.
+
+```sh
+npm install @cutcraft/player @cutcraft/kit react react-dom
+```
+
+```tsx
+import { collectModule, resolve } from "@cutcraft/kit";
+import { Player } from "@cutcraft/player";
+import "@cutcraft/player/fonts.css";
+import * as file from "./video";
+
+const state = resolve(collectModule(file), manifest);
+
+<Player state={state} element={file.default(file.defaults)} media={{ interview: blob, bed: "/bed.ogg" }} controls />
+```
+
+`media` maps asset ids to Blobs or URLs, or you can pass your own `MediaResolver`. `element` is the rendered file; the
+player needs it to draw what is inside each `<Layer>`.
+
+## What you get
+
+- Frame-exact seeking. `seekTo(t)` draws the frame for `t` whether the player is paused or playing.
+- Smooth scrubbing and trimming. A drag repaints from frames already decoded, then fetches the exact frame once the
+  pointer rests.
+- Playback from 0.25× to 4× and looped, with speed ramps and freeze frames and their sound.
+- A clock that does not drift: time comes from `AudioContext.currentTime`.
+- Every overlay carries `data-el` and `data-kind`, and the root carries `data-time` and `data-frame`, so tests and
+  agents can find things on screen.
+- `captureSheet(times, { columns })` returns a labelled contact sheet of frames, a quick way to check a cut without
+  exporting it.
+
+## API
+
+`<Player>` takes `state`, `element`, `media`, `controls`, `loop`, `autoPlay`, `initiallyMuted`, `playbackRate`, `fit`,
+`onError` and `onFrame`, and exposes a `PlayerRef`. Hooks: `usePlayer`, `useCompositionTime`, `useCompositionFrame`, `useLayerT`.
+Mounting a player makes the kit's `useT()` and `useLayer()` return the current time.
+
+`PlayerCore` is the same player without React: `play`, `pause`, `toggle`, `seekTo`, `seekToFrame`, `renderFrame`,
+`captureSheet`, `getCurrentTime`, `getCurrentFrame`, `isPlaying`, `duration`, `playbackRate`, `loop`, `muted`,
+`volume`, `setState`, `attachCanvas`, `subscribeTime`, `dispose`, and the events `frameupdate`, `play`, `pause`,
+`seeked`, `ended`, `ratechange`, `volumechange` and `error`. Every browser dependency (clock, audio output, canvas,
+decoders) can be swapped out, which is how its tests run in jsdom.
+
+## What it draws
+
+Every transition, effect and animation preset the kit accepts: a type the player does not draw is not offered. The few
+remaining limits are in [What renders](https://prefix-tree.github.io/cutcraft/reference/rendering), and the kit's lint
+flags them in the file.
+
+## Docs
+
+- [Player](https://prefix-tree.github.io/cutcraft/guide/player) and the [API reference](https://prefix-tree.github.io/cutcraft/reference/api)
+- [Free code](https://prefix-tree.github.io/cutcraft/guide/free-code)
+
+MIT licensed.

package/dist/engine.d.mts

@@ -0,0 +1,2 @@
+import { $ as motionAt, $t as MAX_OPEN_INPUTS, A as GainPoint, An as PlayerErrorEvent, At as ErrorFrameSource, B as buildFramePlan, Bt as DecodeMode, C as EASING_FN, Cn as EnvelopePoint, Ct as MediabunnyFrameSource, D as OVERLAY_KINDS, Dn as FrameSourceInfo, Dt as mediabunnyAudioSourceFactory, E as keyframedValue, En as FrameSourceFactory, Et as MediabunnyAudioSource, F as DrawOp, Ft as FontFaceSource, G as trackItems, Gt as AUDIO_PRIME_S, H as TransitionRole, Ht as AssetSources, I as FramePlan, It as addFontFaces, J as GraphicAnimation, Jt as ENVELOPE_STEP_S, K as visiblePlacements, Kt as DUCK_ATTACK_S, L as MaskSpec, Lt as loadFileFonts, M as buildGainEnvelope, Mn as ScheduledSource, Mt as ImageFrameSource, N as duckIntervals, Nt as copyFrame, O as backdropTracks, On as MediaHandle, Ot as MediabunnyInputs, P as BackgroundGradient, Pt as defaultCreateCanvas, Q as effect, Qt as LOOKAHEAD_S, R as ResolveNested, Rt as DecoderPool, S as timecode, Sn as Ctx2D, St as toResolver, T as hasKeyframes, Tn as FrameSource, Tt as mediabunnyFrameSourceFactory, U as VisibleItem, Ut as AUDIO_CACHE_S, V as compositionBackground, Vt as AssetSourceDeps, W as isVisibleAt, Wt as AUDIO_CHUNK_S, X as STILL, Xt as FRAME_WAIT_MS, Y as Motion, Yt as FRAME_EPS, Z as combine, Zt as INPUT_IDLE_CLOSE_S, _ as frameTime, _n as AudioSource, _t as PostEffect, a as backgroundCss, an as QUEUE_MAX, at as animatedTransform, b as nestedSourceTime, bn as Clock, bt as postEffects, c as paintBackground, cn as REVERSE_WINDOW_S, ct as fitRect, d as traceMask, dn as SETTLE_MS, dt as multiply, en as MAX_RATE, et as Box, f as Compositor, fn as UNMOUNT_BEHIND_S, ft as rotate, g as frameIndex, gn as AudioOutput, gt as FilterResult, h as makeNestedResolver, hn as AnyCanvas, ht as translate, i as PaintInputs, in as PLAY_PRIME_TIMEOUT_MS, it as Matrix2D, j as buildAudioPlan, jn as PlayerEvents, jt as ImageFrame, k as AudioOccurrence, kn as MediaResolver, kt as ErrorFrame, l as setMatrix, ln as SCHEDULER_MS, lt as layoutRect, m as TickOptions, mn as PerformanceClock, mt as transformMatrix, n as devWarn, nn as MOUNT_AHEAD_S, nt as IDENTITY, o as backgroundFill, on as QUEUE_TARGET, ot as boundsOf, p as CompositorDeps, pn as ManualClock, pt as scaleM, q as ClipRect, qt as DUCK_RELEASE_S, r as CanvasPainter, rn as PICK_EPS, rt as Layout, s as coversCanvas, sn as REVERSE_WINDOW_FRAMES, st as cssTransform, t as captureWarnings, tn as MIN_RATE, tt as DrawRect, u as roundedRect, un as SEEK_MODE_SPEED, ut as matrixToCss, v as layerClock, vn as AudioSourceFactory, vt as filterString, w as ease, wn as Frame, wt as SampleFrame, x as placementSourceTime, xn as CreateCanvas, xt as fromMap, y as localT, yn as AudioSourceInfo, yt as paramsAt, z as blendOf, zt as ClipDecoder } from "./warn-GHM3SBI2.mjs";
+export { AUDIO_CACHE_S, AUDIO_CHUNK_S, AUDIO_PRIME_S, AnyCanvas, AssetSourceDeps, AssetSources, AudioOccurrence, AudioOutput, AudioSource, AudioSourceFactory, AudioSourceInfo, BackgroundGradient, Box, CanvasPainter, ClipDecoder, ClipRect, Clock, Compositor, CompositorDeps, CreateCanvas, Ctx2D, DUCK_ATTACK_S, DUCK_RELEASE_S, DecodeMode, DecoderPool, DrawOp, DrawRect, EASING_FN, ENVELOPE_STEP_S, EnvelopePoint, ErrorFrame, ErrorFrameSource, FRAME_EPS, FRAME_WAIT_MS, FilterResult, FontFaceSource, Frame, FramePlan, FrameSource, FrameSourceFactory, FrameSourceInfo, GainPoint, GraphicAnimation, IDENTITY, INPUT_IDLE_CLOSE_S, ImageFrame, ImageFrameSource, LOOKAHEAD_S, Layout, MAX_OPEN_INPUTS, MAX_RATE, MIN_RATE, MOUNT_AHEAD_S, ManualClock, MaskSpec, Matrix2D, MediaHandle, MediaResolver, MediabunnyAudioSource, MediabunnyFrameSource, MediabunnyInputs, Motion, OVERLAY_KINDS, PICK_EPS, PLAY_PRIME_TIMEOUT_MS, PaintInputs, PerformanceClock, PlayerErrorEvent, PlayerEvents, PostEffect, QUEUE_MAX, QUEUE_TARGET, REVERSE_WINDOW_FRAMES, REVERSE_WINDOW_S, ResolveNested, SCHEDULER_MS, SEEK_MODE_SPEED, SETTLE_MS, STILL, SampleFrame, ScheduledSource, TickOptions, TransitionRole, UNMOUNT_BEHIND_S, VisibleItem, addFontFaces, animatedTransform, backdropTracks, backgroundCss, backgroundFill, blendOf, boundsOf, buildAudioPlan, buildFramePlan, buildGainEnvelope, captureWarnings, combine, compositionBackground, copyFrame, coversCanvas, cssTransform, defaultCreateCanvas, devWarn, duckIntervals, ease, effect, filterString, fitRect, frameIndex, frameTime, fromMap, hasKeyframes, isVisibleAt, keyframedValue, layerClock, layoutRect, loadFileFonts, localT, makeNestedResolver, matrixToCss, mediabunnyAudioSourceFactory, mediabunnyFrameSourceFactory, motionAt, multiply, nestedSourceTime, paintBackground, paramsAt, placementSourceTime, postEffects, rotate, roundedRect, scaleM, setMatrix, timecode, toResolver, traceMask, trackItems, transformMatrix, translate, visiblePlacements };

package/dist/engine.mjs

@@ -0,0 +1 @@
+export { Tt as AUDIO_CACHE_S, Et as AUDIO_CHUNK_S, Dt as AUDIO_PRIME_S, st as AssetSources, n as CanvasPainter, $ as ClipDecoder, t as Compositor, Ot as DUCK_ATTACK_S, kt as DUCK_RELEASE_S, Y as DecoderPool, yt as EASING_FN, At as ENVELOPE_STEP_S, ct as ErrorFrame, lt as ErrorFrameSource, jt as FRAME_EPS, Mt as FRAME_WAIT_MS, b as IDENTITY, Nt as INPUT_IDLE_CLOSE_S, ut as ImageFrame, dt as ImageFrameSource, Pt as LOOKAHEAD_S, Ft as MAX_OPEN_INPUTS, It as MAX_RATE, Lt as MIN_RATE, Rt as MOUNT_AHEAD_S, mt as ManualClock, G as MediabunnyAudioSource, H as MediabunnyFrameSource, V as MediabunnyInputs, L as OVERLAY_KINDS, zt as PICK_EPS, Bt as PLAY_PRIME_TIMEOUT_MS, ht as PerformanceClock, Vt as QUEUE_MAX, Ht as QUEUE_TARGET, Ut as REVERSE_WINDOW_FRAMES, Wt as REVERSE_WINDOW_S, Gt as SCHEDULER_MS, Kt as SEEK_MODE_SPEED, qt as SETTLE_MS, g as STILL, U as SampleFrame, Jt as UNMOUNT_BEHIND_S, q as addFontFaces, x as animatedTransform, R as backdropTracks, r as backgroundCss, i as backgroundFill, f as blendOf, S as boundsOf, gt as buildAudioPlan, p as buildFramePlan, _t as buildGainEnvelope, Ct as captureWarnings, _ as combine, m as compositionBackground, ft as copyFrame, a as coversCanvas, C as cssTransform, pt as defaultCreateCanvas, wt as devWarn, vt as duckIntervals, bt as ease, v as effect, P as filterString, w as fitRect, et as frameIndex, tt as frameTime, z as fromMap, xt as hasKeyframes, X as isVisibleAt, St as keyframedValue, nt as layerClock, T as layoutRect, J as loadFileFonts, rt as localT, d as makeNestedResolver, E as matrixToCss, K as mediabunnyAudioSourceFactory, W as mediabunnyFrameSourceFactory, y as motionAt, D as multiply, it as nestedSourceTime, o as paintBackground, F as paramsAt, at as placementSourceTime, I as postEffects, O as rotate, l as roundedRect, k as scaleM, s as setMatrix, ot as timecode, B as toResolver, u as traceMask, Z as trackItems, A as transformMatrix, j as translate, Q as visiblePlacements } from "./render-DA1KFyei.mjs";

package/dist/index.d.mts

@@ -0,0 +1,327 @@
+import { $ as motionAt, $t as MAX_OPEN_INPUTS, A as GainPoint, An as PlayerErrorEvent, At as ErrorFrameSource, B as buildFramePlan, Bt as DecodeMode, C as EASING_FN, Cn as EnvelopePoint, Ct as MediabunnyFrameSource, D as OVERLAY_KINDS, Dn as FrameSourceInfo, Dt as mediabunnyAudioSourceFactory, E as keyframedValue, En as FrameSourceFactory, Et as MediabunnyAudioSource, F as DrawOp, Ft as FontFaceSource, G as trackItems, Gt as AUDIO_PRIME_S, H as TransitionRole, Ht as AssetSources, I as FramePlan, It as addFontFaces, J as GraphicAnimation, Jt as ENVELOPE_STEP_S, K as visiblePlacements, Kt as DUCK_ATTACK_S, L as MaskSpec, Lt as loadFileFonts, M as buildGainEnvelope, Mn as ScheduledSource, Mt as ImageFrameSource, N as duckIntervals, Nt as copyFrame, O as backdropTracks, On as MediaHandle, Ot as MediabunnyInputs, P as BackgroundGradient, Pt as defaultCreateCanvas, Q as effect, Qt as LOOKAHEAD_S, R as ResolveNested, Rt as DecoderPool, S as timecode, Sn as Ctx2D, St as toResolver, T as hasKeyframes, Tn as FrameSource, Tt as mediabunnyFrameSourceFactory, U as VisibleItem, Ut as AUDIO_CACHE_S, V as compositionBackground, Vt as AssetSourceDeps, W as isVisibleAt, Wt as AUDIO_CHUNK_S, X as STILL, Xt as FRAME_WAIT_MS, Y as Motion, Yt as FRAME_EPS, Z as combine, Zt as INPUT_IDLE_CLOSE_S, _ as frameTime, _n as AudioSource, _t as PostEffect, a as backgroundCss, an as QUEUE_MAX, at as animatedTransform, b as nestedSourceTime, bn as Clock, bt as postEffects, c as paintBackground, cn as REVERSE_WINDOW_S, ct as fitRect, d as traceMask, dn as SETTLE_MS, dt as multiply, en as MAX_RATE, et as Box, f as Compositor, fn as UNMOUNT_BEHIND_S, ft as rotate, g as frameIndex, gn as AudioOutput, gt as FilterResult, h as makeNestedResolver, hn as AnyCanvas, ht as translate, i as PaintInputs, in as PLAY_PRIME_TIMEOUT_MS, it as Matrix2D, j as buildAudioPlan, jn as PlayerEvents, jt as ImageFrame, k as AudioOccurrence, kn as MediaResolver, kt as ErrorFrame, l as setMatrix, ln as SCHEDULER_MS, lt as layoutRect, m as TickOptions, mn as PerformanceClock, mt as transformMatrix, n as devWarn, nn as MOUNT_AHEAD_S, nt as IDENTITY, o as backgroundFill, on as QUEUE_TARGET, ot as boundsOf, p as CompositorDeps, pn as ManualClock, pt as scaleM, q as ClipRect, qt as DUCK_RELEASE_S, r as CanvasPainter, rn as PICK_EPS, rt as Layout, s as coversCanvas, sn as REVERSE_WINDOW_FRAMES, st as cssTransform, t as captureWarnings, tn as MIN_RATE, tt as DrawRect, u as roundedRect, un as SEEK_MODE_SPEED, ut as matrixToCss, v as layerClock, vn as AudioSourceFactory, vt as filterString, w as ease, wn as Frame, wt as SampleFrame, x as placementSourceTime, xn as CreateCanvas, xt as fromMap, y as localT, yn as AudioSourceInfo, yt as paramsAt, z as blendOf, zt as ClipDecoder } from "./warn-GHM3SBI2.mjs";
+import { LayerClock, ResolvedState } from "@cutcraft/kit";
+import { CSSProperties, ReactNode } from "react";
+/**
+ * Composition time as an anchor on the clock: `anchorTime + (now − anchorClock) × rate`.
+ * Every play, pause, seek and rate change re-anchors, so time is always derived from
+ * the clock and never accumulates drift.
+ */
+export declare class Transport {
+  private readonly clock;
+  duration: number;
+  private anchorTime;
+  private anchorClock;
+  private _rate;
+  private _playing;
+  loop: boolean;
+  constructor(clock: Clock, duration: number);
+  get playing(): boolean;
+  get rate(): number;
+  time(): number;
+  timeAt(clockTime: number): number;
+  /** Clock time at which composition time `t` plays; the inverse of `timeAt` while playing. */
+  clockTimeFor(t: number): number;
+  play(): void;
+  pause(): void;
+  seek(t: number): void;
+  setRate(rate: number): void;
+  /** Advance bookkeeping at the end: loops wrap, otherwise playback stops on the last time. */
+  check(): "ended" | "looped" | null;
+  private clamp;
+}
+export interface AudioEngineDeps {
+  readonly output: AudioOutput;
+  readonly transport: Transport;
+  /** Clock seconds (the transport's clock) → audio context seconds. */
+  readonly toContextTime: (clockTime: number) => number;
+  readonly audioSource: (assetId: string) => Promise<AudioSource>;
+  readonly state: () => ResolvedState;
+  readonly resolveNested?: ResolveNested | undefined;
+  readonly setInterval: (fn: () => void, ms: number) => unknown;
+  readonly clearInterval: (id: unknown) => void;
+  readonly onError?: ((e: PlayerErrorEvent) => void) | undefined;
+}
+/**
+ * Schedules audio chunks on the output ahead of the transport. Every play
+ * starts a session; a scheduler tick plans the window since the last tick
+ * up to the lookahead and schedules each new chunk once, with offset,
+ * duration and playback rate derived from the transport. Pause cancels
+ * everything; seek and rate changes restart the session.
+ */
+export declare class AudioEngine {
+  private readonly deps;
+  private session;
+  private timer;
+  private scheduled;
+  private scheduledUpTo;
+  private running;
+  private cache;
+  private cacheSeconds;
+  private _muted;
+  private _volume;
+  constructor(deps: AudioEngineDeps);
+  get muted(): boolean;
+  get volume(): number;
+  get active(): boolean;
+  setMaster(volume: number, muted: boolean): void;
+  /** Decode what plays in the first moments after `t`, bounded by a timeout, so play starts on time. */
+  prime(t: number): Promise<void>;
+  start(): void;
+  stop(): void;
+  /** After a seek, a rate change or a loop: reschedule from the new position. */
+  reseek(): void;
+  tick(): void;
+  dispose(): void;
+  private schedule;
+  private buffer;
+}
+/** Web Audio graph: per scheduled chunk `source → gain(envelope) → [pan] → master → destination`. */
+export declare class WebAudioOutput implements AudioOutput {
+  private readonly ctx;
+  private readonly master;
+  private readonly live;
+  constructor(ctx: AudioContext);
+  get contextTime(): number;
+  get running(): boolean;
+  schedule(src: ScheduledSource): void;
+  cancel(keyPrefix: string): void;
+  cancelAll(): void;
+  setMaster(gain: number): void;
+  resume(): Promise<void>;
+  private drop;
+  private stop;
+  private disconnect;
+}
+/**
+ * `AudioContext.currentTime` while the context runs, the performance clock
+ * otherwise, with an offset captured at every state change so `now()` never
+ * jumps. Audio scheduling converts back with `toContextTime`.
+ */
+export declare class AudioContextClock implements Clock {
+  private readonly ctx;
+  private offset;
+  private wasRunning;
+  private lastNow;
+  constructor(ctx: BaseAudioContext);
+  get running(): boolean;
+  now(): number;
+  /** Audio context seconds for a clock time; exact while the context runs. */
+  toContextTime(clockTime: number): number;
+}
+export interface CaptureSheetOptions {
+  /** Cells per row; default 4, never more than the number of times. */
+  readonly columns?: number;
+  /** Cell width in pixels; default the composition width capped at 320. Height follows the aspect ratio. */
+  readonly cellWidth?: number;
+  /** Draw a `mm:ss:ff` label in each cell; default true. */
+  readonly labels?: boolean;
+}
+export interface PlayerOptions {
+  readonly state: ResolvedState;
+  readonly media: MediaResolver | Readonly<Record<string, Blob | string>>;
+  readonly audioContext?: AudioContext | undefined;
+  readonly loop?: boolean | undefined;
+  readonly initiallyMuted?: boolean | undefined;
+  readonly playbackRate?: number | undefined;
+  /** Load the file's fonts (`state.fonts`) into the page; default true. The export page loads them itself. */
+  readonly loadFonts?: boolean | undefined;
+  /**
+   * Re-render overlays for every change of time, not once per frame; default false. The export sets it to draw the
+   * moments inside a frame that motion blur averages.
+   */
+  readonly exactTime?: boolean | undefined;
+  readonly resolveNested?: ResolveNested | undefined;
+  /** Test seams; the browser defaults are the audio-context clock, Web Audio and mediabunny. */
+  readonly clock?: Clock | undefined;
+  readonly audioOutput?: AudioOutput | undefined;
+  readonly toContextTime?: ((clockTime: number) => number) | undefined;
+  readonly frameSourceFactory?: FrameSourceFactory | undefined;
+  readonly audioSourceFactory?: AudioSourceFactory | undefined;
+  readonly createCanvas?: CreateCanvas | undefined;
+  readonly raf?: ((cb: () => void) => number) | undefined;
+  readonly cancelRaf?: ((id: number) => void) | undefined;
+  readonly setInterval?: ((fn: () => void, ms: number) => unknown) | undefined;
+  readonly clearInterval?: ((id: unknown) => void) | undefined;
+  readonly setTimeout?: ((fn: () => void, ms: number) => unknown) | undefined;
+  readonly clearTimeout?: ((id: unknown) => void) | undefined;
+}
+export interface TimeSnapshot {
+  readonly time: number;
+  readonly frame: number;
+}
+type Listener<K extends keyof PlayerEvents> = (e: PlayerEvents[K]) => void;
+/**
+ * The framework-free player: owns the transport, the compositor (canvas),
+ * the audio engine and the media sources. React's `<Player>` is a thin
+ * wrapper over it; a headless exporter can drive `renderFrame` directly.
+ */
+export declare class PlayerCore {
+  private _state;
+  private readonly media;
+  private readonly clock;
+  private readonly transport;
+  readonly compositor: Compositor;
+  private readonly engine;
+  private readonly sources;
+  private readonly inputs;
+  private readonly audioContext;
+  private readonly audioSources;
+  private readonly listeners;
+  private readonly timeListeners;
+  private readonly createCanvas;
+  private readonly raf;
+  private readonly cancelRaf;
+  private rafId;
+  private readonly setTimeoutFn;
+  private readonly clearTimeoutFn;
+  private settleTimer;
+  private seekGeneration;
+  private snapshot;
+  private _muted;
+  private _volume;
+  private disposed;
+  private fonts;
+  private fontsOf;
+  private readonly fontsWanted;
+  constructor(options: PlayerOptions);
+  /** Resolves once the file's fonts (`state.fonts`) have loaded; a face that fails is reported as an error event. */
+  /** Overlays follow every change of time, not each frame (`exactTime`). */
+  readonly exactTime: boolean;
+  get fontsReady(): Promise<void>;
+  private loadFonts;
+  get state(): ResolvedState;
+  get duration(): number;
+  get playbackRate(): number;
+  set playbackRate(rate: number);
+  get loop(): boolean;
+  set loop(v: boolean);
+  get muted(): boolean;
+  set muted(v: boolean);
+  get volume(): number;
+  set volume(v: number);
+  /** The media handle for an asset id, for DOM elements that show images. */
+  resolveMedia(assetId: string): Promise<MediaHandle>;
+  getCurrentTime(): number;
+  getCurrentFrame(): number;
+  isPlaying(): boolean;
+  getTime(): TimeSnapshot;
+  play(): Promise<void>;
+  pause(): void;
+  toggle(): Promise<void>;
+  /** Jump to `time` and draw its exact frame before resolving, playing or not. */
+  seekTo(time: number): Promise<void>;
+  seekToFrame(frame: number): Promise<void>;
+  /** Draw `time` without moving the transport; decoders return to the play head afterwards. */
+  renderFrame(time: number): Promise<void>;
+  /**
+   * A contact sheet of the canvas plane at `times`: each cell is `renderFrame`
+   * of that time with a timecode label, laid out `columns` wide. The way an
+   * agent or a test looks at the result without exporting. DOM overlays
+   * (titles, shapes, Layer interiors) are not on the canvas and do not appear.
+   */
+  captureSheet(times: readonly number[], options?: CaptureSheetOptions): Promise<AnyCanvas>;
+  /**
+   * The editor pushes a new resolve on every drag step. Decoders of the same
+   * asset keep their frames and take the new trim; a paused preview paints at
+   * once with what is decoded and fetches the exact frame after the gesture
+   * has been quiet for `SETTLE_MS`.
+   */
+  setState(state: ResolvedState): void;
+  attachCanvas(canvas: HTMLCanvasElement | OffscreenCanvas | null): void;
+  addEventListener<K extends keyof PlayerEvents>(type: K, fn: Listener<K>): () => void;
+  removeEventListener<K extends keyof PlayerEvents>(type: K, fn: Listener<K>): void;
+  /** For `useSyncExternalStore`: notified once per painted frame and on every seek. */
+  subscribeTime(fn: () => void): () => void;
+  dispose(): void;
+  private startLoop;
+  private stopLoop;
+  private publish;
+  private emit;
+  private audioSource;
+}
+/**
+ * Walk the file's element tree the way the kit's `collect` does (fragments,
+ * vocabulary elements, pure helpers expanded by calling them) and record the
+ * children of every `<Layer id>`: the resolver drops them, the Player renders them.
+ */
+export declare function indexLayerInteriors(element: ReactNode): Map<string, ReactNode>;
+/** Play/pause, scrubber, time readout, mute and rate. */
+export declare function Controls(): import("react").JSX.Element;
+export declare const PlayerContext: import("react").Context<PlayerCore | null>;
+/** The layer's clock inside a `<Layer>`; null outside one. */
+export declare const LayerContext: import("react").Context<LayerClock | null>;
+export interface DomLayerProps {
+  readonly state: ResolvedState;
+  readonly interiors: ReadonlyMap<string, ReactNode>;
+  /** Which overlays: those beneath the footage (`backdropTracks`), or the rest and the captions (default). */
+  readonly layer?: "backdrop" | "front";
+}
+/** Overlay elements as DOM, one absolutely positioned group per track in compositing order, above the canvas (or, for the backdrop, below it). */
+export declare function DomLayer({ state, interiors, layer }: DomLayerProps): import("react").JSX.Element;
+export interface ElementCellProps {
+  item: VisibleItem;
+  state: ResolvedState;
+  time: number;
+  interior: ReactNode;
+  /** Re-render for any change of time, not only a new frame (the player's `exactTime`). */
+  exact?: boolean;
+}
+/**
+ * Whether two renders of an overlay would produce the same DOM. Placements
+ * are new objects on every resolve, so compare what matters: timing, the
+ * parsed props (referentially stable while untouched), children, the
+ * element-relative frame, the transition progress, the text and the
+ * composition box.
+ */
+export declare function sameElement(a: ElementCellProps, b: ElementCellProps): boolean;
+/**
+ * Holds the CSS animations under `root` at `seconds` past the layer's start: paused, and seeked there. They then
+ * follow the video's clock (play, pause, scrub both ways) and an export captures the same frame twice.
+ *
+ * Only CSS animations: their zero is the moment their element got the style, which inside a Layer is the layer's
+ * start. A Web Animation made with `element.animate()` or by a library keeps its own start and its owner's clock.
+ */
+export declare function holdCssAnimations(root: Element | null, seconds: number): void;
+export declare function usePlayer(): PlayerCore;
+export declare function useCompositionTime(): number;
+export declare function useCompositionFrame(): number;
+/** What the kit's `useLayer()` and `useT()` delegate to while a Player is mounted. */
+export declare function useLayerClock(): LayerClock;
+/** 0..1 progress through the enclosing Layer. */
+export declare function useLayerT(): number;
+/** Installs the kit's layer hooks for the first mounted Player and removes them after the last unmounts. */
+export declare function retainUseT(): () => void;
+export interface PlayerProps {
+  readonly state: ResolvedState;
+  readonly media: MediaResolver | Readonly<Record<string, Blob | string>>;
+  /** The evaluated file element (`mod.default(props)`); needed only to render `<Layer>` interiors. */
+  readonly element?: ReactNode;
+  readonly controls?: boolean;
+  readonly loop?: boolean;
+  readonly autoPlay?: boolean;
+  readonly initiallyMuted?: boolean;
+  readonly playbackRate?: number;
+  /** `contain` scales the composition into the box; `none` renders at composition pixels. */
+  readonly fit?: "contain" | "none";
+  readonly style?: CSSProperties;
+  readonly className?: string;
+  readonly audioContext?: AudioContext;
+  readonly onError?: (e: PlayerEvents["error"]) => void;
+  readonly onFrame?: (e: PlayerEvents["frameupdate"]) => void;
+  /** Test seams forwarded to PlayerCore. */
+  readonly coreOptions?: Partial<PlayerOptions>;
+}
+export type PlayerRef = Pick<PlayerCore, "play" | "pause" | "toggle" | "seekTo" | "seekToFrame" | "getCurrentTime" | "getCurrentFrame" | "isPlaying" | "addEventListener" | "removeEventListener" | "renderFrame" | "captureSheet" | "duration" | "state"> & {
+  playbackRate: number;
+  loop: boolean;
+  muted: boolean;
+  volume: number;
+  readonly core: PlayerCore;
+  readonly canvas: HTMLCanvasElement | null;
+};
+/**
+ * Canvas for media, DOM for overlays, controls below. The root carries
+ * `data-time` and `data-frame`; every element carries `data-el`/`data-kind`.
+ */
+export declare const Player: import("react").ForwardRefExoticComponent<PlayerProps & import("react").RefAttributes<PlayerRef>>;
+export { AUDIO_CACHE_S, AUDIO_CHUNK_S, AUDIO_PRIME_S, AnyCanvas, AssetSourceDeps, AssetSources, AudioOccurrence, AudioOutput, AudioSource, AudioSourceFactory, AudioSourceInfo, BackgroundGradient, Box, CanvasPainter, ClipDecoder, ClipRect, Clock, Compositor, CompositorDeps, CreateCanvas, Ctx2D, DUCK_ATTACK_S, DUCK_RELEASE_S, DecodeMode, DecoderPool, DrawOp, DrawRect, EASING_FN, ENVELOPE_STEP_S, EnvelopePoint, ErrorFrame, ErrorFrameSource, FRAME_EPS, FRAME_WAIT_MS, FilterResult, FontFaceSource, Frame, FramePlan, FrameSource, FrameSourceFactory, FrameSourceInfo, GainPoint, GraphicAnimation, IDENTITY, INPUT_IDLE_CLOSE_S, ImageFrame, ImageFrameSource, LOOKAHEAD_S, Layout, MAX_OPEN_INPUTS, MAX_RATE, MIN_RATE, MOUNT_AHEAD_S, ManualClock, MaskSpec, Matrix2D, MediaHandle, MediaResolver, MediabunnyAudioSource, MediabunnyFrameSource, MediabunnyInputs, Motion, OVERLAY_KINDS, PICK_EPS, PLAY_PRIME_TIMEOUT_MS, PaintInputs, PerformanceClock, PlayerErrorEvent, PlayerEvents, PostEffect, QUEUE_MAX, QUEUE_TARGET, REVERSE_WINDOW_FRAMES, REVERSE_WINDOW_S, ResolveNested, SCHEDULER_MS, SEEK_MODE_SPEED, SETTLE_MS, STILL, SampleFrame, ScheduledSource, TickOptions, TransitionRole, UNMOUNT_BEHIND_S, VisibleItem, addFontFaces, animatedTransform, backdropTracks, backgroundCss, backgroundFill, blendOf, boundsOf, buildAudioPlan, buildFramePlan, buildGainEnvelope, captureWarnings, combine, compositionBackground, copyFrame, coversCanvas, cssTransform, defaultCreateCanvas, devWarn, duckIntervals, ease, effect, filterString, fitRect, frameIndex, frameTime, fromMap, hasKeyframes, isVisibleAt, keyframedValue, layerClock, layoutRect, loadFileFonts, localT, makeNestedResolver, matrixToCss, mediabunnyAudioSourceFactory, mediabunnyFrameSourceFactory, motionAt, multiply, nestedSourceTime, paintBackground, paramsAt, placementSourceTime, postEffects, rotate, roundedRect, scaleM, setMatrix, timecode, toResolver, traceMask, trackItems, transformMatrix, translate, visiblePlacements };