@cutcraft/player 0.1.0 → 0.2.0

package/README.md

@@ -1,103 +1,62 @@
-<p align="center"><img src="../../docs/public/logo.svg" width="64" alt="cutcut logo"></p>
+<p align="center"><img src="https://raw.githubusercontent.com/prefix-tree/cutcraft/main/docs/public/logo.svg" width="64" alt="CutCraft"></p>
 
 # @cutcraft/player
 
-The browser player for cut files. It takes a `ResolvedState` from `@cutcraft/kit`
-and plays it: footage decoded with WebCodecs through mediabunny and composited
-on one canvas, overlays rendered as React DOM above it, sound mixed and
-clocked by Web Audio. The editor's preview and the model's filmstrip drive the
-same `PlayerCore`; the export (`@cutcraft/render`) runs the same engine in Node
-through `@cutcraft/player/engine` and `@cutcraft/player/overlays`, which have no
-React layer, DOM or Web Audio in them.
+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 * as file from "./video";          // the TSX file the model wrote
+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 implements `MediaResolver`).
-`element` is only needed for `<Layer>` interiors, which the resolver drops.
-
-## What it does
-
-- **Clock.** Composition time is an anchor on `AudioContext.currentTime`
-  (`anchorTime + (now − anchorClock) × rate`), re-anchored on play, pause, seek
-  and rate change; it never accumulates drift. The render loop is
-  `requestAnimationFrame`; a tick that lands while a frame is in flight is
-  coalesced, and a tick on the same frame index only keeps decoders prefetching.
-- **Decoding.** One mediabunny `Input` per asset, shared by every clip of it
-  and by nested compositions, ref-counted and closed when idle. Each clip near
-  the play head has a `ClipDecoder`: a `VideoSampleSink` stream feeding a
-  short queue for forward play, pre-decoded windows for reverse, single-frame
-  fetches at high speeds and while scrubbing, one retained frame per freeze.
-  A playing tick never waits for a frame; a seek does. A trim or speed drag
-  updates the decoder in place rather than reopening it, and a paused preview
-  repaints each drag step with what is decoded, then fetches the exact frame
-  once the gesture has been quiet for 120 ms.
-- **Compositing.** `buildFramePlan(state, t)` is pure and deterministic: tracks
-  in document order (the first track is the bottom), each clip with its
-  animated transform, crop, fit, opacity, blend, filter and mask; transitions
-  draw the incoming clip over the outgoing one; adjustments re-filter what is
-  below them. `CanvasPainter` executes it. Titles, shapes, SVG, stickers,
-  layers and captions are DOM elements positioned with the same matrix math.
-- **Audio.** `buildAudioPlan` lists every audio-bearing chunk in a window with
-  its gain envelope (volume, fades, automation, ducking, keyframes, mute and
-  solo). `AudioEngine` schedules each chunk once per play session, 200 ms
-  ahead, as an `AudioBufferSourceNode` with the right offset, duration and
-  `playbackRate = clipSpeed × rate`, automated along a speed-key ramp and
-  split around freeze holds, which are silent; PCM is decoded per source range with
-  `AudioBufferSink` and cached. Pause stops everything; seek reschedules once.
-- **Addressability.** Every DOM element carries `data-el` and `data-kind`; the
-  root carries `data-time` and `data-frame`; the canvas is
-  `[data-el="composition"]`.
-- **Determinism.** `seekTo(t)` and `renderFrame(t)` draw the exact frame for
-  `t`, paused or playing. The exporter steps through frames with
-  `Compositor.step(t)`, which keeps every decoder streaming.
-- **Looking at the result.** `captureSheet(times, { columns })` returns a
-  labelled contact sheet of those frames, the way an agent or a test checks
-  a cut without exporting.
+`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
 
-`PlayerCore` (framework-free): `play`, `pause`, `toggle`, `seekTo`,
-`seekToFrame`, `renderFrame`, `captureSheet`, `getCurrentTime`,
-`getCurrentFrame`, `isPlaying`, `duration`, `playbackRate` (0.25–4), `loop`, `muted`, `volume`,
-`setState`, `attachCanvas`, `addEventListener` (`frameupdate`, `play`,
-`pause`, `seeked`, `ended`, `ratechange`, `volumechange`, `error`),
-`subscribeTime`, `dispose`. Every browser dependency is injectable
-(`clock`, `audioOutput`, `frameSourceFactory`, `audioSourceFactory`,
-`createCanvas`, `raf`, `setInterval`), which is how the unit tests run in jsdom.
-
-React: `<Player>` with `controls`, `loop`, `autoPlay`, `initiallyMuted`,
-`playbackRate`, `fit`, `onError`, `onFrame` and a `PlayerRef`; hooks
-`usePlayer`, `useCompositionTime`, `useCompositionFrame`, `useLayerT`.
-Mounting a Player installs the kit's `useT()` and `useLayer()`.
-
-## Not rendered yet
-
-Transition types other than crossfade, dips to black or white, wipe, slide and push (drawn as a crossfade), effects that
-have no CSS filter equivalent (sharpen, glow, …; vignette and grain are drawn),
-colour wheels, curves and LUTs, matte masks, audio effects, pitch correction,
-3D text, most text animation presets (shown as a fade),
-`background.mode: "blur"` under overlays that sit beneath the footage (the
-plain colour), sticker packs and `file:` nested references. The
-kit's `not-rendered` lint warning reports these in the file before anything
-plays, from the same table (`RENDERED_*` in `@cutcraft/kit`) the player reads.
-
-## Tests
+`<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.
 
