@pictor-sdk/video-android 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,3622 @@
+import { PlaylistResult, PlayIntent, PlaylistItem, UnsupportedSource, VideoProject, ThumbnailProvider, MediaSource, ExportSourceContext, VideoExporter, VideoExportProgress, MediaSaver, AudioProbe, AudioMixProgram } from '@pictor-sdk/video-core';
+
+/**
+ * A debug safety cutoff on native memory.
+ *
+ * **Remove before production.** This exists because an earlier revision drove
+ * the native heap to 1.5 GB in sixty seconds and the process was killed —
+ * taking other applications on the device with it, since Android reclaims from
+ * everything before it gives up on the foreground app. A diagnostic run must
+ * not be able to do that again.
+ *
+ * Two independent triggers, because a leak can be fast or merely relentless:
+ *
+ * - **Ceiling.** An absolute limit, well under anything that would put the
+ *   device under pressure.
+ * - **Sustained rise.** Memory that climbs across every sample of a window with
+ *   no plateau, which is what a slow leak looks like and what a ceiling alone
+ *   would take minutes to catch.
+ *
+ * Pure, so the rule is tested rather than trusted: a cutoff that misfires stops
+ * a good run, and one that never fires is not a cutoff.
+ *
+ * @experimental
+ */
+interface MemoryGuard {
+    readonly ceilingBytes: number;
+    readonly windowSamples: number;
+    /** Minimum total climb across the window to count as a rise, in bytes. */
+    readonly riseBytes: number;
+    samples: number[];
+    tripped: null | 'ceiling' | 'sustained-rise';
+}
+/**
+ * 250 MB. Healthy single-clip playback plateaus near 65 MB.
+ *
+ * Was 400 MB, which a 1 MB/s leak takes six minutes to reach — long enough for
+ * a five-minute run to finish, look successful, and leave the process fat
+ * enough that the next run pushed the device into reclaiming from other
+ * applications.
+ */
+declare const DEFAULT_CEILING_BYTES: number;
+/** Forty samples at 4 Hz — ten seconds of uninterrupted climbing. */
+declare const DEFAULT_WINDOW_SAMPLES = 40;
+/**
+ * 8 MB across the window: ~0.8 MB/s.
+ *
+ * Was 24 MB over three seconds — 8 MB/s, calibrated against a leak that hit
+ * 1.5 GB in a minute. It was blind to the 1.07 MB/s leak that actually got the
+ * process killed, so the cutoff never fired. A cutoff tuned only to the last
+ * failure is not a cutoff.
+ *
+ * A threshold this small is safe only because the rise must also be *strictly*
+ * increasing at every one of the forty samples. Real memory jitters; a leak
+ * does not.
+ */
+declare const DEFAULT_RISE_BYTES: number;
+declare function createMemoryGuard(ceilingBytes?: number, windowSamples?: number, riseBytes?: number): MemoryGuard;
+/**
+ * Record a reading and decide whether to stop.
+ *
+ * Once tripped it stays tripped: the caller has already torn the session down,
+ * and a guard that untrips would invite it to start again into the same leak.
+ */
+declare function observeMemory(guard: MemoryGuard, bytes: number): MemoryGuard;
+/** A sentence a human can act on, or null while nothing is wrong. */
+declare function describeTrip(guard: MemoryGuard): string | null;
+
+/**
+ * Per-tick synchronisation forensics.
+ *
+ * A single offset number cannot say *why* video is late, and optimising against
+ * it invites exactly the wrong fixes — presenting future frames, nudging the
+ * clock, delaying audio. Each of those improves the number and worsens the
+ * playback.
+ *
+ * So every tick is decomposed into causes that can be acted on separately:
+ *
+ * - **Frame quantisation** — video only changes every frame period, so the
+ *   picture is always somewhat behind the audio instant. Bounded by one frame
+ *   by definition, and not a defect.
+ * - **Decoder lateness** — the frame that *should* be showing had not been
+ *   decoded yet. Fix by adjusting the bounded lead or queue depth.
+ * - **Scheduler lateness** — the right frame *was* available and was not
+ *   selected. Fix the missed tick or the contention causing it.
+ * - **Clock correction** — how far each raw `AudioTrack` report moves the
+ *   extrapolated position. Large jumps mean stale timestamps or a bad baseline.
+ *
+ * Pure, so the decomposition is tested rather than trusted.
+ *
+ * @experimental
+ */
+interface TickSample {
+    /** Authoritative extrapolated audio time. */
+    audioUs: number;
+    /** Age of the newest raw `getTimestamp()` report at this tick. */
+    rawAgeUs: number;
+    /** How far the newest raw report moved the extrapolated position. */
+    correctionUs: number;
+    /** Newest decoded frame at or before `audioUs`, or null if none is eligible. */
+    newestEligiblePtsUs: number | null;
+    /** What was actually presented, or null. */
+    presentedPtsUs: number | null;
+    /** Interval since the previous tick. */
+    tickIntervalUs: number;
+    queueDepth: number;
+    decoderLeadUs: number;
+}
+interface SyncTrace {
+    readonly frameUs: number;
+    quantisation: number[];
+    decoderLate: number[];
+    schedulerLate: number[];
+    correction: number[];
+    presentedOffset: number[];
+    tickInterval: number[];
+    ticks: number;
+    decoderLateTicks: number;
+    schedulerLateTicks: number;
+}
+declare function createSyncTrace(fps: number): SyncTrace;
+/**
+ * The frame that ought to be on screen at `audioUs`.
+ *
+ * Assumes a regular frame grid anchored at zero, which the controlled fixture
+ * has. On a variable-rate source this is an approximation and the quantisation
+ * figure should be read as indicative — which is why it is stated here rather
+ * than left for a reader to infer from a clean-looking number.
+ */
+declare function expectedPtsAt(audioUs: number, frameUs: number): number;
+declare function record(trace: SyncTrace, sample: TickSample): SyncTrace;
+interface Distribution {
+    n: number;
+    p50: number;
+    p95: number;
+    p99: number;
+    max: number;
+}
+declare function distribution(values: readonly number[]): Distribution;
+interface SyncReport {
+    quantisation: Distribution;
+    decoderLate: Distribution;
+    schedulerLate: Distribution;
+    correction: Distribution;
+    presentedOffset: Distribution;
+    tickInterval: Distribution;
+    ticks: number;
+    decoderLateTicks: number;
+    schedulerLateTicks: number;
+    frameUs: number;
+    /** Which cause dominates, so the fix is chosen by evidence. */
+    dominant: 'none' | 'decoder' | 'scheduler' | 'quantisation';
+}
+declare function syncReport(trace: SyncTrace): SyncReport;
+
+/** @experimental */
+declare const AndroidVideoPlayer: {
+    /**
+     * Publish the presentation surface host object on the JS runtime.
+     *
+     * It is captured into a worklet closure from there; the UI runtime has its
+     * own global and does not see this one.
+     */
+    installVideoSurface(): boolean;
+};
+
+/**
+ * Playback backed by Media3's ExoPlayer.
+ *
+ * Media3 owns decoding, buffering, audio focus, synchronisation, seeking, speed
+ * and lifecycle. Pictor owns the document, the timeline and the Skia
+ * composition. This is the whole of the seam between them.
+ *
+ * **No Media3 or Android type appears here.** Positions are microseconds
+ * because that is Pictor's unit; the adapter converts.
+ *
+ * Video is rendered into the persistent external texture, so the renderer holds
+ * one `SkImage` for a whole session and nothing is imported per frame.
+ *
+ * @experimental
+ */
+interface Media3State {
+    positionUs: number;
+    durationUs: number;
+    playing: boolean;
+    buffering: boolean;
+    ready: boolean;
+    ended: boolean;
+    rate: number;
+    width: number;
+    height: number;
+    released: boolean;
+    error: string;
+    /** Bumped on seek, source change and release; pairs frames with a clip. */
+    generation: number;
+    /** Frame metadata awaiting a renderer. Bounded. */
+    queueDepth: number;
+    /** Metadata dropped because the queue was full. Should stay zero. */
+    overflowed: number;
+    /** Frames consumed with no sample to pair. Expected briefly after a seek. */
+    unpaired: number;
+    /** Samples discarded because their generation was superseded. */
+    stale: number;
+    queueHighWater: number;
+    /** Live threads in the process. Diagnostics for leak attribution. */
+    threads: number;
+    /** Allocated native heap, for the safety cutoff. */
+    nativeHeapBytes: number;
+    /** The anchor's own position, before extrapolation. Diagnostics. */
+    anchorPositionUs: number;
+    /** Frames the buffer queue dropped because the renderer was behind. */
+    coalesced: number;
+    /** How coarse `Player.currentPosition` is, measured rather than assumed. */
+    anchorPublications: number;
+    anchorChanges: number;
+    anchorMaxStepUs: number;
+    anchorMeanStepUs: number;
+    anchorMaxStaleNs: number;
+    /** Which playlist window is playing, and how many there are. */
+    windowIndex: number;
+    windowCount: number;
+    /** Offset inside the current window, in microseconds. */
+    windowPositionUs: number;
+    /** Window transitions so far — seams crossed. Diagnostics. */
+    transitions: number;
+    /**
+     * Frames whose latch failed and was retried on the next tick.
+     *
+     * `updateTexImage` returns quietly when Skia's GL context is not current on
+     * the calling thread, so this counts the retries rather than letting the
+     * frames disappear. A handful around startup and playlist changes is normal;
+     * a rate that tracks the frame rate is not.
+     */
+    missedLatches: number;
+    /**
+     * What the single latch owner did, per frame.
+     *
+     * `skipped` counts ticks refused because the surface was retired or replaced
+     * — the invalid call, prevented rather than caught. `failed` must stay
+     * visible: a latch that quietly does nothing looks exactly like a paused
+     * video, which is how an earlier defect hid for a whole session.
+     */
+    updatesAttempted: number;
+    updatesSucceeded: number;
+    updatesSkipped: number;
+    updatesFailed: number;
+    /**
+     * Times a requested rate exceeded the range and had to be clamped.
+     *
+     * Should stay zero: the UI only offers rates that compose within range. A
+     * non-zero value means the picture and the timeline are counting differently.
+     */
+    rateConstrained: number;
+    /** The rate actually in force: clip speed times preview rate, clamped. */
+    effectiveRate: number;
+    /**
+     * The rate asked for, before clamping.
+     *
+     * Beside `effectiveRate` this says whether a ceiling was *selected* or merely
+     * reached: 10 requested and 10 effective is a legitimate extreme, while 25
+     * requested and 10 effective is a refusal.
+     */
+    requestedRate: number;
+    /**
+     * Window indices that had no speed. Should stay zero.
+     *
+     * Non-zero means the playlist and the window index were read at different
+     * moments — the shape that left a cleared playlist running at the rate of the
+     * playlist before it.
+     */
+    staleWindowSpeeds: number;
+    /** How many per-window speeds the player holds. Zero when idle. */
+    windowSpeedCount: number;
+    /**
+     * The two halves of frame delivery, counted separately.
+     *
+     * `framesOffered` is Media3 telling us a frame is about to be released;
+     * `framesAvailable` is the SurfaceTexture saying one arrived. If the first
+     * climbs while the second does not, the decoder is running but its output is
+     * not reaching our surface — which is a completely different fault from the
+     * renderer failing to pull.
+     */
+    framesOffered: number;
+    framesAvailable: number;
+    /**
+     * Frames waiting to be latched, right now.
+     *
+     * A level rather than an edge, so it survives the consumer being disarmed.
+     * Usually 0 or 1; larger after a background, and it must fall to 0 within a
+     * tick of the consumer re-arming.
+     */
+    pendingDepth: number;
+    /** Availability announced for a generation already retired. Should stay 0. */
+    framesRejected: number;
+    /**
+     * The generation the pending counters are keeping for.
+     *
+     * Must equal the consumer's generation. A frame pending for a different one
+     * is a frame nobody will ever take.
+     */
+    pendingGeneration: number;
+    /** Producer identity, for proving which object a consumer is holding. */
+    controllerId: number;
+    pendingId: number;
+    orphaned: number;
+    /** `mime WxH rotN @fps` for the active item. Empty when there is no video. */
+    videoFormat: string;
+    /** The decoder Media3 selected, e.g. `c2.exynos.h264.decoder`. */
+    decoderName: string;
+    /**
+     * What the decoder was configured for, and what it produced.
+     *
+     * Read from the player's own events rather than inferred from the device: a
+     * mixed-resolution seam is the one moment input and output can disagree, and
+     * naming the decoder from the model instead of asking is how an attribution
+     * survives without ever being checked.
+     */
+    inputFormats: number;
+    inputWidth: number;
+    inputHeight: number;
+    inputRotation: number;
+    /** Media3's decoder-reuse verdict across the last format change; -1 if none. */
+    decoderReuse: number;
+    outputSizes: number;
+    outputWidth: number;
+    outputHeight: number;
+    /** Increments on each decoder init — makes re-attachment visible. */
+    surfaceGeneration: number;
+    /**
+     * Seek bookkeeping for the cross-window freeze soak.
+     *
+     * `seeksRequested` counts calls; `seeksAccepted` counts those the player's
+     * own thread acted on. A gap between them, or a `pendingSeek` that stays
+     * true, is a seek that never reached the player — which is what the observed
+     * freeze would look like from this side.
+     */
+    /**
+     * Surface attachment bookkeeping, for diagnostics only.
+     *
+     * The adapter attaches automatically the instant a surface becomes live, so a
+     * host never calls anything. These exist so the invariant can be *checked*:
+     * `attachedSurfaceGeneration` trailing `liveSurfaceGeneration` means the
+     * player is rendering into a surface nobody is watching.
+     */
+    surfaceAttachments: number;
+    attachedSurfaceGeneration: number;
+    liveSurfaceGeneration: number;
+    seeksRequested: number;
+    seeksAccepted: number;
+    pendingSeek: boolean;
+    /** Media3's own playback state constant. 1 idle, 2 buffering, 3 ready, 4 ended. */
+    playbackState: number;
+    /** PTS of the last frame the renderer actually paired, or -1. */
+    lastPairedPtsUs: number;
+    /**
+     * Source failures reported by the player, not inferred from the state.
+     *
+     * A failed source otherwise looks exactly like an idle one — nothing playing,
+     * nothing buffering, no duration — so the count is what distinguishes "never
+     * started" from "started and broke".
+     */
+    errorCount: number;
+    /** Media3's error code, and its name plus message. Empty when healthy. */
+    errorCode: number;
+    errorMessage: string;
+    /** Whether Media3 classifies the failure as worth retrying. */
+    errorRecoverable: boolean;
+}
+/** @experimental */
+declare const Media3: {
+    /**
+     * Open a local clip and render it into the presentation surface.
+     *
+     * The surface must already exist: it is created on the UI runtime, where
+     * Skia's GL context lives, and preparing without one is an error rather than
+     * a silently black picture.
+     */
+    prepare(uri: string): boolean;
+    /** Diagnostics: a player with no video output, for heap attribution. */
+    prepareNoSurface(uri: string): boolean;
+    /** Diagnostics: reuse the existing player for another source. */
+    rebind(uri: string): boolean;
+    /** Diagnostics: end the source, keep the player. */
+    stopKeepingPlayer(): void;
+    /**
+     * Replace the playlist from a project's playable windows.
+     *
+     * Takes the `PlaylistResult` straight from `@pictor-sdk/video-core` so the
+     * project → window mapping has exactly one definition, tested there as a
+     * round trip.
+     * The sources must already be URI strings; this adapter does not interpret a
+     * host's media descriptors, and a non-URI source is a host normalisation bug
+     * rather than something to guess at.
+     *
+     * The OES texture and the `SkImage` survive this. Changing the playlist is
+     * not a reason to rebuild what the renderer holds.
+     */
+    setPlaylist(playlist: PlaylistResult, start?: {
+        windowIndex: number;
+        positionUs: number;
+    }, options?: {
+        allowDivergence?: boolean;
+    }): boolean;
+    /** Seek in the player's coordinates. Pair with `projectTimeToWindow`. */
+    seekToWindow(windowIndex: number, positionUs: number): void;
+    play(): void;
+    pause(): void;
+    /** Microseconds, like every other time in Pictor. */
+    seek(positionUs: number): void;
+    setRate(rate: number): void;
+    /**
+     * Try the current source again after a failure.
+     *
+     * This is Media3's own recovery path: it re-resolves the source and resumes
+     * from the current position. Worth calling when `errorRecoverable` is true —
+     * a network source that went away and came back — and pointless otherwise.
+     */
+    retry(): void;
+    release(): void;
+    /** A snapshot for throttled reads. Never call this per frame. */
+    state(): Media3State;
+};
+
+/**
+ * Which playlist Media3 is holding, and against which surface.
+ *
+ * The bug this exists to prevent, in order:
+ *
+ * 1. The editor opens and builds surface A.
+ * 2. The system picker opens. The app backgrounds; A is no longer usable.
+ * 3. Two clips are added to the document while the picker is closing.
+ * 4. The editor returns and builds surface B.
+ * 5. Nothing prepares, because the only thing that ever triggered preparation
+ *    was the *playlist changing*, and it changed in step 3 — when there was no
+ *    surface to prepare against. `setPlaylist` was refused, the signature was
+ *    recorded as applied anyway, and the editor sat there with two clips on the
+ *    timeline and a player holding nothing.
+ *
+ * Two corrections follow from that. Readiness is **level-triggered**: the
+ * question is "does the playlist Media3 holds match the document, against the
+ * surface that is live *now*", asked whenever either side moves — not "did the
+ * playlist just change". And a refusal is **not** recorded as applied, so it is
+ * retried rather than remembered as done.
+ *
+ * A generation is what makes "the surface that is live now" expressible. Without
+ * it a caller can only know that *a* surface exists, which cannot distinguish
+ * the one it prepared against from the one that replaced it.
+ *
+ * Pure, so the sequence above is a test rather than a device run.
+ *
+ * @experimental
+ */
+/** No surface. Distinct from every real generation, which start at 1. */
+declare const NO_SURFACE = 0;
+/** @experimental */
+interface PlaylistSession {
+    /** The playlist Media3 is holding, or null if it holds none. */
+    appliedSignature: string | null;
+    /** The surface generation it was prepared against. */
+    appliedGeneration: number;
+    /**
+     * A preparation was attempted and refused.
+     *
+     * Kept so the retry is driven by this rather than by hoping the document
+     * changes again. A user who has added their clips will not add them twice.
+     */
+    pending: boolean;
+}
+/** @experimental */
+declare function idlePlaylistSession(): PlaylistSession;
+/** What the document and the device currently want. @experimental */
+interface PlaylistIntent {
+    /** A stable description of the playlist the document implies. */
+    signature: string;
+    /** The live surface generation, or {@link NO_SURFACE}. */
+    generation: number;
+}
+/**
+ * Whether to call `setPlaylist` now.
+ *
+ * @experimental
+ */
+declare function shouldPrepare(session: PlaylistSession, intent: PlaylistIntent): boolean;
+/**
+ * Record the outcome.
+ *
+ * A refusal leaves the session **unchanged except for `pending`**. Recording the
+ * signature on failure is precisely the mistake that made the editor wait for an
+ * edit that was never going to come.
+ *
+ * @experimental
+ */
+declare function afterPrepare(session: PlaylistSession, intent: PlaylistIntent, ok: boolean): PlaylistSession;
+/**
+ * The surface went away — backgrounded, replaced, released.
+ *
+ * The signature is kept: it still describes what Media3 was asked to hold, and
+ * the comparison that matters next is against the *generation*, which is now
+ * guaranteed to differ from any live one.
+ *
+ * @experimental
+ */
+declare function retireSurface(session: PlaylistSession): PlaylistSession;
+/**
+ * Whether a callback carrying `generation` is still worth acting on.
+ *
+ * A screen's teardown routinely runs after the next screen's setup, and an
+ * asynchronous surface creation can land after the surface it created has been
+ * replaced. Both arrive looking exactly like a valid result.
+ *
+ * @experimental
+ */
+declare function isCurrentGeneration(generation: number, live: number): boolean;
+
+/**
+ * Who is allowed to create a presentation surface, and when.
+ *
+ * There is one external texture in the process, so there is one of these. Not
+ * one per hook instance: a hook is remounted by a navigation, a fast refresh or
+ * a rotation, and each remount would bring its own lock and its own idea of
+ * what is in flight. Two creates then overlap, each registers a generation, and
+ * the second overwrites the native handles the first is still holding — the GL
+ * texture and `SurfaceTexture` from the first are then unreachable and never
+ * released. The symptom is a hook reporting one generation while the adapter
+ * has moved on to another, with an abandoned surface in between.
+ *
+ * ## The generation is native's, and only native's
+ *
+ * `create()` returns the generation `VideoSurface.register` assigned. This
+ * module publishes that number unchanged and keeps no counter of its own — a
+ * second counter is a second answer to "which surface is live", and the whole
+ * class of bug here is two answers to one question.
+ *
+ * ## A superseded attempt is retired, not ignored
+ *
+ * An attempt whose owner went away while it was on the UI runtime still
+ * *succeeds*: the texture exists, the `Surface` is registered, Media3 could
+ * attach to it. Ignoring its report leaves exactly that — a live, registered
+ * surface nobody will ever draw or release. So it is released, on the runtime
+ * that owns the GL context, before anything else is started.
+ *
+ * ## Serialised, and retirement does not unlock
+ *
+ * A request that arrives while an attempt is unresolved is queued, and
+ * backgrounding or unmounting does **not** release the lock: the earlier
+ * attempt is still out there on the UI runtime and will still come back. The
+ * queue is one deep, because every waiting request wants the same thing.
+ *
+ * Effects are injected so the interleavings are deterministic in a test rather
+ * than a matter of timing on a device.
+ *
+ * @experimental
+ */
+/** What native `create()` reports. @experimental */
+interface SurfaceCreateResult {
+    ok: boolean;
+    /** The generation `register` assigned, or 0 on failure. */
+    generation: number;
+    textureId: number;
+    error: string;
+}
+/** @experimental */
+interface SurfaceOwnerEffects {
+    /**
+     * Schedule a create on the UI runtime.
+     *
+     * Must eventually call {@link SurfaceOwner.complete}, whatever happens.
+     */
+    create(): void;
+    /**
+     * Release a specific generation, on the runtime that owns the GL context.
+     *
+     * Takes a generation rather than "the current surface" so a late attempt
+     * cannot release the surface that replaced it.
+     */
+    retire(generation: number): void;
+}
+/** @experimental */
+interface SurfaceReadiness {
+    /** The live generation, exactly as native reported it. 0 when there is none. */
+    generation: number;
+    /** The last failure, or empty. */
+    error: string;
+}
+/** @experimental */
+interface SurfaceOwner {
+    readonly readiness: SurfaceReadiness;
+    /** Whether an attempt is on the UI runtime right now. */
+    readonly busy: boolean;
+    /** Generations created by a superseded attempt and released. Diagnostics. */
+    readonly retired: number;
+    /**
+     * Ask for a surface on behalf of `token`.
+     *
+     * Returns false when the request was queued or refused rather than started.
+     */
+    request(token: number): boolean;
+    /** That owner is gone. Does not unlock: an unresolved attempt is still out there. */
+    retireOwner(token: number): void;
+    /** An attempt finished. */
+    complete(result: SurfaceCreateResult): void;
+    /** Adopt a surface that already exists, without creating one. */
+    adopt(generation: number, token: number): void;
+    subscribe(listener: () => void): () => void;
+    /** Point the owner at the newest caller's effects. */
+    useEffects(next: SurfaceOwnerEffects): void;
+}
+/** @experimental */
+declare function createSurfaceOwner(initial: SurfaceOwnerEffects): SurfaceOwner;
+/** @experimental */
+declare function surfaceOwner(effects: SurfaceOwnerEffects): SurfaceOwner;
+/** @experimental */
+declare function resetSurfaceOwnerForTests(): void;
+/** @experimental */
+declare function nextOwnerToken(): number;
+
+/**
+ * The one stable slot, installed on first ask.
+ *
+ * Synchronous, and callable during a render, because the consumer has to be able
+ * to capture it *before* any surface exists. An effect is too late: the frame
+ * callback is built on the first render, and anything it captures then is what
+ * it keeps.
+ *
+ * The object never changes. `create` fills its target in place and retirement
+ * clears it, so every call through it resolves to whatever the slot points at
+ * now. There is deliberately nothing replaceable to hold.
+ *
+ * @experimental
+ */
+declare function videoSurfaceSlot(): VideoSurfaceHandle | undefined;
+/** @experimental */
+interface VideoSurfaceOptions {
+    /** Backing size of the texture. Frames are scaled into it. */
+    width: number;
+    height: number;
+    enabled?: boolean;
+}
+/**
+ * The surface as the UI runtime sees it.
+ *
+ * Structural rather than an imported Android type: nothing platform-specific
+ * reaches Pictor's public API.
+ *
+ * @experimental
+ */
+interface VideoSurfaceHandle {
+    create(width: number, height: number): {
+        textureId: number;
+        ok: boolean;
+        generation: number;
+        error?: string;
+    };
+    generation(): number;
+    alive(): boolean;
+    /** Release a named generation. Does nothing if it is not the one held. */
+    releaseGeneration(generation: number): boolean;
+}
+/** @experimental */
+interface VideoSurface {
+    /**
+     * The stable slot.
+     *
+     * Available from the first render and never replaced, so a consumer captures
+     * it once and reads through it. It answers `generation() === 0` while empty,
+     * which is how a renderer knows there is nothing to draw — a null would have
+     * to be captured, and a captured null is what it stays.
+     */
+    surface: unknown | undefined;
+    /**
+     * The live generation, exactly as native reported it. 0 when there is none.
+     *
+     * Feed to `useMedia3Playback`. Every change is a reason to reconcile the
+     * playlist, including the change back to 0.
+     */
+    generation: number;
+    /** Failure to install or create, for a host's error slot. Empty when healthy. */
+    error: string;
+}
+/** @experimental */
+declare function useVideoSurface(options: VideoSurfaceOptions): VideoSurface;
+
+/**
+ * Who owns playback, and until when.
+ *
+ * Media3's player is a **process-wide singleton**. Nothing about it ends when
+ * the screen that started it goes away, so on a Pixel 7 leaving the editor while
+ * playing left the audio running, and backgrounding the app did the same: the
+ * picture stopped because its surface was retired, and the sound carried on
+ * because nobody had told the player anything.
+ *
+ * A singleton with no owner is the whole problem, so this gives it one. A screen
+ * takes ownership when it mounts and gives it back exactly once — and a screen
+ * that mounts afterwards starts from nothing rather than inheriting whatever the
+ * last one was doing.
+ *
+ * ## Two kinds of stopping, deliberately different
+ *
+ * **Suspend** is temporary: the app went to the background, or the picker came
+ * up over the editor. Playback pauses and the player is kept, because the screen
+ * is coming back and rebuilding a player it never lost would be a stall the user
+ * did nothing to earn.
+ *
+ * **Teardown** is final: the screen unmounted, or navigation left it. The player
+ * is paused *and then* released, in that order, so nothing is audible in the
+ * gap. After a teardown this object does nothing at all — a late suspend from a
+ * listener that has not been removed yet must not resurrect anything.
+ *
+ * Neither is a reason to touch the document. Playback stopping says nothing
+ * about what the project is or where its playhead should be, and clearing either
+ * would turn leaving a screen into an edit.
+ *
+ * ## Epochs
+ *
+ * Every stop bumps an epoch, and callbacks carry the epoch they were scheduled
+ * under. A poll that fires after the screen backgrounded still runs — clearing
+ * an interval is not instantaneous — and `accepts` is how it finds out that the
+ * answer it is about to deliver is no longer wanted.
+ *
+ * @experimental
+ */
+/** Why playback stopped. Recorded so a log can say which path ran. @experimental */
+type PlaybackStopReason = 'unmount' | 'background' | 'blur';
+/** @experimental */
+interface PlaybackLifecycleEffects {
+    /** Stop the sound. Must be safe to call when already paused. */
+    pause(): void;
+    /** Give up the native player, and with it audio focus. */
+    release(): void;
+}
+/** @experimental */
+interface PlaybackLifecycle {
+    /** Whether this screen currently owns running playback. */
+    readonly active: boolean;
+    /** Whether the player has been given back. Final. */
+    readonly released: boolean;
+    /** Why it last stopped, or `null`. */
+    readonly reason: PlaybackStopReason | null;
+    /** Bumped by every stop; callbacks carry the value they were scheduled under. */
+    readonly epoch: number;
+    /** Whether work scheduled under `epoch` may still act. */
+    accepts(epoch: number): boolean;
+    /** Pause and keep the player. Idempotent within one suspension. */
+    suspend(reason: PlaybackStopReason): void;
+    /** Become active again. Idempotent; ignored after teardown. */
+    resume(): void;
+    /** Pause, then release, exactly once, forever. */
+    teardown(reason: PlaybackStopReason): void;
+}
+/** @experimental */
+declare function createPlaybackLifecycle(effects: PlaybackLifecycleEffects): PlaybackLifecycle;
+
+/**
+ * Deciding that a restored surface is not actually showing anything.
+ *
+ * After a background, a picker, or any other trip away from the editor, the
+ * player and the surface have to find each other again. When that handshake
+ * half-succeeds the result is the worst kind of failure: audio plays, the clock
+ * advances, no error is reported, and the picture is black. Nothing in the
+ * player's own state says anything is wrong, because from its point of view
+ * nothing is.
+ *
+ * So it is decided from the counters instead, and the counters are already
+ * separated into the four things that can go wrong — see `Media3State`, where
+ * `framesOffered` is the decoder saying a frame is coming and `framesAvailable`
+ * is the surface saying one arrived.
+ *
+ * The point of naming the branch is that the repairs differ. Re-running the
+ * handshake fixes a stale generation and does nothing at all for a consumer
+ * that has stopped pulling, and "retry everything" would have made both look
+ * like the same intermittent bug.
+ *
+ * @experimental
+ */
+/** How long a stall must persist before it counts. @experimental */
+declare const RECOVERY_GRACE_MS = 1500;
+/** What a sample of the pipeline looked like at one instant. @experimental */
+interface RecoverySample {
+    atMs: number;
+    /** The player's own clock. Advancing means audio is being produced. */
+    positionUs: number;
+    /** Media3 announcing frames. */
+    framesOffered: number;
+    /** The SurfaceTexture receiving them. */
+    framesAvailable: number;
+    /** Frames the consumer actually took. */
+    framesLatched: number;
+    /** Announcements for a generation already retired. */
+    framesRejected: number;
+    /** The generation the producer is filling. */
+    pendingGeneration: number;
+    /** The generation the consumer is watching. */
+    consumerGeneration: number;
+}
+/**
+ * Which half of the pipeline is broken, or `null` when it is healthy.
+ *
+ * @experimental
+ */
+type StallKind = 
+/** Frames arrive and nobody takes them: the consumer or its frame loop. */
+'consumer'
+/** Producer and consumer disagree about which surface: a stale handshake. */
+ | 'handshake'
+/** The player is running but nothing reaches the surface: attachment. */
+ | 'attachment'
+/** Frames are latched and the picture is still wrong: scene or image. */
+ | 'resource';
+/**
+ * Name the branch from two samples.
+ *
+ * `null` means nothing is wrong *that this can see* — including the ordinary
+ * case of a player that is simply not advancing, which is what a paused editor
+ * looks like and is not a fault.
+ *
+ * @experimental
+ */
+declare function classifyStall(since: RecoverySample, now: RecoverySample): StallKind | null;
+/**
+ * Whether the stall has lasted long enough to act on.
+ *
+ * A grace period because none of this is instantaneous: a surface is recreated,
+ * a playlist is reconciled and the first frame decoded, and a check that fired
+ * inside that window would recover a pipeline that was about to work.
+ *
+ * @experimental
+ */
+declare function shouldRecover(since: RecoverySample, now: RecoverySample, graceMs?: number): boolean;
+
+/**
+ * Keep a Media3 playlist in step with a project, and the playhead with playback.
+ *
+ * Two directions, deliberately separated:
+ *
+ * - **Project → player.** When the clips, their order or their trims change,
+ *   the playlist is replaced. The current *project time* is preserved across
+ *   that, not the window index — deleting the second of four clips must not
+ *   leave the playhead in whatever the second window now happens to be.
+ * - **Player → playhead.** While playing, the player's position is polled at a
+ *   readable rate and mapped back to project time. This is a **throttled
+ *   semantic update**, not a per-frame one: the picture is composed on the UI
+ *   runtime from the external texture and never waits for React.
+ *
+ * The playlist is only replaced when it genuinely differs. A trim drag
+ * dispatches a command per finger sample, and rebuilding the playlist on each
+ * would restart decoding many times a second.
+ *
+ * @experimental
+ */
+/** @experimental */
+interface UseMedia3PlaybackOptions {
+    project: VideoProject;
+    /** Timeline time the host wants shown. */
+    playheadUs: number;
+    /** Called with the project time as playback advances. Throttled. */
+    onPositionUs?: (timeUs: number) => void;
+    /** How often to poll the player, in milliseconds. */
+    pollMs?: number;
+    /**
+     * The live presentation surface generation, from `useVideoSurface`.
+     *
+     * Not a boolean. A playlist prepared against a retired surface renders into
+     * something nobody is watching — the player decodes, releases frames and
+     * reports no error — so the question is *which* surface, not whether one
+     * exists. Every change is a reason to reconcile, including the change to 0.
+     */
+    surfaceGeneration?: number;
+    enabled?: boolean;
+}
+/** @experimental */
+interface Media3Playback {
+    playing: boolean;
+    /**
+     * Start or resume playback, replaying from zero when there is nothing left.
+     *
+     * Returns what it decided, so a host can show it or count it. See
+     * `playIntent` in `@pictor-sdk/video-core` for why the end is a special case.
+     */
+    play(): PlayIntent;
+    pause(): void;
+    setRate(rate: number): void;
+    /** Seek in project time. Mapped to the player's own coordinates. */
+    seek(timeUs: number): void;
+    state: Media3State | null;
+    /** The windows currently loaded, for diagnostics and gates. */
+    items: readonly PlaylistItem[];
+    /**
+     * Clips the player cannot open. Non-empty means playback is **not** loaded.
+     *
+     * Surfaced rather than swallowed: the alternative is an editor that plays a
+     * shorter timeline than it draws, which reads as a synchronisation bug.
+     */
+    unsupported: readonly UnsupportedSource[];
+    /**
+     * Which half of the pipeline stalled after a surface restoration, or `null`.
+     *
+     * Non-null means a black picture was detected and the handshake re-run — a
+     * host should surface it rather than show a silent audio-only result.
+     */
+    stall: StallKind | null;
+    /**
+     * This screen's ownership of the shared player, for diagnostics and gates.
+     *
+     * Exposed so a host can log which path stopped playback and assert that a
+     * screen released exactly once.
+     */
+    lifecycle: PlaybackLifecycle;
+    /**
+     * How far the timeline and the player disagree, in microseconds. Zero when
+     * everything is playable, and asserted by the device gates.
+     */
+    divergenceUs: number;
+    /**
+     * The player's position in project time, read now, without rendering.
+     *
+     * For a host driving a UI-thread playhead: it samples this a few times a
+     * second and advances between samples itself. Returns `null` when the player
+     * has no position to give — before a playlist is loaded, or after release.
+     */
+    positionUs(): number | null;
+    /**
+     * The rate actually in force: clip speed and preview rate, composed and
+     * clamped by the adapter. A host showing a rate should show this one.
+     */
+    effectiveRate: number;
+    /**
+     * The last seek this hook actually issued.
+     *
+     * Global time in, and the `{windowIndex, localUs}` it was converted to. A
+     * player reporting an unexpected position is either being sent the wrong
+     * thing or mishandling the right thing, and those need different fixes — this
+     * is what tells them apart instead of leaving it to arithmetic on a
+     * screenshot.
+     */
+    lastSeek: {
+        globalUs: number;
+        windowIndex: number;
+        localUs: number;
+    } | null;
+}
+/** @experimental */
+declare function useMedia3Playback(options: UseMedia3PlaybackOptions): Media3Playback;
+
+/**
+ * The preview, on one clock.
+ *
+ * ## What this replaces
+ *
+ * Two players kept in step: a video player and a separate player for the
+ * prepared audio mix, with a drift check correcting between them. That
+ * architecture was measured to its limit and could not hold synchronisation
+ * across a clip seam — the correction is a seek, a seek costs a decode, and a
+ * decode at the moment of a seam is what the correction was trying to cover.
+ *
+ * A `CompositionPlayer` has one clock, one playback thread and one audio graph.
+ * The prepared mix becomes an audio-only sequence beside the video sequence, so
+ * the two cannot drift: there is nothing to drift against.
+ *
+ * ## What it does not fix
+ *
+ * The clip seam still costs a picture. Media3 tears down the video decoder at
+ * an item boundary and builds another, and for 119 to 168 ms nothing reaches
+ * the renderer while the clock runs on — the audio is continuous and the
+ * picture holds. That behaviour was watched on a device and accepted for v1;
+ * see `docs/research/preview-acceptance.md` for what was accepted and what was
+ * explicitly not.
+ *
+ * ## Why the same contract
+ *
+ * It returns {@link Media3Playback}, unchanged. The editor, the transport and
+ * the gates were all written against it, and swapping the engine underneath is
+ * a smaller and more reviewable change than rewriting every caller to a shape
+ * that would end up equivalent.
+ *
+ * @experimental
+ */
+interface UseCompositionPlaybackOptions {
+    project: VideoProject;
+    /** Timeline time the host wants shown. */
+    playheadUs: number;
+    /**
+     * The prepared audio program, from `usePreviewAudio`.
+     *
+     * Null while it is being prepared, after it has failed, and — legitimately —
+     * when the document has no audio at all.
+     *
+     * Those are different situations and the hook has to tell them apart. A
+     * document *with* audio waits: building the composition without its sound
+     * would play a silent preview and gain the music a second later, which is two
+     * timelines to anyone watching. A document *without* audio has nothing to
+     * wait for, and refusing to build would leave the picture dead.
+     */
+    mix: {
+        uri: string;
+        durationUs: number;
+    } | null;
+    /** Turns a document source into something the player can open. */
+    resolveSource: (source: {
+        kind: string;
+        uri?: string;
+    }) => string | null;
+    /** @see UseMedia3PlaybackOptions.surfaceGeneration */
+    surfaceGeneration?: number;
+    enabled?: boolean;
+}
+/**
+ * What a composition knows about itself.
+ *
+ * Deliberately not `Media3State`. That type is the shape the video player's
+ * native state comes back in — forty fields about queue depth, anchors, native
+ * heap and window indices — and a composition has none of them. Synthesising
+ * one would be inventing forty numbers to satisfy a type, and a reader would
+ * have no way to tell the invented ones from the measured ones.
+ *
+ * @experimental
+ */
+interface CompositionPlaybackState {
+    playing: boolean;
+    ready: boolean;
+    buffering: boolean;
+    ended: boolean;
+    released: boolean;
+    /** Project time, which for a single composition is the only time there is. */
+    positionUs: number;
+    durationUs: number;
+    /** The presentation size, or 0 while nothing has been measured. */
+    width: number;
+    height: number;
+    error: string | null;
+}
+/** @experimental */
+type CompositionPlayback = Omit<Media3Playback, 'state'> & {
+    state: CompositionPlaybackState | null;
+};
+/** @experimental */
+declare function useCompositionPlayback(options: UseCompositionPlaybackOptions): CompositionPlayback;
+
+/**
+ * `ThumbnailProvider` over Media3's retriever, with the core policy on top.
+ *
+ * The division is the point: `@pictor-sdk/video-core` owns deduplication, the
+ * bounded cache and visible-range ordering, all of which are pure; this file
+ * owns the part that needs a codec. A host that writes its own provider — for a
+ * remote thumbnail service, say — reuses the policy and replaces only this.
+ *
+ * Results arrive as base64 JPEG rather than as a native image handle. A strip
+ * thumbnail is a few kilobytes and it is drawn by React Native's own image
+ * pipeline, so there is nothing here to leak and no ownership to transfer. The
+ * `AHardwareBuffer` lesson applies to full-resolution frames at 30 per second,
+ * not to a 64-pixel square that changes when the user scrolls.
+ *
+ * @experimental
+ */
+/** @experimental */
+interface AndroidThumbnailOptions {
+    /**
+     * How many decoded thumbnails to keep.
+     *
+     * 240 covers several screens of a dense strip at 64 px — enough that
+     * scrolling back does not re-decode, bounded enough that a long project
+     * cannot grow without limit.
+     */
+    capacity?: number;
+    /** How often to check whether a decode has finished, in milliseconds. */
+    pollMs?: number;
+}
+/** @experimental */
+declare function createAndroidThumbnailProvider(options?: AndroidThumbnailOptions): ThumbnailProvider;
+/** Decode counters, for gates and diagnostics. @experimental */
+declare function thumbnailCounters(): {
+    decoded: number;
+    cancelled: number;
+    failed: number;
+    running: number;
+    retrievers: number;
+};
+
+/**
+ * Deciding when playback has settled, instead of assuming it after a timeout.
+ *
+ * The first attempt excluded a fixed 1.5 s after every transition. That is a
+ * guess in both directions: too short for a seek, whose tail leaked into the
+ * steady figures, and too long for a rate change that settles immediately. It
+ * also hides the thing worth knowing — how long recovery actually took.
+ *
+ * So a transition opens a phase, and the phase closes when the offsets say so:
+ * [CONVERGED_RUN] consecutive samples inside the expected bound. The recovery
+ * duration and the worst offset seen on the way are kept, because a transient
+ * that is excluded but not reported is a failure nobody can see.
+ *
+ * [MAX_RECOVERY_SAMPLES] is a safety net, not a policy. A phase that never
+ * converges is closed anyway and marked, so a permanent failure surfaces as a
+ * failure instead of an ever-growing exclusion window.
+ *
+ * Pure, so the rule is tested rather than trusted.
+ *
+ * @experimental
+ */
+/** What kind of transition opened a phase. Steady is the absence of one. */
+type Phase = 'steady' | 'startup' | 'seek' | 'source' | 'pauseResume' | 'rateChange';
+/**
+ * Consecutive in-bound samples that end a transient.
+ *
+ * Eight at 30 fps is about a quarter second of agreement — long enough that a
+ * single lucky frame cannot close a phase, short enough to measure recovery
+ * rather than round it up.
+ */
+declare const CONVERGED_RUN = 8;
+/** A phase is closed after this many samples whatever they say. */
+declare const MAX_RECOVERY_SAMPLES = 600;
+interface PhaseState {
+    phase: Phase;
+    /** Offsets collected while this phase was open. */
+    samples: number[];
+    /** Consecutive in-bound samples so far. */
+    run: number;
+    /** Worst absolute offset seen during the transient, in microseconds. */
+    worstUs: number;
+    /** Samples taken before it converged. */
+    recoverySamples: number;
+    /** True once converged; further samples belong to steady state. */
+    converged: boolean;
+    /** True when the safety net closed it instead of convergence. */
+    timedOut: boolean;
+}
+declare function beginPhase(phase: Phase): PhaseState;
+/**
+ * Feed one offset. Returns the updated phase and where the sample belongs.
+ *
+ * A sample taken while a transient is open belongs to that transient, never to
+ * steady state — merging them would report the transitions as if they were
+ * playback.
+ */
+declare function observe(state: PhaseState, offsetUs: number, boundUs: number): {
+    state: PhaseState;
+    bucket: Phase;
+};
+/** How long recovery took, in frames, or null while still recovering. */
+declare function recoveryFrames(state: PhaseState): number | null;
+
+/**
+ * The Media3 exporter.
+ *
+ * Honours `VideoExporter` in full: asynchronous, cancellable while it runs,
+ * monotonic progress, temporary and file destinations, one export at a time,
+ * typed refusal, cancellation, stall and failure, and deterministic cleanup on
+ * every one of those paths.
+ *
+ * Nothing constructs it for you. It is not on `VideoRuntime`, not behind the
+ * editor's Next button, and not reachable from `@pictor-sdk/video-ui` — a host
+ * builds it explicitly, which is what keeps the surface reviewable. Wiring it
+ * to a button is Slice 5's job, not this file's.
+ *
+ * ## The gate boundary
+ *
+ * Nothing here reaches a `exportGate*` method. Provenance hashing, fault
+ * injection, artificial holds and test beats live behind
+ * `exportGateEnableDiagnostics`, which this never calls, and which leaves them
+ * inert even when a payload asks for them.
+ *
+ * ## The whole project is interpreted here, in TypeScript
+ *
+ * `planClipShards` and `compileVideoSceneProgram` run once, sources are resolved
+ * once, overlays are rasterised once, and what crosses to native is a list of
+ * shards, a compiled program and a resource manifest — all JSON and file paths.
+ * Native never sees a `VideoProject`, a `VideoClip`, a trim, a speed or a
+ * transform field. It looks up segments by timestamp and draws what they say.
+ *
+ * ## It refuses rather than approximating
+ *
+ * Every clip kind, spec field and overlay state this slice does not implement is
+ * rejected by name before anything is encoded. A photo clip silently skipped, or
+ * a bitrate silently ignored, produces a file that is plausible and wrong — and
+ * a plausible wrong file is worse than no file, because nothing downstream can
+ * tell it apart from a correct one.
+ *
+ * @experimental
+ */
+/**
+ * An overlay raster, described structurally.
+ *
+ * Deliberately not imported from `@pictor-sdk/video-skia`. The adapter has no
+ * opinion about how an overlay is rendered — that is the whole point of the
+ * boundary — and importing the renderer would drag Skia into a package whose
+ * job is to talk to Media3. What it needs is the shape of a descriptor, which
+ * is JSON.
+ *
+ * @experimental
+ */
+interface OverlayResourceDescriptor {
+    overlayId: string;
+    resourceId: string;
+    size: {
+        width: number;
+        height: number;
+    };
+    rasterBounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    rasterScale: number;
+    rasterWidth: number;
+    rasterHeight: number;
+    format: string;
+    premultiplied: boolean;
+    colorSpace: string;
+    file: string;
+    byteLength: number;
+    checksum: number;
+}
+/** What preparing a program's overlays produced. @experimental */
+interface OverlayPreparationResult {
+    resources: readonly OverlayResourceDescriptor[];
+    /** Still resolving. An export must not proceed and omit them. */
+    pending: readonly string[];
+    /** Cannot be exported at all. */
+    invalid: readonly {
+        overlayId: string;
+        kind: string;
+        reason: string;
+    }[];
+}
+/** Everything the host must supply. @experimental */
+interface Media3ExporterOptions {
+    /**
+     * Turn an opaque `MediaSource` into something Android can open.
+     *
+     * The exporter never inspects a descriptor: `MediaSource` is `JsonValue` and
+     * only the host knows whether it is an asset id, a content URI or a row in a
+     * database. Returning `null` fails the export naming the clip or the span.
+     *
+     * `context` says which part of the project is being resolved. It used to be
+     * the clip, which left the audio path with nothing honest to pass: every
+     * span, project music included, was resolved with the *first video clip* as
+     * context. A resolver that keys on the clip returned that clip's media for
+     * the whole timeline's audio — a plausible file with the wrong sound in it.
+     */
+    resolveSource(source: MediaSource, context: ExportSourceContext): string | null;
+    /**
+     * Rasterise every overlay the compiled program names.
+     *
+     * The host wires its registry, its prepared resources and its raster sink
+     * behind this — typically `prepareProgramOverlayExports` from
+     * `@pictor-sdk/video-skia`. Injecting the whole step rather than its three inputs
+     * is what keeps this package free of a renderer dependency, and it is the same
+     * reason `resolveSource` is injected rather than a media library being.
+     *
+     * Omitted means "no overlays are exportable": a project that has any then
+     * fails naming each one, rather than exporting without them.
+     */
+    prepareOverlays?(program: {
+        segments: readonly {
+            commands: readonly unknown[];
+        }[];
+    }, projectSize: {
+        width: number;
+        height: number;
+    }, rasterScale: number): OverlayPreparationResult;
+    /**
+     * Called after an export finishes, successfully or not.
+     *
+     * The sidecars belong to the host's raster sink, so the host removes them.
+     * Passing the list rather than the sink keeps this from having to know how
+     * they were stored.
+     */
+    releaseResources?(files: readonly string[]): void;
+    /**
+     * How long without any heartbeat counts as wedged.
+     *
+     * Defaults to {@link STALL_GRACE_MS}, which is **Pixel 7 evidence**: the worst
+     * legitimate silence measured across seven production-path cases on that
+     * device, with margin. It is not a claim about Android. A slower encoder, a
+     * thermally throttled phone or a codec that batches differently can produce a
+     * longer honest gap, and the number to change is this one — raising it costs
+     * only how late a genuine wedge is noticed, while leaving it too low kills
+     * healthy exports.
+     */
+    stallGraceMs?: number;
+    /**
+     * How often native counters are read, and progress delivered.
+     *
+     * Defaults to 125 ms — 8 Hz, inside the 5–10 Hz a person can actually read.
+     * Native counting is unthrottled regardless; this is only the bridge rate.
+     */
+    progressPollMs?: number;
+}
+/** Why an export will not start. @experimental */
+declare class VideoExportRejected extends Error {
+    readonly reasons: readonly string[];
+    constructor(reasons: readonly string[]);
+}
+/**
+ * Build an exporter.
+ *
+ * @experimental
+ */
+declare function createMedia3VideoExporter(options: Media3ExporterOptions): VideoExporter;
+
+/**
+ * One export at a time, settled exactly once, cancellable anywhere.
+ *
+ * The experimental exporter blocked the bridge for a whole encode and threw
+ * from `cancel()`. That was honest — a silent no-op behind a cancel button is
+ * worse than a refusal — but it is not something a host can ship, so this is the
+ * orchestration that makes cancellation real.
+ *
+ * ## Why cancellation cannot just reject the promise
+ *
+ * A Transformer nobody is listening to still encodes, still writes and still
+ * holds its codecs. Rejecting in JavaScript would hand the host a cancelled
+ * state over an export that is still running, still filling the cache and still
+ * about to produce a file nobody is waiting for. So `cancel` reaches native
+ * first and the promise settles from the job's own checkpoints.
+ *
+ * ## Checkpoints
+ *
+ * Cancellation is cooperative. The work is a sequence of stages, each of which
+ * calls {@link ExportJob.checkpoint} on the way past, and the first checkpoint
+ * after a cancel throws. That is why the stages are named: a cancellation
+ * carries where it stopped, which is the difference between a log that says
+ * "cancelled" and one that says which resources were live at the time.
+ *
+ * ## Settling once
+ *
+ * Every path — success, failure, cancellation — clears the active job, and
+ * nothing may be delivered afterwards. A progress callback that arrives after a
+ * host has shown a result is a UI that goes backwards from "done".
+ *
+ * @experimental
+ */
+/** The lifecycle points an export can be stopped at. @experimental */
+declare const EXPORT_STAGES: readonly ["resolving", "overlays", "shards", "cadence", "audio", "concatenating", "finalising", "publishing"];
+/** @experimental */
+type ExportStage = (typeof EXPORT_STAGES)[number];
+/** @experimental */
+interface ExportJob {
+    readonly id: string;
+    /**
+     * Give cancellation a chance to take effect.
+     *
+     * Throws {@link VideoExportCancelled} if the job has been cancelled. Called
+     * between stages and inside long loops, because a cancel that can only be
+     * observed when the work finishes is not a cancel.
+     */
+    checkpoint(stage: ExportStage): void;
+    /** Deliver progress, unless the job has settled. */
+    progress(value: number, deliver: (value: number) => void): void;
+}
+/** @experimental */
+interface ExportJobsOptions {
+    /**
+     * Stop the native side of a job.
+     *
+     * Given the job id so a late cancel cannot stop a *different* export that
+     * started in the meantime.
+     */
+    cancelNative(jobId: string): void;
+    /** Injected in tests. */
+    now?: () => number;
+}
+/**
+ * The job domain's ledger.
+ *
+ * Kept apart from the native run counters on purpose. One export job drives
+ * several Transformer runs, so adding a job total to a run total produces a
+ * number that reconciles with nothing — and reads like a reconciliation, which
+ * is worse than reporting neither.
+ *
+ * @experimental
+ */
+interface ExportJobCounts {
+    /** Jobs that began. Refused starts are not accepted jobs. */
+    accepted: number;
+    succeeded: number;
+    cancelled: number;
+    failed: number;
+    /** Exactly 0 or 1: one job at a time. */
+    active: number;
+}
+/** @experimental */
+interface ExportJobs {
+    /** The running job's id, or `null`. */
+    readonly active: string | null;
+    /**
+     * `accepted === succeeded + cancelled + failed + active`, always.
+     *
+     * Terminal outcomes are mutually exclusive: a cancelled job is not also a
+     * failed one, however it unwound.
+     */
+    readonly counts: ExportJobCounts;
+    /** Run `body` as the one active job. */
+    run<T>(body: (job: ExportJob) => Promise<T>): Promise<T>;
+    /** Ask the running job to stop. Idempotent; a no-op when none is running. */
+    cancel(): void;
+}
+/** @experimental */
+declare function createExportJobs(options: ExportJobsOptions): ExportJobs;
+
+/**
+ * How far an export has got, and how to tell slow from stuck.
+ *
+ * ## Weighting is derived, not decided
+ *
+ * Equal percentages per stage would be a lie the bar tells: a 0.1× shard writes
+ * three hundred frames while its neighbour writes sixty, and splitting them
+ * evenly makes the first appear stuck and the second appear instant. The weights
+ * come from the work the compiler already planned — output frames per shard,
+ * audio samples, the mux — so the bar moves at the rate the encoder does.
+ *
+ * Output frames, specifically. Cadence changes how many frames a shard *writes*
+ * for a given source, and writing is what the progress is measuring the passage
+ * of; counting source frames would make slow motion look fast and fast motion
+ * look stuck.
+ *
+ * ## What 1 means
+ *
+ * One is not "the encoder finished". It is "the destination is complete and
+ * readable", which is a later moment: there is still a mux, and after that a
+ * publication. Reporting 1 at the end of encoding produces a "done" that cannot
+ * yet be opened, which is worse than a bar that sits at 97 for a moment.
+ *
+ * ## Progress and heartbeat are different signals
+ *
+ * **Progress** is completed work shown to a person, throttled to a handful of
+ * updates a second because nobody can read more than that and every update
+ * costs a bridge crossing.
+ *
+ * **Heartbeat** is evidence that work is still happening. It is not throttled,
+ * it does not have to move the visible percentage, and it is counted natively:
+ * a single muxed sample batch or a block of copied destination bytes is a
+ * heartbeat even when the bar does not visibly change for a second.
+ *
+ * Conflating them is what makes a watchdog wrong in both directions. Keyed on
+ * visible progress, a long mux or a large destination copy looks stalled
+ * because its percentage barely moves; keyed on elapsed time per stage, a 0.1×
+ * shard that legitimately runs for minutes looks stalled too. What actually
+ * marks a wedge is **silence** — no heartbeat from any source at all.
+ *
+ * @experimental
+ */
+/** What a shard will write. @experimental */
+interface ShardPlan {
+    /** Output frames, after cadence. */
+    frames: number;
+}
+/** @experimental */
+interface ProgressPlanInput {
+    shards: readonly ShardPlan[];
+    /** Mixed audio samples the timeline will produce. Zero when silent. */
+    audioSamples: number;
+    durationUs: number;
+}
+/** Fractions of the whole export, summing to 1. @experimental */
+interface ProgressPlan {
+    shardWeights: number[];
+    audioWeight: number;
+    /** Concatenation and mux: real work, and the last thing before publication. */
+    muxWeight: number;
+    /**
+     * Publication: writing the destination and making it readable.
+     *
+     * Held back deliberately so the encoded-and-muxed state cannot reach 1. A bar
+     * that fills before the file exists produces a "done" that cannot be opened,
+     * which is a worse lie than sitting at 97 for a moment.
+     */
+    publishWeight: number;
+    durationUs: number;
+    /** The totals the fractions are measured against. */
+    shardFrames: number[];
+    audioSamples: number;
+}
+/**
+ * How long without a heartbeat counts as wedged.
+ *
+ * Derived from the longest silence real work produces, not from how long the
+ * platform takes to notice a wedge. The first version had that backwards — it
+ * justified twelve seconds by sitting *past* Media3's observed 10.5 s stall
+ * detection, which makes a watchdog decorative: it can only ever be the second
+ * thing to notice.
+ *
+ * The maximum legitimate heartbeat gap, measured across **three passes of seven
+ * cases** on a Pixel 7 — short and long 1×, 0.1× and 10× cadence, mixed-speed
+ * multi-clip, muted, and project audio — is **2046 ms**, in the 0.1× case. Seven
+ * seconds is 3.4× that, and 3.5 s ahead of the platform's own 10.5 s stall
+ * detection. Both margins are the point: too close to the first and it fires on
+ * healthy work, too close to the second and it is not worth having.
+ *
+ * Three passes rather than one because a single pass is not a maximum. The same
+ * 0.1× case measured 1668, 1426 and 2046 ms in three different sessions, and a
+ * threshold frozen from the lowest of those would have been derived from a run
+ * that happened to go well.
+ *
+ * ## Two corrections this number carries
+ *
+ * The first series measured 1668 ms with gate provenance hashing running — every
+ * sample of both intermediates and the result read and digested, beating as it
+ * went. A threshold calibrated against work the user never pays for is
+ * calibrated against the wrong export, so the hashing moved behind a conformance
+ * flag. The second series missed the *per-shard* hashing, which was still
+ * running. With all of it gated the worst source moved from `muxBatch` to
+ * `audioBlock`: the mux beats on its own sample batches, and once the hashing
+ * that was reading them stopped, the audio mix became the quietest stage again.
+ *
+ * ## The headroom here is small, and that is the finding
+ *
+ * 3.4× the worst gap and 3.5 s before the platform leaves roughly one doubling
+ * of the worst legitimate silence before the two constraints meet. On a slower
+ * encoder there may be no gap between them at all, which is why
+ * `Media3ExporterOptions.stallGraceMs` exists.
+ *
+ * Any of this was only measurable after the silence was instrumented rather
+ * than tolerated. Before, the maximum gap was 5.4 s and no useful threshold
+ * existed between it and the platform's timeout; the gap turned out to be the
+ * Sonic time-stretch and AAC encode inside the audio mix, which at 0.1× turn one
+ * second of source into ten with nothing beating.
+ *
+ * @experimental
+ */
+declare const STALL_GRACE_MS = 7000;
+/** The measured maximum, kept beside the threshold it justifies. @experimental */
+declare const MAX_OBSERVED_HEARTBEAT_GAP_MS = 2046;
+/** @experimental */
+declare function planProgressWeights(input: ProgressPlanInput): ProgressPlan;
+/** @experimental */
+interface ProgressReporterOptions {
+    plan: ProgressPlan;
+    durationUs: number;
+    onProgress?: (progress: VideoExportProgress) => void;
+    /** Bridge crossings are bounded to roughly this spacing. */
+    throttleMs?: number;
+    now?: () => number;
+}
+/** @experimental */
+interface ProgressReporter {
+    /** Emit 0, once, when work begins. */
+    begin(): void;
+    /** Report a shard's completed output frames. */
+    shard(index: number, framesDone: number): void;
+    /** Report mixed audio samples. */
+    audio(samplesDone: number): void;
+    /** Concatenation and mux finished. Not 1. */
+    muxed(): void;
+    /** The destination is complete and readable. Emits 1, once. */
+    complete(): void;
+    /**
+     * Apply several updates and emit at most once.
+     *
+     * A poll reads every shard, the audio and the mux together, and without this
+     * the first of those spends the throttle slot and the rest are dropped until
+     * the next tick — so the last shard's frames and the whole audio mix could
+     * arrive a tick late or, at the end of an export, never. One read of native
+     * state is one update to the bar.
+     */
+    batch(body: () => void): void;
+    /** Deliver nothing further. */
+    stop(): void;
+}
+/** @experimental */
+declare function createProgressReporter(options: ProgressReporterOptions): ProgressReporter;
+/** What a wedged export looked like when it was noticed. @experimental */
+interface StallVerdict {
+    stage: ExportStage | string;
+    units: number;
+    idleMs: number;
+}
+/** @experimental */
+interface StallWatchdogOptions {
+    thresholdMs?: number;
+}
+/** @experimental */
+interface StallWatchdog {
+    /**
+     * Record a heartbeat. Any beat counts, whether or not it moved the bar.
+     *
+     * `units` is carried for the report only — a repeated count is still a
+     * heartbeat, because the pipeline spoke.
+     */
+    advanced(stage: ExportStage | string, units: number, atMs: number): void;
+    /** The verdict if nothing has reported for the threshold, else `null`. */
+    stalledFor(atMs: number): StallVerdict | null;
+}
+/**
+ * Slow is not stuck.
+ *
+ * Keyed on *any* report rather than on elapsed time per stage: a 0.1× export
+ * spends minutes inside one shard and is perfectly healthy while doing it, and
+ * a stage timeout would either fire on that or be too long to catch anything.
+ * What distinguishes a wedge is silence.
+ *
+ * Fires once. A wedged export is one event, and the cleanup it triggers is the
+ * same path cancellation already proved.
+ *
+ * @experimental
+ */
+declare function createStallWatchdog(options?: StallWatchdogOptions): StallWatchdog;
+
+/**
+ * Saving a finished export into Android's video collection.
+ *
+ * A thin boundary. The insert-pending / stream / verify / publish sequence is
+ * native, because it is where the file descriptors and the cancellation live;
+ * this turns one JSON result into either a {@link SavedMedia} or a typed error,
+ * and gives every save an id so a cancel reaches the right one.
+ *
+ * ## What a failure guarantees
+ *
+ * Nothing partial. Every unsuccessful native path — a short write, a full disk,
+ * a cancellation, an unreadable result — deletes the pending row before
+ * returning, and a pending row was never visible to the gallery in the first
+ * place. So a failed save leaves the collection exactly as it was.
+ *
+ * ## What it never does
+ *
+ * Delete a published item. Releasing the export's temporary is a separate act
+ * on a separate file, and a saved video belongs to the user from the moment it
+ * is published.
+ *
+ * @experimental
+ */
+/** Why a save did not happen. @experimental */
+declare class MediaSaveFailed extends Error {
+    /** Safe to display: never a path, a stack, or a platform message. */
+    readonly reason: string;
+    constructor(reason: string);
+}
+/** A save the user asked to stop. @experimental */
+declare class MediaSaveCancelled extends Error {
+    constructor();
+}
+/**
+ * Offer a saved video to the system share sheet.
+ *
+ * Only after a successful save, and only ever the durable `content:` uri. The
+ * cache path the export produced is app-private: a receiver could not open it,
+ * and handing one out is the mistake `FileUriExposedException` exists to catch.
+ *
+ * Sharing changes nothing. The same row is offered every time — no copy, no
+ * rename, no re-publish, and nothing released.
+ *
+ * Returns `false` when the device has nothing that accepts a video, which is an
+ * outcome rather than a failure: the saved video is untouched either way.
+ *
+ * @experimental
+ */
+declare function shareSavedMedia(uri: string): {
+    ok: boolean;
+    noTargets: boolean;
+    reason: string;
+};
+/** @experimental */
+declare function createMediaStoreSaver(): MediaSaver;
+/**
+ * Delete pending rows a killed process left behind.
+ *
+ * Worth calling once at startup. A pending row is invisible to the gallery and
+ * still occupies storage, so nothing will ever prompt a user to clean one up.
+ *
+ * Scoped to this app's own still-pending rows under its own folder: a published
+ * item is never a candidate, and neither is anything another app wrote.
+ *
+ * @experimental
+ */
+declare function sweepPendingMediaSaves(): {
+    swept: number;
+    inspected: number;
+    /** Pending rows seen and deliberately left alone. */
+    skipped: number;
+};
+
+/**
+ * Install the staging primitive, once.
+ *
+ * Idempotent, and safe to call before an export rather than at module load: a
+ * host that never exports an overlay never pays for it.
+ */
+declare function installOverlayStaging(): boolean;
+/** What a sink hands back, plus the token that owns it. @experimental */
+interface StagedRaster {
+    file: string;
+    byteLength: number;
+    checksum: number;
+}
+/**
+ * A sink, and the tokens it is holding.
+ *
+ * The token list is the whole point of the wrapper: the structural
+ * `OverlayRasterSink` contract identifies a staged raster by its file, and a
+ * caller that released by path would be naming something it was never given
+ * authority over. Every release here goes through the token native issued.
+ *
+ * @experimental
+ */
+interface OverlayStagingSink {
+    stage(bytes: Uint8Array, meta: {
+        overlayId: string;
+        resourceId: string;
+        rasterWidth: number;
+        rasterHeight: number;
+    }): StagedRaster;
+    /** Discard one staged raster, by the file the descriptor carried. */
+    remove(file: string): void;
+    /** Discard everything this sink still holds. Idempotent. */
+    releaseAll(): number;
+    /** For assertions: created, released and still live. */
+    ledger(): {
+        created: number;
+        released: number;
+        live: number;
+    };
+}
+/**
+ * Remove sidecars a previous process left behind.
+ *
+ * Scoped by native to this module's own directory and file suffix, so it cannot
+ * take a cache file belonging to anything else. Returns how many it removed.
+ *
+ * @experimental
+ */
+declare function sweepOverlayStaging(): number;
+/** @experimental */
+declare function createOverlayStagingSink(): OverlayStagingSink;
+/**
+ * How long a synchronous stage blocks the JS thread, for a raster this size.
+ *
+ * Exists because the synchronous contract is only defensible if the number is
+ * small. If a maximum-size raster stalls long enough to drop frames in the
+ * export sheet, the answer is to make `OverlayRasterSink.stage` asynchronous —
+ * not to keep a blocking write behind a synchronous signature because it is
+ * convenient.
+ *
+ * @experimental
+ */
+declare function measureStagingStall(sink: OverlayStagingSink, width: number, height: number): {
+    ms: number;
+    bytes: number;
+};
+
+/**
+ * Reading what a picked audio file actually contains.
+ *
+ * The structural half of {@link AudioProbe} lives in `@pictor-sdk/video-core`,
+ * which has no decoder and never will; this is the adapter that can answer it.
+ * A host calls this once, before adding, and passes the result to
+ * `acceptAudioSource`.
+ *
+ * Nothing here identifies the file. The display name is the host's to carry —
+ * a picker URI embeds an id and sometimes a user's own folder names.
+ *
+ * @experimental
+ */
+/** A probe that failed, with a reason fit for a log rather than a person. @experimental */
+interface AudioProbeFailure {
+    ok: false;
+    /** Why the file could not be read. Diagnostic, not a user-facing sentence. */
+    reason: string;
+}
+/** What native learned, minus the display name only the host knows. @experimental */
+type AudioProbeResult = ({
+    ok: true;
+} & Omit<AudioProbe, 'displayName'>) | AudioProbeFailure;
+/**
+ * Open `uri` and report its audio.
+ *
+ * Never throws for an unreadable file: a pick that cannot be read is an answer,
+ * and a host that had to wrap this in a `try` would be handling a normal
+ * outcome as an exception. It throws only if the adapter is not installed,
+ * which is a wiring mistake rather than a file.
+ *
+ * @experimental
+ */
+declare function probeAudioSource(uri: string): AudioProbeResult;
+
+/**
+ * Media the app owns, copied out of wherever it was picked from.
+ *
+ * A picker returns a reference, not a file. A `content://` grant is scoped to
+ * the activity result that produced it; `copyToCacheDirectory` improves on that
+ * by writing into **cache**, which Android reclaims whenever it wants storage
+ * back. Either way a project persisted with a picker URI reopens with media
+ * that has quietly gone, and nothing says so until an export fails.
+ *
+ * So ingestion copies into `filesDir` and the project stores that. See
+ * `ManagedSources.kt` for why the name is the content hash and why nothing is
+ * ever deleted implicitly.
+ *
+ * @experimental
+ */
+/** Where a managed source lives, and what it is. @experimental */
+interface ManagedSource {
+    /** A `file://` URI in app-owned durable storage. Safe to persist. */
+    uri: string;
+    /** The content hash. Names the file; never derived from the user's filename. */
+    token: string;
+    byteLength: number;
+    sha256: string;
+    /**
+     * Whether this call brought the file into existence.
+     *
+     * False means the bytes were already stored and something else may be
+     * pointing at them — a caller unwinding its own work must not release a
+     * source it did not create.
+     */
+    created: boolean;
+}
+/** @experimental */
+interface ManagedSourceFailure {
+    ok: false;
+    /** Diagnostic. Never shown to a person: it may name a path. */
+    reason: string;
+}
+/** @experimental */
+type IngestResult = ({
+    ok: true;
+} & ManagedSource) | ManagedSourceFailure;
+/**
+ * Copy a picked source into durable, app-owned storage.
+ *
+ * Never throws for an unreadable source: a pick that cannot be copied is an
+ * answer. It throws only if the adapter is not installed.
+ *
+ * @experimental
+ */
+declare function ingestManagedSource(uri: string): IngestResult;
+/**
+ * Drop one managed source.
+ *
+ * For unwinding an ingestion whose item was never created. Not for Undo: an
+ * Undo that deleted the source would leave Redo restoring an item that points
+ * at nothing.
+ *
+ * @experimental
+ */
+declare function releaseManagedSource(token: string): boolean;
+/**
+ * Remove every managed source not named in `keepTokens`.
+ *
+ * The only thing that deletes media, and it is always given the full set of
+ * what the project still references. Also removes partials a killed process
+ * left behind.
+ *
+ * @experimental
+ */
+declare function sweepManagedSources(keepTokens: readonly string[]): {
+    removed: number;
+    kept: number;
+    partials: number;
+    /** Files that are not ours, counted so the accounting matches a listing. */
+    skipped: number;
+};
+/**
+ * Every filename in the managed directory, including partials and strays.
+ *
+ * Read-only accounting, so it is available in release for the same reason the
+ * ledgers are: it is how a sweep is proven rather than asserted.
+ * {@link managedSourceLedger} reports only well-formed sources, which cannot
+ * show what a sweep left behind.
+ *
+ * @experimental
+ */
+declare function managedSourceList(): {
+    name: string;
+    byteLength: number;
+}[];
+/**
+ * Gate-only: put a file in the managed directory with an exact name.
+ *
+ * Ingestion only ever produces well-formed, referenced sources, so the cases a
+ * sweep exists to handle — an orphan, a stale partial, a file that is not ours
+ * — cannot be reached through the normal API. Refused in a release build built
+ * without diagnostics.
+ *
+ * @experimental
+ */
+declare function seedManagedSourceForGate(name: string, bytes: number): boolean;
+/**
+ * Gate-only: sweep with a keep list handed over exactly as written.
+ *
+ * The production path serialises its own list, so an unparseable one can never
+ * reach native — which makes "an unreadable keep list deletes nothing"
+ * unprovable through it. Returns what native reported.
+ *
+ * @experimental
+ */
+declare function sweepManagedSourcesRawForGate(rawKeep: string): {
+    ok: boolean;
+    removed: number;
+    kept: number;
+    partials: number;
+    skipped: number;
+};
+/** What is stored, for assertions. Tokens and sizes, never names. @experimental */
+declare function managedSourceLedger(): {
+    count: number;
+    bytes: number;
+    items: {
+        token: string;
+        byteLength: number;
+    }[];
+};
+/**
+ * The token a managed URI names, or null if it is not one of ours.
+ *
+ * Lets a host collect the keep list for {@link sweepManagedSources} straight
+ * from a project's sources without storing a second index that could drift.
+ *
+ * @experimental
+ */
+declare function managedSourceToken(uri: string): string | null;
+
+/**
+ * The audio a preview plays.
+ *
+ * ## Preparation, not playback
+ *
+ * A preview mix is produced by the same code an export runs: every contributing
+ * source is decoded, re-timed by its clip's speed, ramped, summed and saturated
+ * once, then encoded. That takes real time proportional to the project, and no
+ * amount of naming it "preview" makes it realtime. A caller has to show that it
+ * is preparing and must not pretend otherwise.
+ *
+ * ## Why not mix in the player
+ *
+ * Because then there would be two definitions of what a project sounds like,
+ * and the one a person hears while editing would be the one that was never
+ * tested against an export. Gain, fades, trims, speed and overlap are decided
+ * by `compileAudioMixProgram` and executed by `AudioMixer` — here and in the
+ * exporter, from the same plan.
+ *
+ * ## Superseding
+ *
+ * One job at a time. A newer request cancels the one in flight, which unwinds
+ * at its next checkpoint, deletes its partial and reports `superseded`. A
+ * superseded result is not a failure and must never be published: it is the
+ * answer to a question nobody is asking any more.
+ *
+ * @experimental
+ */
+/** A prepared mix. @experimental */
+interface PreparedMix {
+    ok: true;
+    /** A `file://` URI in app-private storage. */
+    uri: string;
+    /** The content key: mix program, sources and mixer configuration. */
+    key: string;
+    /** True when nothing had to be encoded — the file was already there. */
+    cached: boolean;
+    byteLength: number;
+    /**
+     * Where the time went, when it was actually prepared.
+     *
+     * Milliseconds per stage and frames per source. Absent for a cached mix,
+     * which did no work to attribute.
+     */
+    profile?: {
+        stageMs: Record<string, number>;
+        counts: Record<string, number>;
+        sources: Record<string, Record<string, number>>;
+    };
+}
+/** @experimental */
+type PreviewMixResult = PreparedMix
+/** A newer request replaced this one. Not a failure; never publish it. */
+ | {
+    ok: false;
+    superseded: true;
+    key: string;
+}
+/** It ran and failed. The reason is diagnostic and may name a path. */
+ | {
+    ok: false;
+    superseded?: false;
+    key?: string;
+    reason: string;
+};
+/**
+ * Prepare the mix for a compiled program, or hand back the one already
+ * prepared.
+ *
+ * `urisJson` maps span id to a resolved, durable source URI — the same
+ * resolution an export performs, so the two agree about which file a span
+ * means.
+ *
+ * Never rejects: a mix that cannot be produced is an outcome.
+ *
+ * @experimental
+ */
+declare function preparePreviewMix(jobId: string, programJson: string, urisJson: string): Promise<PreviewMixResult>;
+/**
+ * Stop whatever is preparing.
+ *
+ * Safe to call when nothing is: cancelling twice, or cancelling after a job
+ * already finished, is how a caller's teardown paths overlap on purpose.
+ *
+ * @experimental
+ */
+declare function cancelPreviewMix(): void;
+/**
+ * The key a program would produce, without preparing it.
+ *
+ * Lets a caller ask "is this the mix I am already playing?" before starting a
+ * job — which is what stops a selection change, or any edit that does not
+ * change the sound, from rebuilding anything.
+ *
+ * @experimental
+ */
+declare function previewMixKey(programJson: string, urisJson: string): string;
+/** Drop one prepared mix. @experimental */
+declare function releasePreviewMix(key: string): boolean;
+/**
+ * Keep only these mixes; remove the rest and every partial.
+ *
+ * The bound on the cache. A sweep that cannot read its own result removes
+ * nothing, rather than assuming the directory should be empty.
+ *
+ * @experimental
+ */
+declare function sweepPreviewMixes(keepKeys: readonly string[]): {
+    removed: number;
+    kept: number;
+    partials: number;
+    skipped: number;
+};
+/** What is prepared, for assertions. @experimental */
+declare function previewMixLedger(): {
+    count: number;
+    bytes: number;
+    items: {
+        name: string;
+        byteLength: number;
+    }[];
+};
+
+/**
+ * Deciding what a preview should be doing about audio.
+ *
+ * Pure, and separate from the hook that acts on it, because every rule worth
+ * getting right here is a rule about state rather than about React: whether a
+ * project needs a mix at all, whether the mix on hand is the one the document
+ * describes, whether a result that just arrived is still wanted, and whether
+ * two players have drifted far enough to be worth correcting.
+ *
+ * ## Two sources of sound, never both
+ *
+ * Without music, the video player's own audio is the preview and nothing here
+ * applies. With music, the mix covers the *whole* timeline — including the
+ * audio of the clips themselves — so playing the clips' audio as well would
+ * play everything twice. There is no state in which both are audible, and the
+ * transition between them is the thing this file exists to sequence.
+ *
+ * @experimental
+ */
+/** What a preview's audio is doing. @experimental */
+type PreviewAudioStatus = 
+/** No music in the project. The video player's own audio is the preview. */
+'source'
+/** Music exists and the mix for *this* document is not ready. */
+ | 'preparing'
+/** The mix on hand matches the document. Source audio is muted. */
+ | 'ready'
+/** The mix could not be prepared. Nothing is played rather than the wrong thing. */
+ | 'failed';
+/** @experimental */
+interface PreviewAudioDecision {
+    status: PreviewAudioStatus;
+    /** The key the document wants. Empty when there is no music. */
+    wantedKey: string;
+    /** Whether a job should be started for `wantedKey`. */
+    shouldPrepare: boolean;
+    /** Whether the video player's own audio must be silenced. */
+    muteSourceAudio: boolean;
+    /** Whether playback may run right now. */
+    canPlay: boolean;
+}
+/** @experimental */
+interface PreviewAudioInputs {
+    /** The key the current document compiles to, or '' when it has no music. */
+    wantedKey: string;
+    /** The key of the mix already prepared and loaded, if any. */
+    readyKey: string | null;
+    /** The key a job is currently preparing, if any. */
+    preparingKey: string | null;
+    /** The key whose preparation failed, if any. */
+    failedKey: string | null;
+}
+/**
+ * Whether a project needs a mixed preview at all.
+ *
+ * True when anything in the compiled program is audible *and comes from an
+ * audio item* — a project whose only sound is clip audio does not need a mix,
+ * because the video player already plays exactly that and does it in realtime.
+ *
+ * @experimental
+ */
+declare function previewAudioNeeded(project: VideoProject): boolean;
+/**
+ * What to do, given what is wanted and what is on hand.
+ *
+ * @experimental
+ */
+declare function decidePreviewAudio(inputs: PreviewAudioInputs): PreviewAudioDecision;
+/** The key a project's audio compiles to, given resolved sources. @experimental */
+declare function previewProgramJson(project: VideoProject): string;
+/**
+ * The default tolerance.
+ *
+ * The drift this used to chase is prevented rather than corrected: `PreviewSync`
+ * holds both transports through a stall and releases them aligned, which is
+ * where all of it came from. A correcting seek during playback costs 200-340 ms
+ * on a Pixel 7 — the same size as the error it was chasing, so it oscillated
+ * between +264 ms and -198 ms — and realignment now happens while everything is
+ * held, where a seek has nothing to chase.
+ *
+ * So this is back to the tolerance the gates were written against. It is a
+ * backstop for something nobody has seen, not the mechanism.
+ *
+ * @experimental
+ */
+declare const PREVIEW_DRIFT_TOLERANCE_US = 60000;
+
+/**
+ * The paired player trace.
+ *
+ * Both players sampled on one monotonic clock, buffered natively and drained
+ * afterwards. It exists because the question — do the picture and the sound
+ * agree — needs samples closer together than a bridge hop, and far closer than
+ * `uiautomator` can time.
+ *
+ * Diagnostics-only in native: a build without them refuses, and even with them
+ * it does nothing until armed.
+ *
+ * @experimental
+ */
+/** One sample or event. @experimental */
+interface TraceEvent {
+    seq: number;
+    /** `System.nanoTime()`, the clock both players publish on. */
+    atNs: number;
+    type: string;
+    v: Record<string, unknown>;
+}
+/** @experimental */
+interface TracePage {
+    ok: boolean;
+    /**
+     * Whether the *run* is trustworthy.
+     *
+     * False when the sampler threw. The events before the fault are real and the
+     * silence after it is not evidence of anything — a summary computed over a
+     * truncated run reads exactly like one computed over a complete one.
+     */
+    valid: boolean;
+    /** Why it stopped being trustworthy, or null. */
+    fault: string | null;
+    events: TraceEvent[];
+    nextSeq: number;
+    total: number;
+    /** Events overwritten before they could be read. Non-zero means a hole. */
+    dropped: number;
+}
+/** Arm the trace and start sampling. @experimental */
+declare function armPreviewTrace(on: boolean, intervalMs?: number): boolean;
+/** Label the trace, so a harness can find its own cases. @experimental */
+declare function markPreviewTrace(label: string): void;
+/**
+ * Drain a page of events.
+ *
+ * Paged rather than whole: a full trace is far past what a single log line
+ * survives, and truncation in the middle is the failure this is meant to
+ * detect rather than cause.
+ *
+ * @experimental
+ */
+declare function drainPreviewTrace(fromSeq: number, limit?: number): TracePage;
+/**
+ * Every event, drained in pages until the buffer is exhausted.
+ *
+ * @experimental
+ */
+declare function drainAllPreviewTrace(limit?: number): TracePage;
+/**
+ * The offset between the players, summarised over the samples that mattered.
+ *
+ * Only samples where **both** players were playing are counted: a paused
+ * player's position does not advance, so including it would average in a
+ * divergence that is not drift.
+ *
+ * @experimental
+ */
+declare function summariseOffsets(events: readonly TraceEvent[]): {
+    samples: number;
+    playingSamples: number;
+    /** Samples whose presented frame was the same one as the tick before. */
+    staleFrameSamples: number;
+    /**
+     * Samples with no presented frame at all.
+     *
+     * `FrameClock.latest` is null until the renderer consumes something, and
+     * again after a generation bump. Counting these as "stale" hid them: a run
+     * reported 56 stale of 506 while every sampled point in the same run had no
+     * record whatsoever, because an absent field is not a false one.
+     */
+    absentFrameSamples: number;
+    /** Samples with a frame that had advanced since the previous tick. */
+    freshFrameSamples: number;
+    /** The longest run of consecutive stale samples. */
+    longestStaleRun: number;
+    minUs: number;
+    maxUs: number;
+    meanUs: number;
+    worstAbsUs: number;
+};
+/**
+ * What the stall coordinator has done.
+ *
+ * Holds, releases and realigning seeks. A gate asserts that seams produced
+ * holds and that every hold resolved — a coordinator that never engaged and one
+ * that engaged and never released look identical in an offset summary.
+ *
+ * @experimental
+ */
+declare function previewSyncCounters(): Record<string, unknown>;
+/**
+ * Stop playback for a host reason — background, picker, unmount.
+ *
+ * Overrides a resume the coordinator is holding, so playback cannot restart at
+ * a moment nobody asked for.
+ *
+ * @experimental
+ */
+declare function stopPreviewForHost(reason: string): void;
+/**
+ * Frames offered, queued and drawn.
+ *
+ * The instrument-disruption check reads this with tracing off and again with it
+ * on: if the drawn count advances at the same rate either way, the trace is not
+ * changing what it measures. Three defects in this area were the measurement
+ * rather than the product, so that check comes before the numbers do.
+ *
+ * @experimental
+ */
+declare function previewFramePipeline(): Record<string, number>;
+/** Which parts of the music preview exist. All true in production. @experimental */
+interface PreviewParts {
+    /** Whether the drift check may act. Off measures without correcting. */
+    driftCorrection: boolean;
+    loadPlayer: boolean;
+    startMix: boolean;
+    positionPump: boolean;
+    coordinator: boolean;
+}
+/**
+ * Turn parts of the music preview off, to bisect a failure.
+ *
+ * Gate-only in native. Guessing between a second player, its position pump, the
+ * stall coordinator and the mix actually playing is how the previous attempts
+ * in this area became tuning; this is how one of them gets ruled out at a time.
+ *
+ * @experimental
+ */
+declare function setPreviewParts(parts: Partial<PreviewParts>): PreviewParts | null;
+/** @experimental */
+declare function previewParts(): PreviewParts | null;
+/**
+ * Silence the video player's own audio.
+ *
+ * Exposed because a bisect control needs the *same* mute in every
+ * configuration: without it, the video-only row would be the only one with
+ * audible clip audio, and any difference against the others would be
+ * confounded by a whole track the rest do not have.
+ *
+ * @experimental
+ */
+declare function muteSourceAudio(muted: boolean): void;
+/**
+ * Every codec mix preparation owns, and what became of it.
+ *
+ * A `release()` that was called is not a release that finished, so both ends
+ * are recorded along with the exception path. The preview video decoder is not
+ * here: it belongs to the player and outlives any job, and counting it would
+ * make "live after publication" always true.
+ *
+ * @experimental
+ */
+declare function previewCodecLedger(): {
+    live: number;
+    peakLive: number;
+    total: number;
+    entries: Record<string, unknown>[];
+};
+
+/**
+ * The offset, segmented by the marks a gate put in the run.
+ *
+ * ## Why a whole-run summary is not enough
+ *
+ * `summariseOffsets` answers "how bad did it get", and a gate needs "where".
+ * Measured on a Pixel 7, a run whose worst excursion was 266 ms spent every
+ * moment between its transitions inside ±40 ms: the whole-run worst described
+ * three settling transients and nothing else, and a single number cannot tell
+ * that from a steady 266 ms error. They are not the same defect and they do not
+ * have the same fix.
+ *
+ * So a run is cut at its marks, and each segment is summarised on its own. The
+ * gate verdict is still the run's worst — this localises a failure, it does not
+ * soften one.
+ *
+ * ## Fresh and stale are reported, never traded
+ *
+ * A stale presented frame is what a person actually sees, so its offset is real
+ * and is counted in `worstAbsUs`. But a stale frame's offset grows purely
+ * because audio advanced while the picture did not, which is a different fault
+ * from two clocks disagreeing — so `freshWorstAbsUs` is reported beside it
+ * rather than instead of it. Neither is allowed to stand alone: quoting only
+ * the fresh figure is how a run with a nine-second frozen picture passes a
+ * synchronisation gate.
+ *
+ * @experimental
+ */
+interface PhaseSummary {
+    /** The mark that opened this segment, or `'start'` before the first one. */
+    label: string;
+    index: number;
+    /** Samples in the segment, whatever their state. */
+    samples: number;
+    /** Samples with both players playing — the only ones an offset means anything for. */
+    playingSamples: number;
+    /** Of those, the ones whose presented frame had advanced. */
+    freshPlayingSamples: number;
+    stalePlayingSamples: number;
+    /** The longest unbroken run of stale samples, in samples. */
+    longestStaleRun: number;
+    minUs: number;
+    maxUs: number;
+    meanUs: number;
+    /** Worst absolute offset over every playing sample, stale included. */
+    worstAbsUs: number;
+    /** Worst over fresh samples only. Reported beside `worstAbsUs`, never instead. */
+    freshWorstAbsUs: number;
+    /** Playing samples outside the tolerance. */
+    overToleranceSamples: number;
+    /**
+     * How long the segment took to come inside tolerance and stay there.
+     *
+     * `-1` when it never did, which is the difference between a transient and a
+     * failure that happens to start at a transition. Measured from the segment's
+     * first playing sample, so it is a settling time rather than a wall clock.
+     */
+    settledAfterUs: number;
+}
+/** @experimental */
+interface PhaseReport {
+    toleranceUs: number;
+    phases: PhaseSummary[];
+    /** The run's worst, over every phase. This is the gate. */
+    worstAbsUs: number;
+    freshWorstAbsUs: number;
+    overToleranceSamples: number;
+    /** Whether every playing sample in the run was inside tolerance. */
+    pass: boolean;
+}
+/**
+ * The prefix a gate's own marks carry.
+ *
+ * Every mark is recorded as a `mark` event carrying its label, and the trace is
+ * also full of system events — holds, releases, drift corrections, transport
+ * transitions. Cutting on "not a sample" would start a new phase at every one
+ * of those, and cutting on every mark would let an ad-hoc label reshape a gate's
+ * phases. So only marks whose label carries this prefix cut the run.
+ *
+ * @experimental
+ */
+declare const PHASE_MARK_PREFIX = "phase:";
+/**
+ * Summarise a drained run, cut at its mark events.
+ *
+ * @experimental
+ */
+declare function summarisePhases(events: readonly TraceEvent[], toleranceUs: number): PhaseReport;
+
+/**
+ * The shared-clock playback spike, from the host's side.
+ *
+ * ## What it is testing
+ *
+ * Whether one playback-clock authority can drive the picture and a prepared,
+ * project-wide mix at once. The two-player preview cannot meet the 60 ms gate
+ * and the reasons are structural: anchors polled at 50 ms make a single
+ * comparison uncertain by up to ±56 ms against a 60 ms tolerance, the
+ * correction loop runs at 500 ms while each corrective seek costs 200-400 ms,
+ * and at a seam the project clock divides by a speed the player applies about
+ * 450 ms later.
+ *
+ * ## Why the spec is built here
+ *
+ * `playlistOf` is the shared compiler, and it already decides every number this
+ * needs: the source bounds a clip plays between, its speed, and where the
+ * window sits on the project timeline. Passing its output through verbatim is
+ * what keeps the adapter free of a second interpretation of the document —
+ * native maps items onto media items and nothing else.
+ *
+ * Diagnostics-only, and it says nothing about live PCM gain or fades: it plays
+ * the same prepared mix file the current preview plays.
+ *
+ * @experimental
+ */
+/** One clip, as the compiler described it. @experimental */
+interface CompositionSpikeItem {
+    uri: string;
+    /** Clipping bounds in **source** time, which is where speed is applied. */
+    startUs: number;
+    endUs: number;
+    speed: number;
+}
+/** @experimental */
+interface CompositionSpikeSpec {
+    /**
+     * Hold the shared clock at each clip boundary.
+     *
+     * Off, and measured off for a reason: with `playWhenReady` false
+     * `CompositionPlayer` does not advance across an item boundary, so the
+     * incoming frame the hold waits for is never produced and the hold runs to
+     * its bound. Holding the clock and preparing the next stream are mutually
+     * exclusive on this player.
+     */
+    seamHold?: boolean;
+    /**
+     * Prepare the incoming item with an explicit seek while the clock is held.
+     *
+     * Only meaningful with `seamHold`. Pausing natural traversal and seeking to a
+     * target are different operations: the seek path resets the renderers, which
+     * is what makes a paused player produce a frame, and is the same path the
+     * existing seek readiness already passes on.
+     */
+    seamSeek?: boolean;
+    items: CompositionSpikeItem[];
+    /** The prepared mix. Empty plays the picture with no sound at all. */
+    mixUri: string;
+    /**
+     * The mix's duration.
+     *
+     * Required whenever `mixUri` is set: the player computes each sequence's
+     * duration before playing, and an audio-only item cannot report one itself.
+     */
+    mixDurationUs: number;
+    width: number;
+    height: number;
+    /**
+     * The request this attachment belongs to.
+     *
+     * Claimed before preparation starts. Native refuses an attachment whose id is
+     * older than the newest claim, so a preparation that finishes late cannot put
+     * a stale mix on screen for even one frame. Omit for runs with no race.
+     */
+    requestId?: number;
+}
+/** @experimental */
+interface CompositionSpikeState {
+    ok: boolean;
+    attached: boolean;
+    built: number;
+    released: number;
+    error: string | null;
+    /**
+     * Readiness latency, reported apart from synchronisation.
+     *
+     * A preparation pause is a latency figure and an A/V offset is an error;
+     * averaging one into the other is how a slow start reads as drift.
+     */
+    startupMs: number;
+    seekMs: number;
+    /** What the person asked for, independent of whether the transport is running. */
+    intentPlaying?: boolean;
+    /** A hold waiting for the first frame of the current epoch. */
+    releasePending?: boolean;
+    releases?: number;
+    readinessTimeouts?: number;
+    readinessFailure?: string | null;
+    /** How long the last hold lasted before playback was released. */
+    holdMs?: number;
+    /**
+     * Wall-clock milliseconds spent holding the clock at each clip boundary.
+     *
+     * Listed, never averaged. Each entry is a pause the person sees: the decoder
+     * is torn down and rebuilt at a boundary and the clock waits rather than the
+     * picture falling behind it. **This is not seamless playback**, which is why
+     * it is reported apart from every synchronisation figure.
+     */
+    seamHoldMs?: number[];
+    /** Holds that reached their bound without a correctly associated frame. */
+    seamHoldTimeouts?: number;
+    seamHoldActive?: boolean;
+    atNs?: number;
+    positionUs?: number;
+    playing?: boolean;
+    playbackState?: number;
+    durationUs?: number;
+    presentedUs?: number | null;
+    /** How old the presented frame was when it was read, so a stalled sample can be excluded. */
+    presentedAgeNs?: number;
+    /** How long the paired read itself took. Bounds the pairing error. */
+    readSpanNs?: number;
+    /** How stale the pairing was when it was read out. */
+    pairingAgeNs?: number;
+}
+/**
+ * Build the spike's spec from a project and a prepared mix.
+ *
+ * Unsupported clips are not silently dropped: `playlistOf` reports them, and a
+ * spec built from a playlist missing a window would put every later seam in the
+ * wrong place — which is exactly the class of error this spike exists to
+ * measure.
+ *
+ * @experimental
+ */
+declare function compositionSpikeSpec(project: VideoProject, mix: {
+    uri: string;
+    durationUs: number;
+}, resolve: (source: {
+    kind: string;
+    uri?: string;
+}) => string | null): {
+    spec: CompositionSpikeSpec;
+    unsupported: string[];
+};
+/** Claim the next request id, before preparing. @experimental */
+declare function spikeClaim(): number;
+/** @experimental */
+declare function spikeStart(spec: CompositionSpikeSpec): Record<string, unknown>;
+/** @experimental */
+declare function spikePlay(): Record<string, unknown>;
+/** @experimental */
+declare function spikePause(): Record<string, unknown>;
+/** @experimental */
+declare function spikeSeek(positionUs: number): Record<string, unknown>;
+/** @experimental */
+declare function spikeState(): CompositionSpikeState;
+/**
+ * One retained sample, unpacked.
+ *
+ * Packed across the boundary because a gate reads thousands of these, and named
+ * here because a gate that indexes into an array of eighteen longs is one
+ * transposition away from a confident wrong answer.
+ *
+ * @experimental
+ */
+interface SpikeSample {
+    seq: number;
+    atNs: number;
+    positionUs: number;
+    playing: boolean;
+    ready: boolean;
+    epoch: number;
+    sinceEpochNs: number;
+    frameId: number;
+    frameGeneration: number;
+    frameWindow: number;
+    framePtsUs: number;
+    /**
+     * When Media3's renderer said this frame was about to go to the surface.
+     *
+     * The earliest boundary observable here, and the one that separates the
+     * owners of a gap: nothing before this is the decoder or the item's
+     * preparation, this to {@link SpikeSample.frameAvailableNs} is the video
+     * graph, and that to {@link SpikeSample.frameConsumedNs} is this consumer.
+     */
+    frameMetadataNs: number;
+    /** The time Media3 *asked* the surface to present at. An intention. */
+    frameReleaseNs: number;
+    /** The time the consumer latched it. The last boundary observable here. */
+    frameConsumedNs: number;
+    frameAvailableNs: number;
+    coalesced: number;
+    offered: number;
+    available: number;
+    taken: number;
+    readSpanNs: number;
+}
+/** @experimental */
+declare function spikeDrain(fromSeq: number, limit?: number): {
+    ok: boolean;
+    rows: SpikeSample[];
+    nextSeq: number;
+    total: number;
+    dropped: number;
+};
+/** @experimental */
+declare function spikeRelease(): Record<string, unknown>;
+
+/**
+ * Where a shared-clock run left the tolerance, and why.
+ *
+ * ## What is being compared
+ *
+ * The audio clock's position and the presented frame's timestamp, brought to
+ * one instant. The frame was latched at `frameConsumedNs`; the position was
+ * read at `atNs`. Rolling the position back to the latch is what puts them on
+ * the same monotonic instant — the composition runs at project rate 1x, so the
+ * roll-back is the elapsed time itself.
+ *
+ * ## Which boundary this observes
+ *
+ * The **latch**, not the display. `frameConsumedNs` is when the consumer called
+ * `updateTexImage`; `frameReleaseNs` is the time Media3 *asked* the surface to
+ * present at, which is an intention and not an acknowledgement. Actual scanout
+ * happens one compositor pass later and is not observed anywhere in this path.
+ * So an offset here is "audio against latched picture", and the display adds a
+ * further unmeasured delay common to every sample.
+ *
+ * ## Uncertainty is stated, never subtracted
+ *
+ * Comparing a 30 fps frame's timestamp against a continuous clock carries an
+ * irreducible ±16.7 ms, and the paired read adds a few more. That is reported
+ * beside the verdict. It is not deducted from an excursion to bring it under
+ * the line: a 95 ms excursion is not a 78 ms excursion because the instrument
+ * is imperfect.
+ *
+ * @experimental
+ */
+/** @experimental */
+declare const SPIKE_TOLERANCE_US = 60000;
+/**
+ * Why one sample left the tolerance.
+ *
+ * Ordered by precedence, because more than one can be true and the first is the
+ * one that explains the sample: a frame from before a seek is cross-epoch
+ * whatever else is also true of it.
+ *
+ * @experimental
+ */
+type ExcursionCause = 
+/**
+ * The latched frame predates the moment playback was released.
+ *
+ * Not a filter and not a drift. The readiness gate releases on a frame whose
+ * *position* matches the epoch, and that frame may have been latched long
+ * before — measured at 13.9 s, the whole interval between attaching the
+ * composition and the person pressing play. The picture was right; the
+ * frame's wall-clock age simply includes a pause, and charging that to
+ * synchronisation measures the pause.
+ *
+ * Reported rather than excluded, because the size of it is the size of the
+ * interval in which the first sample after a release is not yet a
+ * synchronisation reading.
+ */
+'pre-release-frame'
+/** The frame belongs to a different transition epoch or frame generation. */
+ | 'cross-epoch'
+/** The frame was latched long enough ago that it is not a current reading. */
+ | 'stale-pairing'
+/** The first frames after a seek or after readiness, before the picture caught up. */
+ | 'first-frame-after-seek'
+/** The frame was latched well after the time it was asked to be presented at. */
+ | 'delayed-presentation'
+/** The audio clock moved discontinuously between adjacent samples. */
+ | 'audio-discontinuity'
+/** The mapped project time disagrees with the frame's own window and PTS. */
+ | 'mapping'
+/** None of the above fitted. Deliberately not folded into a neighbour. */
+ | 'unexplained';
+/** @experimental */
+interface Excursion {
+    seq: number;
+    /** Against the latch: observed, and earlier than display. */
+    offsetUs: number;
+    /** Against the time the frame was asked to appear. An intention. */
+    offsetAtIntendedUs: number;
+    cause: ExcursionCause;
+    epoch: number;
+    sinceEpochMs: number;
+    frameWindow: number;
+    framePtsUs: number;
+    /** Latched minus asked-for. Large means the picture arrived late. */
+    latchLagUs: number;
+    /** How old the latched frame was when the position was read. */
+    frameAgeUs: number;
+    /** The audio clock's step from the previous sample, in microseconds. */
+    positionStepUs: number;
+    /** The wall-clock step from the previous sample. */
+    wallStepUs: number;
+}
+/** @experimental */
+interface ExcursionReport {
+    toleranceUs: number;
+    /** Samples where playback was declared active. Only these are judged. */
+    activeSamples: number;
+    /** Samples before readiness, exposed rather than dropped. */
+    preparingSamples: number;
+    excursions: Excursion[];
+    byCause: Record<string, number>;
+    /**
+     * Samples still showing a frame latched before the release.
+     *
+     * Reported apart, and *retained* in the acceptance set: they are real
+     * playback, and if the picture never catches up they are the only thing that
+     * says so.
+     */
+    preReleaseSamples: number;
+    preReleaseWorstUs: number;
+    worstAbsUs: number;
+    /** The same run judged at the intended-presentation boundary. */
+    worstAtIntendedUs: number;
+    overAtIntended: number;
+    passAtIntended: boolean;
+    /** Mean latch-minus-intended over the excursions. Negative means early. */
+    meanLatchLagUs: number;
+    pass: boolean;
+    uncertainty: {
+        /** Half a frame interval at the measured rate. Irreducible. */
+        frameQuantumUs: number;
+        /** The widest paired read in the run. */
+        readSpanUs: number;
+        positionQuantumUs: number;
+    };
+}
+/**
+ * The offset at each observable boundary.
+ *
+ * They are not the same instant and the difference is not noise. Measured on a
+ * Pixel 7, the consumer latches a buffer about 34 ms *before* the time Media3
+ * asked the surface to present it — `releaseOutputBuffer(index, releaseTimeNs)`
+ * queues immediately with a desired present time in the future, and the
+ * SurfaceTexture consumer takes it as soon as it is queued.
+ *
+ * So `atLatch` compares the audio clock against a frame that is in the texture
+ * but has not been displayed, and is systematically early by that gap;
+ * `atIntended` compares it against when that frame was *meant* to appear, which
+ * is the best available estimate of what a viewer experiences and is still an
+ * intention rather than an acknowledgement. The true display instant lies at or
+ * after `atIntended`, and nothing in this process observes it.
+ *
+ * Both are returned because choosing one silently is how a boundary decision
+ * becomes a verdict.
+ *
+ * @experimental
+ */
+declare function offsetAt(sample: SpikeSample, 
+/**
+ * When the current playing interval was released, if known.
+ *
+ * A frame latched while paused carries the pause in its age. Charging that to
+ * synchronisation measured a 13.9 second "error" for a picture that was
+ * showing exactly the right position. Clamping the reference to the release
+ * instant charges only the time playback has actually been running — so at
+ * release the offset is (audio position - displayed PTS), and it grows from
+ * there if the audio advances while the picture stays put.
+ *
+ * That growth is the point: this corrects the baseline without removing
+ * coverage. A frame that is never replaced still accrues the offset it
+ * deserves.
+ */
+releaseAtNs?: number): {
+    atLatch: number;
+    atIntended: number;
+};
+/**
+ * Classify a run's over-tolerance samples.
+ *
+ * `frameIntervalUs` is the source's nominal frame interval; half of it is the
+ * irreducible quantisation of comparing a discrete frame against a continuous
+ * clock.
+ *
+ * @experimental
+ */
+declare function classifyExcursions(samples: readonly SpikeSample[], options?: {
+    toleranceUs?: number;
+    frameIntervalUs?: number;
+}): ExcursionReport;
+/**
+ * The samples around one excursion, for looking at rather than inferring from.
+ *
+ * @experimental
+ */
+declare function windowAround(samples: readonly SpikeSample[], seq: number, spanUs?: number): SpikeSample[];
+
+/**
+ * Score the picture where it is handed to composition.
+ *
+ * ## The boundary, stated
+ *
+ * **Submission**, not scanout. A frame is scored at the instant composition
+ * begins consuming it; the compositor presents it some time later and nothing
+ * in this process observes that. The delay is common to every frame, so it
+ * shifts the whole series rather than spreading it — but it is not measured
+ * here and is not subtracted from anything.
+ *
+ * ## Why an interval rather than a point
+ *
+ * A frame is not a sample of one instant; it is the correct picture for a span
+ * of project time. Comparing a continuous audio clock against a single
+ * timestamp charges the frame's own duration to synchronisation, which is why
+ * the 0.5x clip — whose frames are correct for 66.7 ms each — looked worse than
+ * the 1x clip at identical quality.
+ *
+ * So a submitted frame carries `[ptsUs, ptsUs + intervalUs)`, and the error is
+ * how far outside that span the audio clock sits. Zero inside, and the distance
+ * to the nearer edge outside. The interval comes from the measured cadence,
+ * which for a clip of speed `s` and source interval `i` is `i / s` — 33.3 ms at
+ * 1x, 66.7 ms at 0.5x.
+ *
+ * @experimental
+ */
+/** One submission, as the consumer recorded it. @experimental */
+interface SubmissionRecord {
+    frameId: number;
+    epoch: number;
+    ptsUs: number;
+    intervalUs: number;
+    submittedNs: number;
+    /** What the texture reported holding at acquisition. */
+    texturePtsUs: number;
+    /** Which ring slot carried it. */
+    slot: number;
+    occupancy: number;
+    /**
+     * The frame index read out of the slot's pixels when it was acquired.
+     *
+     * -1 when the probe was off or the band could not be read; `markerFailure`
+     * says which.
+     */
+    acquiredMarker: number;
+    /** The frame index read out of the picture actually handed to composition. */
+    submittedMarker: number;
+    /** Empty when the band was read; otherwise why it was not. */
+    markerFailure: string;
+    /**
+     * The picture's whole life, so one row can be attributed.
+     *
+     * When it was acquired, when it was due for presentation, when it was
+     * promoted. Without these, a late submission cannot be separated into a late
+     * arrival, a long wait for its due time, and a slow promotion.
+     */
+    acquiredNs: number;
+    dueNs: number;
+    promotedNs: number;
+    /**
+     * Rendering error against the frame the submitted band names: background
+     * level in 0..255, bar position in 0..1 of height. -1 when not measured.
+     */
+    levelDelta: number;
+    barDelta: number;
+}
+/** @experimental */
+interface ScoredSubmission {
+    frameId: number;
+    ptsUs: number;
+    intervalUs: number;
+    submittedNs: number;
+    /** The audio clock at the submission instant, on the same monotonic timeline. */
+    audioUs: number;
+    /** 0 inside the interval; otherwise the distance to the nearer edge. */
+    errorUs: number;
+    /** Positive when the sound is past the frame's span — the picture is behind. */
+    signedUs: number;
+    occupancy: number;
+}
+/** @experimental */
+interface SubmissionReport {
+    toleranceUs: number;
+    scored: number;
+    /** Submissions with no audio sample close enough to pair with. */
+    unpaired: number;
+    excursions: ScoredSubmission[];
+    worstErrorUs: number;
+    pass: boolean;
+    /**
+     * What this run established, as three outcomes.
+     *
+     * A score computed from nothing is not a pass. Zero scored submissions means
+     * the run did not observe playback, and that has to be distinguishable from
+     * a run that observed it and found it clean.
+     */
+    verdict: 'pass' | 'fail' | 'invalid';
+    verdictReason: string;
+    /** Gaps between consecutive submitted timestamps: the delivered cadence. */
+    cadenceUs: {
+        median: number;
+        min: number;
+        max: number;
+        samples: number;
+    };
+    /**
+     * Wall-clock gaps between consecutive submissions.
+     *
+     * The tail is the point: a median at the output interval says nothing about
+     * the frame that took four times as long, and that frame is the one somebody
+     * sees. Taken from `submittedNs`, which is the instant composition began
+     * consuming each picture.
+     */
+    frameTimeUs: {
+        p50: number;
+        p95: number;
+        p99: number;
+        max: number;
+        samples: number;
+    };
+    peakOccupancy: number;
+}
+/** @experimental */
+declare function scoreSubmissions(submissions: readonly SubmissionRecord[], samples: readonly SpikeSample[], options?: {
+    toleranceUs?: number;
+    pairWindowNs?: number;
+}): SubmissionReport;
+/** One submission, with its whole life and the clock it was scored against. @experimental */
+interface TraceRow {
+    frameId: number;
+    /** Offsets in ms from the window's first row, so the numbers are readable. */
+    acquiredMs: number;
+    dueMs: number;
+    promotedMs: number;
+    submittedMs: number;
+    /**
+     * Acquisition to due, due to promotion, promotion to submission, in us.
+     *
+     * A negative `waitUs` means the presentation time had already passed when the
+     * frame was acquired — it was late before the ring saw it.
+     */
+    waitUs: number;
+    promoteUs: number;
+    submitUs: number;
+    ptsUs: number;
+    audioUs: number;
+    errorUs: number;
+    slot: number;
+    occupancy: number;
+    marker: number;
+}
+/** @experimental */
+interface SubmissionTrace {
+    /** The frame the window is centred on. */
+    frameId: number;
+    rows: TraceRow[];
+    /**
+     * Where the centre frame's budget went, as the largest single interval.
+     *
+     * `arrival` when it was acquired late, `due` when it sat waiting for its
+     * presentation time, `promotion` when it was due and not chosen, `submission`
+     * when promotion and submission diverged. Empty when the row is incomplete.
+     */
+    spentOn: 'arrival' | 'due' | 'promotion' | 'submission' | 'unknown';
+    /** The dominant leg's size, so a label cannot imply a magnitude it lacks. */
+    spentUs: number;
+    /** True when the window could not be built from complete records. */
+    invalid: boolean;
+    reason: string;
+}
+/**
+ * The life of one submission and its neighbours.
+ *
+ * Built for attribution, not for scoring: a submission excursion says a picture
+ * was wrong at an instant, and this says where its time went. Acquisition, due
+ * time, promotion and submission are four stamps on one frame, and the largest
+ * gap between consecutive ones is the interval to investigate.
+ *
+ * Incomplete rows are reported rather than dropped. A ring buffer that wrapped,
+ * a record written before the ring carried these stamps, or a frame that never
+ * reached submission all produce a window that cannot be attributed, and a
+ * silently shortened window would read as a clean one.
+ *
+ * @experimental
+ */
+declare function traceSubmission(records: readonly SubmissionRecord[], scored: readonly ScoredSubmission[], frameId: number, span?: number): SubmissionTrace;
+/** @experimental */
+interface SeamStage {
+    framePtsUs: number;
+    /** Offsets in ms from the window's first sample. */
+    metadataMs: number;
+    availableMs: number;
+    consumedMs: number;
+    /** Renderer to queue, queue to latch, in us. -1 when a stamp is missing. */
+    graphUs: number;
+    latchUs: number;
+}
+/** @experimental */
+interface SeamTrace {
+    /** The boundary this window is centred on, in project time. */
+    atUs: number;
+    /** The largest gap between consecutive frames reaching the renderer, in us. */
+    outputGapUs: number;
+    /** The same gap measured at acquisition. */
+    acquireGapUs: number;
+    /**
+     * Who owns the gap.
+     *
+     * `graph` when the renderer produced and the queue did not follow.
+     * `consumer` when it was queued and not latched. `production` when nothing
+     * reached the renderer's output callback at all.
+     *
+     * That last one is deliberately broader than "the decoder was unprepared":
+     * this stamp fires when the renderer is about to hand a frame to the surface,
+     * so its absence covers a decoder that produced nothing *and* a renderer
+     * blocked waiting for the sink to accept a new input stream. Separating those
+     * two needs a stamp inside Media3 that is not exposed here. What it does
+     * establish is that the graph and this consumer are not responsible, which is
+     * what the acquisition gap alone could not say.
+     */
+    owner: 'production' | 'graph' | 'consumer' | 'unknown';
+    stages: SeamStage[];
+    invalid: boolean;
+    reason: string;
+}
+/**
+ * Where output stops at a clip boundary.
+ *
+ * The acquisition gap says delivery stopped; it cannot say whether the decoder
+ * produced nothing, the video graph held what it produced, or this consumer
+ * failed to latch what was queued. Those are three owners and three different
+ * fixes, and they are separated by one stamp: when the renderer said a frame
+ * was about to go to the surface.
+ *
+ * Samples carrying no frame are skipped rather than treated as a gap — the
+ * poller runs faster than the frame rate, so most samples repeat the last
+ * frame, and counting those would report a stall on every tick.
+ *
+ * @experimental
+ */
+declare function traceSeam(samples: readonly SpikeSample[], atUs: number, spanUs?: number): SeamTrace;
+/** One frame, seen from both sides of the pairing. @experimental */
+interface StartupRow {
+    frameId: number;
+    /** What Media3 said this frame's presentation time was. */
+    renderedPtsUs: number;
+    /** What the submission record was written under. The same number, or a bug. */
+    recordedPtsUs: number;
+    /** What the pixels say the frame is. Independent of both. */
+    marker: number;
+    /** The source frame the marker's own index implies, at this clip's speed. */
+    markerPtsUs: number;
+    metadataMs: number;
+    consumedMs: number;
+    submittedMs: number;
+}
+/** @experimental */
+interface StartupTrace {
+    rows: StartupRow[];
+    /**
+     * Frames the renderer never emitted, by source index.
+     *
+     * The discriminator. If the renderer emitted a presentation time and the
+     * pixels under it belong to a different frame, the *association* is wrong. If
+     * it never emitted that time at all, the frame was dropped or never produced.
+     * Those are different defects and the pixels alone cannot tell them apart.
+     */
+    missingSourceFrames: number[];
+    /** Frames whose pixels disagree with the time they were rendered under. */
+    misassociated: number[];
+    invalid: boolean;
+    reason: string;
+}
+/**
+ * The first frames of a clip, from both sides of the pairing at once.
+ *
+ * Media3's presentation time and the marker in the pixels are independent
+ * claims about the same frame. Joined by frame id, they separate "frames 2 to 6
+ * were never produced" from "frame 7's pixels arrived labelled as frame 2" —
+ * which look identical in a cadence result and need opposite fixes.
+ *
+ * @experimental
+ */
+declare function traceStartup(samples: readonly SpikeSample[], records: readonly SubmissionRecord[], options: {
+    sourceFps: number;
+    speed: number;
+    count?: number;
+}): StartupTrace;
+
+/**
+ * Did the preview show the right frame at each output instant?
+ *
+ * ## The oracle this replaces
+ *
+ * The first version counted *source* frames and expected every one to appear.
+ * That reported a 2x clip — 6 seconds of source occupying 3 seconds — as
+ * delivering 98 of 180 frames with 58 missed intervals. The 180 was wrong: a
+ * preview has its own output rate, and at 30 fps three seconds of timeline has
+ * about 90 output instants, at each of which the resampling rule *skips* every
+ * second source frame by design. Requiring all 180 asked the preview to run at
+ * 60 fps and then scored it for refusing.
+ *
+ * So the oracle is the shared rule itself. `resampleClip` already decides which
+ * source frame belongs at each output instant, at a stated target rate, and it
+ * is the same function the exporter's contract is written against. Using it
+ * here means the preview and the export cannot disagree about what "correct"
+ * means.
+ *
+ * ## What is checked
+ *
+ * At each expected output instant, whether the picture on screen is the frame
+ * the rule names. Not whether every source frame appeared — above 1x most of
+ * them must not.
+ *
+ * @experimental
+ */
+/** One clip, as the playlist compiled it. @experimental */
+interface CadenceClip {
+    name: string;
+    /** Where the window sits on the project timeline. */
+    timelineStartUs: number;
+    timelineEndUs: number;
+    /** Clipping bounds in source time. */
+    sourceStartUs: number;
+    sourceEndUs: number;
+    speed: number;
+    sourceFps: number;
+}
+/**
+ * How far the preview may sit from the export's frame selection.
+ *
+ * The tolerance the rest of the video path is held to. A preview picture is
+ * temporally accurate when the frame it shows is within this of the frame the
+ * rule names, converted to project time — not when it is that exact frame.
+ *
+ * @experimental
+ */
+declare const PREVIEW_TOLERANCE_US = 60000;
+/**
+ * What a run established, as three outcomes rather than two.
+ *
+ * `invalid` is not a soft failure — it is the absence of a measurement, and it
+ * must never be reachable by a run that simply had the probe switched off. A
+ * boolean cannot say that: `false` reads as "measured and wrong", and three
+ * device runs once reported `wrong=0, worstOffset=0.0 ms` because a shifted
+ * button meant nothing was scorable at all. That was a clean pass by absence of
+ * evidence and one paste from being reported as a fix working.
+ *
+ * @experimental
+ */
+type Verdict = 'pass' | 'fail' | 'invalid';
+/** Rendering correctness, per clip. @experimental */
+interface CadenceParity {
+    /** Submissions that carried a parity measurement. */
+    measured: number;
+    /** Worst background-level error, 0..255. */
+    worstLevelDelta: number;
+    /** Worst bar-position error, in 0..1 of height. */
+    worstBarDelta: number;
+    /** Submissions whose rendering was outside tolerance. */
+    failures: number;
+    pass: boolean;
+}
+/** @experimental */
+interface CadenceResult {
+    clip: string;
+    /** Output instants the rule names for the whole clip. */
+    nominalInstants: number;
+    /** Output instants the rule expects across the span actually covered. */
+    expectedInstants: number;
+    /**
+     * Instants that could not be placed on the wall clock.
+     *
+     * No bracketing pair of player-clock samples inside one segment — the
+     * transport was paused or seeking across them. Counted and excluded from
+     * scoring rather than placed by extrapolation.
+     */
+    unplaceableInstants: number;
+    /**
+     * How far the frame-derived clock sits from the player's, in microseconds.
+     *
+     * A diagnostic, never the anchor. Positive means pictures are handed over
+     * later than the project time they carry — the pipeline's systematic
+     * presentation delay.
+     *
+     * Anchoring on the frame-derived value would subtract this from every
+     * measurement and call a uniformly late pipeline punctual, which is why
+     * instants are placed from the player's clock and this is only reported.
+     */
+    frameDerivedOffsetUs: number;
+    /**
+     * Instants before the first submission, and after the last.
+     *
+     * Named rather than absorbed. Scoring a clip over its nominal length would
+     * count every instant a run never reached as a missed deadline; excluding
+     * them silently would let a picture that arrived late or stopped early
+     * disappear from coverage instead. They are excluded from the identity check
+     * and reported here, and `leadingExcluded` in particular is the interval
+     * where the previous clip was still on screen — which is the seam, and is
+     * scored by the submission metric rather than by this one.
+     */
+    leadingExcluded: number;
+    trailingExcluded: number;
+    /** Instants where some frame was on screen. */
+    coveredInstants: number;
+    /**
+     * Instants showing a different source frame from the one the rule names.
+     *
+     * The real failure: a missed deadline is the picture being wrong at a moment
+     * somebody was looking, not a source frame going unused.
+     */
+    wrongFrameInstants: number;
+    /** Instants with no frame at all — the picture had not caught up. */
+    uncoveredInstants: number;
+    /** Unique pictures submitted inside the span. */
+    submittedUnique: number;
+    /**
+     * Source frames the rule says to skip.
+     *
+     * Above 1x this is most of them and is correct. Reported so a count of
+     * "missing" frames cannot be read as loss.
+     */
+    ruleSkippedSourceFrames: number;
+    /** The interval between output instants, from the declared preview rate. */
+    outputIntervalUs: number;
+    medianHoldUs: number;
+    maxHoldUs: number;
+    /**
+     * How long one picture should stay up, from the rule.
+     *
+     * At 2x a new source frame is due at every output instant; at 0.5x the rule
+     * repeats each one, so a hold of two instants is correct rather than a stall.
+     */
+    expectedHoldUs: number;
+    /**
+     * Pictures held past their turn.
+     *
+     * Counted from the holds rather than from the covered span, because a stall
+     * at the end of a run produces no further submissions and would otherwise
+     * simply shorten the span it was scored over.
+     */
+    missedDeadlines: number;
+    /**
+     * How far off the shown frame was, counted in source frames.
+     *
+     * Keyed by `shown - expected`, over every scored instant whose identity was
+     * established — the correct ones included, so the shape of the whole run is
+     * visible rather than only its tail. This is what separates a picture that is
+     * one source frame early from one that is a third of a second stale, and at
+     * 2x those are 8.3 ms and 330 ms of project time: the same count of "wrong
+     * instants" and completely different defects.
+     */
+    offsets: Record<string, number>;
+    /**
+     * The largest offset, in project time rather than in source frames.
+     *
+     * The conversion that makes the count mean something. One source frame at
+     * speed `s` is `1 / sourceFps / s` of project time — 16.7 ms at 2x, 66.7 ms
+     * at 0.5x — so the same offset of three frames is 50 ms in one clip and 200
+     * ms in another. Judged against the synchronisation tolerance, not against
+     * zero: a preview consumes a live decoder at its own display rate and cannot
+     * seek to an exact source frame per instant the way an export does.
+     */
+    worstOffsetUs: number;
+    /**
+     * Rendering correctness, against the frame each picture's own band names.
+     *
+     * Separate from everything above it. The rest of this result is about *which*
+     * frame was shown; this is about whether that frame was drawn correctly —
+     * colour, orientation and scale. A picture one source frame early and
+     * rendered perfectly scores zero here.
+     */
+    parity: CadenceParity;
+    /**
+     * Instants that showed exactly the frame the export rule names.
+     *
+     * Reported, never required. It is the export contract's measure, kept here so
+     * the preview's tolerance is visible as a decision rather than as the absence
+     * of a check.
+     */
+    exactInstants: number;
+    /**
+     * What this run established. @see Verdict
+     *
+     * `pass` only when identity was read from pixels, parity was measured, and
+     * both were clean. Anything unmeasured is `invalid`.
+     */
+    verdict: Verdict;
+    /** Why, when the verdict is not a pass. */
+    verdictReason: string;
+    /** Whether the acquired-identity evidence was usable at all. */
+    identity: CadenceIdentity;
+    /**
+     * Wall-clock gaps between this clip's submissions.
+     *
+     * Per clip because the aggregate mixes rates: a 0.5x clip legitimately holds
+     * each picture for two output intervals, so a global p95 at 66.7 ms is the
+     * 0.5x clip behaving correctly and says nothing about whether the 2x clip
+     * stalled. Reported separately so a delay cannot hide inside a hold.
+     */
+    frameTimeUs: {
+        p50: number;
+        p95: number;
+        p99: number;
+        max: number;
+        samples: number;
+    };
+    /**
+     * Every instant whose picture was not the one the rule names.
+     *
+     * Including the boundary instants the scored span excludes: those are the
+     * seam, and leaving them out of the identity check is how a wrong picture at
+     * a clip change disappears from both metrics at once.
+     */
+    wrong: WrongInstant[];
+    pass: boolean;
+}
+/**
+ * Why an instant showed the wrong picture.
+ *
+ * The first three are decided in pixels and name one place to look. The fourth
+ * is what the metadata alone can support, which is less than it appears: on
+ * this device `SurfaceTexture` reports a system-clock value, so an instant
+ * classified without the marker cannot separate a frame acquired wrongly from a
+ * frame chosen wrongly, and says so rather than picking one.
+ *
+ * @experimental
+ */
+type WrongInstantCause = 
+/**
+ * The expected frame's pixels were not in the ring when the instant needed
+ * them.
+ *
+ * Nothing downstream could have shown it. The fault is decode, acquisition or
+ * the copy into the ring — and the test is by that instant, not by the end of
+ * the clip, because every frame arrives eventually and a clip-global check
+ * would charge a frame that had simply not arrived yet to selection.
+ */
+'not-delivered'
+/**
+ * The expected frame's pixels were in the ring, and a different frame was
+ * submitted.
+ *
+ * The fault is the choice, not the supply.
+ */
+ | 'wrong-selection'
+/**
+ * The submitted picture no longer held the frame its slot was filled with.
+ *
+ * A wrapped texture aliases storage the ring may redraw. This is that storage
+ * changing under a picture composition still holds, and it is the one cause
+ * here that is a correctness defect in the ring's own contract.
+ */
+ | 'storage-aliased'
+/**
+ * The wrong picture, and the evidence cannot say whether it was acquired or
+ * chosen wrongly.
+ *
+ * What the metadata supports with the probe off. Not a third fault: a
+ * placeholder for an attribution not yet made.
+ */
+ | 'wrong-submitted-identity'
+/**
+ * The right frame, submitted after the instant it belonged to.
+ *
+ * Only reachable without pixel identity. When the marker is readable, a frame
+ * matching the rule makes the instant correct however late it was submitted,
+ * so lateness stops being an identity fault and becomes a frame-time one.
+ * Its evidence — the ring's own submission time and project timestamp — is
+ * independent of the disputed pairing, which is why it survives there.
+ */
+ | 'late-delivery'
+/** No submission covered the instant at all. */
+ | 'uncovered';
+/** @experimental */
+interface WrongInstant {
+    projectUs: number;
+    /** From the shared rule: the source frame that belongs at this instant. */
+    expectedSourceFrame: number;
+    expectedSourcePtsUs: number;
+    /** What was on screen, mapped back through the same speed. */
+    shownSourceFrame: number;
+    shownPtsUs: number;
+    /** What the texture said it held when that frame was acquired. */
+    acquiredTexturePtsUs: number;
+    /** The frame index in the pixels of the slot, and of the submitted picture. */
+    acquiredMarker: number;
+    submittedMarker: number;
+    slot: number;
+    frameId: number;
+    submittedNs: number;
+    cause: WrongInstantCause;
+    /** True when the instant lies outside the scored span. */
+    boundary: boolean;
+}
+/** What the texture timestamp turned out to be. @experimental */
+type TimestampDomain = 
+/** Comparable with the clip's media time. */
+'media'
+/** A system-clock value: `System.nanoTime()`, as measured on this device. */
+ | 'system'
+/** Nothing was recorded, so there is nothing to establish. */
+ | 'unknown';
+/** @experimental */
+interface CadenceIdentity {
+    /**
+     * The domain the texture timestamps were established to be in.
+     *
+     * Recorded rather than assumed, and recorded even when it is the one that
+     * makes the check weaker. It was `media` by assumption for one whole run and
+     * the assumption was wrong by forty-eight hours.
+     */
+    timestampDomain: TimestampDomain;
+    medianTextureSkewUs: number;
+    /**
+     * Whether identity came from the pixels.
+     *
+     * When false, the fallback compares submitted timestamps — which on a
+     * `system` domain cannot uniquely associate a buffer with a frame. Every
+     * instant is then counted `identityUnverified` and the clip cannot pass. A
+     * fallback that quietly declared those instants correct would be restoring
+     * confidence the evidence does not support.
+     */
+    pixelIdentity: boolean;
+    /** Instants whose identity could not be established either way. */
+    identityUnverified: number;
+    /** Distinct frame indices read out of the ring for this clip. */
+    deliveredFrames: number;
+    /** Bands that were read, and bands that failed. */
+    markersRead: number;
+    markersFailed: number;
+}
+/**
+ * The preview's own output rate.
+ *
+ * Stated rather than inferred from what arrived: an oracle that takes its
+ * expectation from the measurement cannot fail.
+ *
+ * @experimental
+ */
+declare const PREVIEW_OUTPUT_FPS = 30;
+/** @experimental */
+declare function checkCadence(clip: CadenceClip, submissions: readonly SubmissionRecord[], outputFps?: number, 
+/**
+ * How far the shown frame may be from the named one, in project time.
+ *
+ * Zero scores the export contract — exact selection, no tolerance — and the
+ * default scores the preview's. @see PREVIEW_TOLERANCE_US
+ */
+toleranceUs?: number, 
+/**
+ * The player's own clock, paired with monotonic time.
+ *
+ * Where instants are placed on the wall clock. Empty means no instant can be
+ * placed, and the result is `invalid` rather than scored against a guess.
+ */
+samples?: readonly SpikeSample[]): CadenceResult;
+
+/**
+ * Preview audio, bound to a screen's lifetime.
+ *
+ * The decisions live in `previewAudioSession.ts` and the mixing lives in
+ * native; this is the part that acts — starting jobs, loading the player,
+ * muting the other one, and refusing to publish an answer that has been
+ * superseded.
+ *
+ * ## Epochs
+ *
+ * Every load, play and seek carries the epoch of the mix it belongs to. A
+ * callback or a correction arriving with an older epoch is from a mix that has
+ * since been replaced, and acting on it would move the picture to match audio
+ * that is no longer playing. The epoch is bumped on every publish, so a late
+ * result cannot masquerade as the current one.
+ *
+ * @experimental
+ */
+/** @experimental */
+interface UsePreviewAudioOptions {
+    project: VideoProject;
+    /** The same resolver the exporter is given. */
+    resolveSource: (source: MediaSource, context: ExportSourceContext) => string | null | undefined;
+    /** Off entirely — for a screen that never plays. */
+    enabled?: boolean;
+    /** How far apart the players may drift before audio is moved. */
+    toleranceUs?: number;
+}
+/** @experimental */
+interface PreviewAudioBinding {
+    status: PreviewAudioStatus;
+    /** A sentence for a person when preparation failed. */
+    error: string | null;
+    /** Whether playback may run. False while preparing or after a failure. */
+    canPlay: boolean;
+    /** True once a mix matching the document is loaded. */
+    ready: boolean;
+    /** How long the last preparation took, in ms. Null when it was cached. */
+    lastPrepareMs: number | null;
+    /** Where that time went. Null for a cached mix. */
+    lastProfile: unknown;
+    /**
+     * The prepared mix, for a composition that carries the sound itself.
+     *
+     * Null until one matching the document exists. The preview plays audio and
+     * video from one composition on one clock, so what this hook contributes is
+     * the prepared program — the file and how long it runs — rather than a second
+     * player to keep in step with the first. `play`, `pause`, `seek`, `setRate`
+     * and `checkDrift` are what is left of that second player and are no longer
+     * part of the preview path.
+     */
+    mix: {
+        uri: string;
+        durationUs: number;
+    } | null;
+    /** Cancel, release the player and drop the mix. */
+    release(): void;
+}
+/** @experimental */
+declare function usePreviewAudio(options: UsePreviewAudioOptions): PreviewAudioBinding;
+
+/**
+ * One isolation control for the preview-audio hook, and nothing else.
+ *
+ * ## What it is for
+ *
+ * The picture stops advancing when a mix is loaded, and the minimal failing
+ * configuration loads a *cached* mix — no decode, no encode, no codecs at all.
+ * What is left in common is this hook being active, and being active means two
+ * separable things: the native calls it makes, and the React state it
+ * publishes. Five `useState` values re-render the editor while a surface, a
+ * texture consumer and a composition callback are all being re-established.
+ *
+ * Suppressing the publications while leaving every native call in place
+ * separates those two. If the freeze survives suppression it belongs to the
+ * native side; if it disappears, the trigger is a render-driven ownership
+ * transition and the fix belongs in whatever that render disturbs.
+ *
+ * ## What it is not
+ *
+ * Not a fix, and not reachable from a production build. Suppressed, the hook
+ * cannot report readiness, so audio never plays — the control is deliberately
+ * useless for anything except attribution. Anyone tempted to leave it on to
+ * "reduce renders" is turning a diagnostic into a silent feature regression.
+ *
+ * @experimental
+ */
+/** @experimental */
+interface PreviewAudioDiagnostics {
+    /** Drop the hook's React state publications, keeping every native call. */
+    suppressPublications: boolean;
+    /** Log each publication with its value. Off by default; noisy under a mix. */
+    logPublications: boolean;
+    /** Publications made, and publications suppressed. */
+    published: number;
+    suppressed: number;
+}
+/** @experimental */
+declare const previewAudioDiagnostics: PreviewAudioDiagnostics;
+
+/**
+ * Turning a compiled mix program's spans into files to decode.
+ *
+ * Shared by the exporter and by preview preparation, deliberately. The two must
+ * agree about which file a span means, or a preview would be mixed from one set
+ * of sources and the export from another — and the difference would only be
+ * audible in the finished video.
+ *
+ * @experimental
+ */
+/**
+ * What a span is, so a host can resolve it as what it actually is.
+ *
+ * A span carved from a clip's own audio resolves as that clip — the same
+ * context the video pass used, so the same media resolves the same way. A span
+ * from a music item resolves as that item. The id alone cannot say which, and a
+ * host that guessed would resolve the first thing that matched.
+ */
+declare function mixSpanContext(project: VideoProject, spanId: string): ExportSourceContext | null;
+/** @experimental */
+interface ResolvedMixSources {
+    /** Span id to readable URI, for every span that needs decoding. */
+    uris: Record<string, string>;
+    /** One sentence per span that could not be resolved. Empty means usable. */
+    unresolved: string[];
+}
+/**
+ * Resolve every span that needs decoding.
+ *
+ * Silent spans are skipped: they occupy their time and contribute no samples,
+ * so asking a host to resolve one would be asking for a file that is not
+ * needed — and a host that returned nothing would look like a failure.
+ *
+ * @experimental
+ */
+declare function resolveMixSources(project: VideoProject, program: AudioMixProgram, resolveSource: (source: MediaSource, context: ExportSourceContext) => string | null | undefined): ResolvedMixSources;
+
+/**
+ * The AAC encoder's frozen behaviour, re-measurable on demand.
+ *
+ * The encode loop is 16% of a preview preparation and was 89% of it before it
+ * was rewritten. That rewrite was checked against a baseline of natively
+ * generated PCM fixtures — inputs that are formulas rather than files, so the
+ * two halves of the comparison cannot drift apart — and the check was exact:
+ * access-unit count, payload bytes, payload hash, CSD, timestamps, decoded
+ * frame count, RMS and transient positions all matched.
+ *
+ * This is the door to that. Diagnostics-gated in native, so a release build
+ * without them refuses.
+ *
+ * @experimental
+ */
+/** @experimental */
+interface EncoderGateResult {
+    ok: boolean;
+    fixture?: string;
+    /** Compressed shape. */
+    units?: number;
+    payloadBytes?: number;
+    payloadHash?: number;
+    csd0?: number;
+    firstUs?: number;
+    lastUs?: number;
+    headTimestamps?: number[];
+    /** Decoded result. */
+    decodedFrames?: number;
+    decodedRms?: number;
+    peak?: number;
+    markerPositionsMs?: number[];
+    expectedMarkersMs?: number[];
+    /** What it cost. */
+    encodeMs?: number;
+    inputFrames?: number;
+    fileBytes?: number;
+    error?: string;
+}
+/** The fixtures the gate can run. @experimental */
+declare const ENCODER_GATE_FIXTURES: readonly ["short", "acceptance", "silence", "saturated", "markers"];
+/**
+ * Encode one fixture and describe the result completely.
+ *
+ * Never throws: a gate that is unavailable is an answer.
+ *
+ * @experimental
+ */
+declare function runEncoderGate(fixture: string, maxInputSize?: number): EncoderGateResult;
+
+export { type AndroidThumbnailOptions, AndroidVideoPlayer, type AudioProbeFailure, type AudioProbeResult, CONVERGED_RUN, type CadenceClip, type CadenceResult, type CompositionPlayback, type CompositionPlaybackState, type CompositionSpikeItem, type CompositionSpikeSpec, type CompositionSpikeState, DEFAULT_CEILING_BYTES, DEFAULT_RISE_BYTES, DEFAULT_WINDOW_SAMPLES, type Distribution, ENCODER_GATE_FIXTURES, EXPORT_STAGES, type EncoderGateResult, type Excursion, type ExcursionCause, type ExcursionReport, type ExportJob, type ExportJobs, type ExportJobsOptions, type ExportStage, type IngestResult, MAX_OBSERVED_HEARTBEAT_GAP_MS, MAX_RECOVERY_SAMPLES, type ManagedSource, type ManagedSourceFailure, Media3, type Media3ExporterOptions, type Media3Playback, type Media3State, MediaSaveCancelled, MediaSaveFailed, type MemoryGuard, NO_SURFACE, type OverlayPreparationResult, type OverlayResourceDescriptor, type OverlayStagingSink, PHASE_MARK_PREFIX, PREVIEW_DRIFT_TOLERANCE_US, PREVIEW_OUTPUT_FPS, PREVIEW_TOLERANCE_US, type Phase, type PhaseReport, type PhaseState, type PhaseSummary, type PlaybackLifecycle, type PlaybackLifecycleEffects, type PlaybackStopReason, type PlaylistIntent, type PlaylistSession, type PreparedMix, type PreviewAudioBinding, type PreviewAudioDecision, type PreviewAudioDiagnostics, type PreviewAudioInputs, type PreviewAudioStatus, type PreviewMixResult, type PreviewParts, type ProgressPlan, type ProgressPlanInput, type ProgressReporter, type ProgressReporterOptions, RECOVERY_GRACE_MS, type RecoverySample, type ResolvedMixSources, SPIKE_TOLERANCE_US, STALL_GRACE_MS, type ScoredSubmission, type SeamStage, type SeamTrace, type ShardPlan, type SpikeSample, type StagedRaster, type StallKind, type StallVerdict, type StallWatchdog, type StallWatchdogOptions, type StartupRow, type StartupTrace, type SubmissionRecord, type SubmissionReport, type SubmissionTrace, type SurfaceCreateResult, type SurfaceOwner, type SurfaceOwnerEffects, type SurfaceReadiness, type SyncReport, type SyncTrace, type TickSample, type TraceEvent, type TracePage, type TraceRow, type UseCompositionPlaybackOptions, type UseMedia3PlaybackOptions, type UsePreviewAudioOptions, type Verdict, VideoExportRejected, type VideoSurface, type VideoSurfaceHandle, type VideoSurfaceOptions, afterPrepare, armPreviewTrace, beginPhase, cancelPreviewMix, checkCadence, classifyExcursions, classifyStall, compositionSpikeSpec, createAndroidThumbnailProvider, createExportJobs, createMedia3VideoExporter, createMediaStoreSaver, createMemoryGuard, createOverlayStagingSink, createPlaybackLifecycle, createProgressReporter, createStallWatchdog, createSurfaceOwner, createSyncTrace, decidePreviewAudio, describeTrip, distribution, drainAllPreviewTrace, drainPreviewTrace, expectedPtsAt, idlePlaylistSession, ingestManagedSource, installOverlayStaging, isCurrentGeneration, managedSourceLedger, managedSourceList, managedSourceToken, markPreviewTrace, measureStagingStall, mixSpanContext, muteSourceAudio, nextOwnerToken, observe, observeMemory, offsetAt, planProgressWeights, preparePreviewMix, previewAudioDiagnostics, previewAudioNeeded, previewCodecLedger, previewFramePipeline, previewMixKey, previewMixLedger, previewParts, previewProgramJson, previewSyncCounters, probeAudioSource, record as recordTick, recoveryFrames, releaseManagedSource, releasePreviewMix, resetSurfaceOwnerForTests, resolveMixSources, retireSurface, runEncoderGate, scoreSubmissions, seedManagedSourceForGate, setPreviewParts, shareSavedMedia, shouldPrepare, shouldRecover, spikeClaim, spikeDrain, spikePause, spikePlay, spikeRelease, spikeSeek, spikeStart, spikeState, stopPreviewForHost, summariseOffsets, summarisePhases, surfaceOwner, sweepManagedSources, sweepManagedSourcesRawForGate, sweepOverlayStaging, sweepPendingMediaSaves, sweepPreviewMixes, syncReport, thumbnailCounters, traceSeam, traceStartup, traceSubmission, useCompositionPlayback, useMedia3Playback, usePreviewAudio, useVideoSurface, videoSurfaceSlot, windowAround };