-```
-pnpm --filter @cutcraft/player test        # vitest over jsdom with fakes (part of `pnpm check`)
-pnpm --filter @cutcraft/player test:e2e    # Playwright: ffmpeg-generated media, Vite, headless Chromium
-```
+`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)
 
-The browser suite generates `bars.webm` (frame number encoded in a binary
-strip), `tone.ogg`, `logo.png` and `solid.webm` into `e2e/app/public/`, then
-checks seek accuracy, real-time playback on the audio clock, rate changes,
-crossfade blending, DOM overlays and `useT`, image clips, ended/loop and
-determinism. It needs `ffmpeg` and Playwright's Chromium (pinned to 1.56.1 to
-match the preinstalled browser).
+MIT licensed.

package/dist/engine.d.mts

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

@@ -1,3 +1 @@
-import { $ as MIN_RATE, A as hasKeyframes, B as devWarn, C as transformMatrix, D as visiblePlacements, E as trackItems, F as localT, G as DUCK_RELEASE_S, H as AUDIO_CHUNK_S, I as nestedSourceTime, J as FRAME_WAIT_MS, K as ENVELOPE_STEP_S, L as placementSourceTime, M as frameIndex, N as frameTime, O as EASING_FN, P as layerClock, Q as MAX_RATE, R as timecode, S as scaleM, T as isVisibleAt, U as AUDIO_PRIME_S, V as AUDIO_CACHE_S, W as DUCK_ATTACK_S, X as LOOKAHEAD_S, Y as INPUT_IDLE_CLOSE_S, Z as MAX_OPEN_INPUTS, _ as fitRect, a as backdropTracks, at as REVERSE_WINDOW_FRAMES, b as multiply, c as combine, ct as SEEK_MODE_SPEED, d as filterString, et as MOUNT_AHEAD_S, f as postEffects, g as cssTransform, h as boundsOf, i as OVERLAY_KINDS, it as QUEUE_TARGET, j as keyframedValue, k as ease, l as effect, lt as SETTLE_MS, m as animatedTransform, n as buildFramePlan, nt as PLAY_PRIME_TIMEOUT_MS, ot as REVERSE_WINDOW_S, p as IDENTITY, q as FRAME_EPS, r as compositionBackground, rt as QUEUE_MAX, s as STILL, st as SCHEDULER_MS, t as blendOf, tt as PICK_EPS, u as motionAt, ut as UNMOUNT_BEHIND_S, v as layoutRect, w as translate, x as rotate, y as matrixToCss, z as captureWarnings } from "./frame-plan-BNwblf1s.mjs";
-import { A as buildAudioPlan, C as ImageFrameSource, D as toResolver, E as fromMap, M as duckIntervals, O as ManualClock, S as ImageFrame, T as defaultCreateCanvas, _ as DecoderPool, a as backgroundFill, b as ErrorFrame, c as setMatrix, d as MediabunnyAudioSource, f as mediabunnyAudioSourceFactory, g as MediabunnyInputs, h as mediabunnyFrameSourceFactory, i as backgroundCss, j as buildGainEnvelope, k as PerformanceClock, l as roundedRect, m as SampleFrame, n as Compositor, o as coversCanvas, p as MediabunnyFrameSource, r as CanvasPainter, s as paintBackground, t as makeNestedResolver, u as traceMask, v as ClipDecoder, w as copyFrame, x as ErrorFrameSource, y as AssetSources } from "./nested-DSXA1q8d.mjs";
-export { AUDIO_CACHE_S, AUDIO_CHUNK_S, AUDIO_PRIME_S, AssetSources, CanvasPainter, ClipDecoder, Compositor, DUCK_ATTACK_S, DUCK_RELEASE_S, DecoderPool, EASING_FN, ENVELOPE_STEP_S, ErrorFrame, ErrorFrameSource, FRAME_EPS, FRAME_WAIT_MS, IDENTITY, INPUT_IDLE_CLOSE_S, ImageFrame, ImageFrameSource, LOOKAHEAD_S, MAX_OPEN_INPUTS, MAX_RATE, MIN_RATE, MOUNT_AHEAD_S, ManualClock, MediabunnyAudioSource, MediabunnyFrameSource, MediabunnyInputs, OVERLAY_KINDS, PICK_EPS, PLAY_PRIME_TIMEOUT_MS, PerformanceClock, QUEUE_MAX, QUEUE_TARGET, REVERSE_WINDOW_FRAMES, REVERSE_WINDOW_S, SCHEDULER_MS, SEEK_MODE_SPEED, SETTLE_MS, STILL, SampleFrame, UNMOUNT_BEHIND_S, 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, localT, makeNestedResolver, matrixToCss, mediabunnyAudioSourceFactory, mediabunnyFrameSourceFactory, motionAt, multiply, nestedSourceTime, paintBackground, placementSourceTime, postEffects, rotate, roundedRect, scaleM, setMatrix, timecode, toResolver, traceMask, trackItems, transformMatrix, translate, visiblePlacements };
+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

@@ -1,24 +1,6 @@
-import { $ as postEffects, A as ImageFrameSource, At as FRAME_EPS, B as buildGainEnvelope, Bt as QUEUE_MAX, C as ClipDecoder, Ct as devWarn, D as ErrorFrame, Dt as DUCK_ATTACK_S, E as AssetSources, Et as AUDIO_PRIME_S, F as ManualClock, Ft as MAX_RATE, G as MaskSpec, Gt as SEEK_MODE_SPEED, H as BackgroundGradient, Ht as REVERSE_WINDOW_FRAMES, I as PerformanceClock, It as MIN_RATE, J as buildFramePlan, K as ResolveNested, Kt as SETTLE_MS, L as AudioOccurrence, Lt as MOUNT_AHEAD_S, M as defaultCreateCanvas, Mt as INPUT_IDLE_CLOSE_S, N as fromMap, Nt as LOOKAHEAD_S, O as ErrorFrameSource, Ot as DUCK_RELEASE_S, P as toResolver, Pt as MAX_OPEN_INPUTS, Q as filterString, R as GainPoint, Rt as PICK_EPS, S as DecoderPool, St as captureWarnings, T as AssetSourceDeps, Tt as AUDIO_CHUNK_S, U as DrawOp, Ut as REVERSE_WINDOW_S, V as duckIntervals, Vt as QUEUE_TARGET, W as FramePlan, Wt as SCHEDULER_MS, X as FilterResult, Y as compositionBackground, Z as PostEffect, _ as FrameSourceHooks, _t as MediaHandle, a as TickOptions, at as AudioOutput, b as mediabunnyFrameSourceFactory, bt as PlayerEvents, c as backgroundCss, ct as AudioSourceInfo, d as paintBackground, dt as Ctx2D, et as EASING_FN, f as setMatrix, ft as EnvelopePoint, g as mediabunnyAudioSourceFactory, gt as FrameSourceInfo, h as MediabunnyAudioSource, ht as FrameSourceFactory, i as FrameIntercept, it as AnyCanvas, j as copyFrame, jt as FRAME_WAIT_MS, k as ImageFrame, kt as ENVELOPE_STEP_S, l as backgroundFill, lt as Clock, m as traceMask, mt as FrameSource, n as Compositor, nt as hasKeyframes, o as CanvasPainter, ot as AudioSource, p as roundedRect, pt as Frame, q as blendOf, qt as UNMOUNT_BEHIND_S, r as CompositorDeps, rt as keyframedValue, s as PaintInputs, st as AudioSourceFactory, t as makeNestedResolver, tt as ease, u as coversCanvas, ut as CreateCanvas, v as MediabunnyFrameSource, vt as MediaResolver, w as DecodeMode, wt as AUDIO_CACHE_S, x as MediabunnyInputs, xt as ScheduledSource, y as SampleFrame, yt as PlayerErrorEvent, z as buildAudioPlan, zt as PLAY_PRIME_TIMEOUT_MS } from "./nested-Bd4Y7qrF.mjs";
-import { A as visiblePlacements, C as scaleM, D as VisibleItem, E as TransitionRole, F as nestedSourceTime, I as placementSourceTime, L as timecode, M as frameTime, N as layerClock, O as isVisibleAt, P as localT, S as rotate, T as translate, _ as cssTransform, a as Motion, b as matrixToCss, c as effect, d as DrawRect, f as IDENTITY, g as boundsOf, h as animatedTransform, i as GraphicAnimation, j as frameIndex, k as trackItems, l as motionAt, m as Matrix2D, n as backdropTracks, o as STILL, p as Layout, r as ClipRect, s as combine, t as OVERLAY_KINDS, u as Box, v as fitRect, w as transformMatrix, x as multiply, y as layoutRect } from "./backdrop-BqrzCzTB.mjs";
-import { t as indexLayerInteriors } from "./layer-interiors-r4SeMbp2.mjs";
+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";
-/**
- * `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;
-}
 /**
  * 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
@@ -110,6 +92,22 @@ export declare class WebAudioOutput implements AudioOutput {
   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;
@@ -125,6 +123,13 @@ export interface PlayerOptions {
   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;
@@ -175,7 +180,15 @@ export declare class PlayerCore {
   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;
@@ -226,18 +239,17 @@ export declare class PlayerCore {
   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 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 DomLayerProps {
   readonly state: ResolvedState;
   readonly interiors: ReadonlyMap<string, ReactNode>;
@@ -251,6 +263,8 @@ export interface ElementCellProps {
   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
@@ -260,8 +274,23 @@ export interface ElementCellProps {
  * composition box.
  */
 export declare function sameElement(a: ElementCellProps, b: ElementCellProps): boolean;
-/** Play/pause, scrubber, time readout, mute and rate. */
-export declare function Controls(): import("react").JSX.Element;
+/**
+ * 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>>;
@@ -295,4 +324,4 @@ export type PlayerRef = Pick<PlayerCore, "play" | "pause" | "toggle" | "seekTo"
  * `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, Frame, FrameIntercept, FramePlan, FrameSource, FrameSourceFactory, FrameSourceHooks, 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, 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, indexLayerInteriors, isVisibleAt, keyframedValue, layerClock, layoutRect, localT, makeNestedResolver, matrixToCss, mediabunnyAudioSourceFactory, mediabunnyFrameSourceFactory, motionAt, multiply, nestedSourceTime, paintBackground, placementSourceTime, postEffects, rotate, roundedRect, scaleM, setMatrix, timecode, toResolver, traceMask, trackItems, transformMatrix, translate, visiblePlacements };
+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 };