@pictor-sdk/video-android 0.1.0

package/dist/index.js

@@ -0,0 +1,3737 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AndroidVideoPlayer: () => AndroidVideoPlayer,
+  CONVERGED_RUN: () => CONVERGED_RUN,
+  DEFAULT_CEILING_BYTES: () => DEFAULT_CEILING_BYTES,
+  DEFAULT_RISE_BYTES: () => DEFAULT_RISE_BYTES,
+  DEFAULT_WINDOW_SAMPLES: () => DEFAULT_WINDOW_SAMPLES,
+  ENCODER_GATE_FIXTURES: () => ENCODER_GATE_FIXTURES,
+  EXPORT_STAGES: () => EXPORT_STAGES,
+  MAX_OBSERVED_HEARTBEAT_GAP_MS: () => MAX_OBSERVED_HEARTBEAT_GAP_MS,
+  MAX_RECOVERY_SAMPLES: () => MAX_RECOVERY_SAMPLES,
+  Media3: () => Media3,
+  MediaSaveCancelled: () => MediaSaveCancelled,
+  MediaSaveFailed: () => MediaSaveFailed,
+  NO_SURFACE: () => NO_SURFACE,
+  PHASE_MARK_PREFIX: () => PHASE_MARK_PREFIX,
+  PREVIEW_DRIFT_TOLERANCE_US: () => PREVIEW_DRIFT_TOLERANCE_US,
+  PREVIEW_OUTPUT_FPS: () => PREVIEW_OUTPUT_FPS,
+  PREVIEW_TOLERANCE_US: () => PREVIEW_TOLERANCE_US,
+  RECOVERY_GRACE_MS: () => RECOVERY_GRACE_MS,
+  SPIKE_TOLERANCE_US: () => SPIKE_TOLERANCE_US,
+  STALL_GRACE_MS: () => STALL_GRACE_MS,
+  VideoExportRejected: () => VideoExportRejected,
+  afterPrepare: () => afterPrepare,
+  armPreviewTrace: () => armPreviewTrace,
+  beginPhase: () => beginPhase,
+  cancelPreviewMix: () => cancelPreviewMix,
+  checkCadence: () => checkCadence,
+  classifyExcursions: () => classifyExcursions,
+  classifyStall: () => classifyStall,
+  compositionSpikeSpec: () => compositionSpikeSpec,
+  createAndroidThumbnailProvider: () => createAndroidThumbnailProvider,
+  createExportJobs: () => createExportJobs,
+  createMedia3VideoExporter: () => createMedia3VideoExporter,
+  createMediaStoreSaver: () => createMediaStoreSaver,
+  createMemoryGuard: () => createMemoryGuard,
+  createOverlayStagingSink: () => createOverlayStagingSink,
+  createPlaybackLifecycle: () => createPlaybackLifecycle,
+  createProgressReporter: () => createProgressReporter,
+  createStallWatchdog: () => createStallWatchdog,
+  createSurfaceOwner: () => createSurfaceOwner,
+  createSyncTrace: () => createSyncTrace,
+  decidePreviewAudio: () => decidePreviewAudio,
+  describeTrip: () => describeTrip,
+  distribution: () => distribution,
+  drainAllPreviewTrace: () => drainAllPreviewTrace,
+  drainPreviewTrace: () => drainPreviewTrace,
+  expectedPtsAt: () => expectedPtsAt,
+  idlePlaylistSession: () => idlePlaylistSession,
+  ingestManagedSource: () => ingestManagedSource,
+  installOverlayStaging: () => installOverlayStaging,
+  isCurrentGeneration: () => isCurrentGeneration,
+  managedSourceLedger: () => managedSourceLedger,
+  managedSourceList: () => managedSourceList,
+  managedSourceToken: () => managedSourceToken,
+  markPreviewTrace: () => markPreviewTrace,
+  measureStagingStall: () => measureStagingStall,
+  mixSpanContext: () => mixSpanContext,
+  muteSourceAudio: () => muteSourceAudio,
+  nextOwnerToken: () => nextOwnerToken,
+  observe: () => observe,
+  observeMemory: () => observeMemory,
+  offsetAt: () => offsetAt,
+  planProgressWeights: () => planProgressWeights,
+  preparePreviewMix: () => preparePreviewMix,
+  previewAudioDiagnostics: () => previewAudioDiagnostics,
+  previewAudioNeeded: () => previewAudioNeeded,
+  previewCodecLedger: () => previewCodecLedger,
+  previewFramePipeline: () => previewFramePipeline,
+  previewMixKey: () => previewMixKey,
+  previewMixLedger: () => previewMixLedger,
+  previewParts: () => previewParts,
+  previewProgramJson: () => previewProgramJson,
+  previewSyncCounters: () => previewSyncCounters,
+  probeAudioSource: () => probeAudioSource,
+  recordTick: () => record,
+  recoveryFrames: () => recoveryFrames,
+  releaseManagedSource: () => releaseManagedSource,
+  releasePreviewMix: () => releasePreviewMix,
+  resetSurfaceOwnerForTests: () => resetSurfaceOwnerForTests,
+  resolveMixSources: () => resolveMixSources,
+  retireSurface: () => retireSurface,
+  runEncoderGate: () => runEncoderGate,
+  scoreSubmissions: () => scoreSubmissions,
+  seedManagedSourceForGate: () => seedManagedSourceForGate,
+  setPreviewParts: () => setPreviewParts,
+  shareSavedMedia: () => shareSavedMedia,
+  shouldPrepare: () => shouldPrepare,
+  shouldRecover: () => shouldRecover,
+  spikeClaim: () => spikeClaim,
+  spikeDrain: () => spikeDrain,
+  spikePause: () => spikePause,
+  spikePlay: () => spikePlay,
+  spikeRelease: () => spikeRelease,
+  spikeSeek: () => spikeSeek,
+  spikeStart: () => spikeStart,
+  spikeState: () => spikeState,
+  stopPreviewForHost: () => stopPreviewForHost,
+  summariseOffsets: () => summariseOffsets,
+  summarisePhases: () => summarisePhases,
+  surfaceOwner: () => surfaceOwner,
+  sweepManagedSources: () => sweepManagedSources,
+  sweepManagedSourcesRawForGate: () => sweepManagedSourcesRawForGate,
+  sweepOverlayStaging: () => sweepOverlayStaging,
+  sweepPendingMediaSaves: () => sweepPendingMediaSaves,
+  sweepPreviewMixes: () => sweepPreviewMixes,
+  syncReport: () => syncReport,
+  thumbnailCounters: () => thumbnailCounters,
+  traceSeam: () => traceSeam,
+  traceStartup: () => traceStartup,
+  traceSubmission: () => traceSubmission,
+  useCompositionPlayback: () => useCompositionPlayback,
+  useMedia3Playback: () => useMedia3Playback,
+  usePreviewAudio: () => usePreviewAudio,
+  useVideoSurface: () => useVideoSurface,
+  videoSurfaceSlot: () => videoSurfaceSlot,
+  windowAround: () => windowAround
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/memoryGuard.ts
+var DEFAULT_CEILING_BYTES = 250 * 1024 * 1024;
+var DEFAULT_WINDOW_SAMPLES = 40;
+var DEFAULT_RISE_BYTES = 8 * 1024 * 1024;
+function createMemoryGuard(ceilingBytes = DEFAULT_CEILING_BYTES, windowSamples = DEFAULT_WINDOW_SAMPLES, riseBytes = DEFAULT_RISE_BYTES) {
+  return {
+    ceilingBytes,
+    windowSamples: Math.max(3, Math.floor(windowSamples)),
+    riseBytes,
+    samples: [],
+    tripped: null
+  };
+}
+function observeMemory(guard, bytes) {
+  if (guard.tripped) return guard;
+  if (!Number.isFinite(bytes) || bytes <= 0) return guard;
+  if (bytes >= guard.ceilingBytes) {
+    return { ...guard, samples: [...guard.samples, bytes].slice(-guard.windowSamples), tripped: "ceiling" };
+  }
+  const samples = [...guard.samples, bytes].slice(-guard.windowSamples);
+  if (samples.length < guard.windowSamples) return { ...guard, samples };
+  let climbing = true;
+  for (let i = 1; i < samples.length; i++) {
+    if (samples[i] <= samples[i - 1]) {
+      climbing = false;
+      break;
+    }
+  }
+  const climb = samples[samples.length - 1] - samples[0];
+  if (climbing && climb >= guard.riseBytes) {
+    return { ...guard, samples, tripped: "sustained-rise" };
+  }
+  return { ...guard, samples };
+}
+function describeTrip(guard) {
+  if (!guard.tripped) return null;
+  const mb = (b) => (b / (1024 * 1024)).toFixed(0);
+  const latest = guard.samples[guard.samples.length - 1] ?? 0;
+  return guard.tripped === "ceiling" ? `native heap reached ${mb(latest)} MB (ceiling ${mb(guard.ceilingBytes)} MB) \u2014 session released` : `native heap rose ${mb(latest - (guard.samples[0] ?? 0))} MB across ${guard.samples.length} samples without plateauing \u2014 session released`;
+}
+
+// src/syncTrace.ts
+var MAX_SAMPLES = 2e4;
+function createSyncTrace(fps) {
+  const rate = Number.isFinite(fps) && fps > 0 ? fps : 30;
+  return {
+    frameUs: Math.round(1e6 / rate),
+    quantisation: [],
+    decoderLate: [],
+    schedulerLate: [],
+    correction: [],
+    presentedOffset: [],
+    tickInterval: [],
+    ticks: 0,
+    decoderLateTicks: 0,
+    schedulerLateTicks: 0
+  };
+}
+function expectedPtsAt(audioUs, frameUs) {
+  if (audioUs <= 0 || frameUs <= 0) return 0;
+  return Math.floor(audioUs / frameUs) * frameUs;
+}
+function record(trace, sample) {
+  if (trace.ticks >= MAX_SAMPLES) return { ...trace, ticks: trace.ticks + 1 };
+  const expected = expectedPtsAt(sample.audioUs, trace.frameUs);
+  const next = {
+    ...trace,
+    ticks: trace.ticks + 1,
+    quantisation: [...trace.quantisation, sample.audioUs - expected],
+    correction: [...trace.correction, Math.abs(sample.correctionUs)],
+    tickInterval: [...trace.tickInterval, sample.tickIntervalUs],
+    decoderLate: trace.decoderLate,
+    schedulerLate: trace.schedulerLate,
+    presentedOffset: trace.presentedOffset,
+    decoderLateTicks: trace.decoderLateTicks,
+    schedulerLateTicks: trace.schedulerLateTicks
+  };
+  const eligible = sample.newestEligiblePtsUs;
+  if (eligible === null || eligible < expected) {
+    const shortfall = eligible === null ? sample.audioUs : expected - eligible;
+    next.decoderLate = [...trace.decoderLate, shortfall];
+    next.decoderLateTicks = trace.decoderLateTicks + 1;
+  }
+  if (eligible !== null && (sample.presentedPtsUs === null || sample.presentedPtsUs < eligible)) {
+    const behind = eligible - (sample.presentedPtsUs ?? 0);
+    next.schedulerLate = [...trace.schedulerLate, behind];
+    next.schedulerLateTicks = trace.schedulerLateTicks + 1;
+  }
+  if (sample.presentedPtsUs !== null) {
+    next.presentedOffset = [...trace.presentedOffset, sample.presentedPtsUs - sample.audioUs];
+  }
+  return next;
+}
+function distribution(values) {
+  if (values.length === 0) return { n: 0, p50: 0, p95: 0, p99: 0, max: 0 };
+  const abs = values.map(Math.abs).sort((a, b) => a - b);
+  const at = (q) => abs[Math.min(abs.length - 1, Math.floor(q * abs.length))];
+  return { n: abs.length, p50: at(0.5), p95: at(0.95), p99: at(0.99), max: abs[abs.length - 1] };
+}
+function syncReport(trace) {
+  const decoderLate = distribution(trace.decoderLate);
+  const schedulerLate = distribution(trace.schedulerLate);
+  const quantisation = distribution(trace.quantisation);
+  const presentedOffset = distribution(trace.presentedOffset);
+  const decoderShare = trace.ticks === 0 ? 0 : trace.decoderLateTicks / trace.ticks;
+  const schedulerShare = trace.ticks === 0 ? 0 : trace.schedulerLateTicks / trace.ticks;
+  let dominant = "none";
+  if (presentedOffset.p95 > trace.frameUs) {
+    if (decoderShare >= schedulerShare && decoderShare > 0.01) dominant = "decoder";
+    else if (schedulerShare > 0.01) dominant = "scheduler";
+    else dominant = "quantisation";
+  }
+  return {
+    quantisation,
+    decoderLate,
+    schedulerLate,
+    correction: distribution(trace.correction),
+    presentedOffset,
+    tickInterval: distribution(trace.tickInterval),
+    ticks: trace.ticks,
+    decoderLateTicks: trace.decoderLateTicks,
+    schedulerLateTicks: trace.schedulerLateTicks,
+    frameUs: trace.frameUs,
+    dominant
+  };
+}
+
+// src/NativePictorVideo.ts
+var import_react_native = require("react-native");
+var NativePictorVideo_default = import_react_native.TurboModuleRegistry.get("PictorVideo");
+
+// src/player.ts
+var 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() {
+    return requireNative().installVideoSurface();
+  }
+};
+function requireNative() {
+  if (!NativePictorVideo_default) {
+    throw new Error(
+      "@pictor-sdk/video-android: the native module is not installed. It is Android-only and requires minSdkVersion 29."
+    );
+  }
+  return NativePictorVideo_default;
+}
+
+// src/media3.ts
+var EMPTY = {
+  positionUs: 0,
+  durationUs: 0,
+  playing: false,
+  buffering: false,
+  ready: false,
+  ended: false,
+  rate: 1,
+  width: 0,
+  height: 0,
+  released: true,
+  error: "",
+  generation: 0,
+  queueDepth: 0,
+  overflowed: 0,
+  unpaired: 0,
+  stale: 0,
+  queueHighWater: 0,
+  threads: 0,
+  nativeHeapBytes: 0,
+  anchorPositionUs: 0,
+  coalesced: 0,
+  anchorPublications: 0,
+  anchorChanges: 0,
+  anchorMaxStepUs: 0,
+  anchorMeanStepUs: 0,
+  anchorMaxStaleNs: 0,
+  windowIndex: 0,
+  windowCount: 0,
+  windowPositionUs: 0,
+  transitions: 0,
+  missedLatches: 0,
+  updatesAttempted: 0,
+  updatesSucceeded: 0,
+  updatesSkipped: 0,
+  updatesFailed: 0,
+  rateConstrained: 0,
+  effectiveRate: 1,
+  requestedRate: 1,
+  staleWindowSpeeds: 0,
+  windowSpeedCount: 0,
+  framesOffered: 0,
+  framesAvailable: 0,
+  pendingDepth: 0,
+  framesRejected: 0,
+  pendingGeneration: 0,
+  controllerId: 0,
+  pendingId: 0,
+  orphaned: 0,
+  videoFormat: "",
+  decoderName: "",
+  inputFormats: 0,
+  inputWidth: 0,
+  inputHeight: 0,
+  inputRotation: 0,
+  decoderReuse: -1,
+  outputSizes: 0,
+  outputWidth: 0,
+  outputHeight: 0,
+  surfaceGeneration: 0,
+  surfaceAttachments: 0,
+  attachedSurfaceGeneration: 0,
+  liveSurfaceGeneration: 0,
+  seeksRequested: 0,
+  seeksAccepted: 0,
+  pendingSeek: false,
+  playbackState: 0,
+  lastPairedPtsUs: -1,
+  errorCount: 0,
+  errorCode: 0,
+  errorMessage: "",
+  errorRecoverable: false
+};
+var 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) {
+    return requireNative().media3Prepare(uri);
+  },
+  /** Diagnostics: a player with no video output, for heap attribution. */
+  prepareNoSurface(uri) {
+    return requireNative().media3PrepareNoSurface(uri);
+  },
+  /** Diagnostics: reuse the existing player for another source. */
+  rebind(uri) {
+    return requireNative().media3Rebind(uri);
+  },
+  /** Diagnostics: end the source, keep the player. */
+  stopKeepingPlayer() {
+    requireNative().media3StopKeepingPlayer();
+  },
+  /**
+   * 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, start = { windowIndex: 0, positionUs: 0 }, options = {}) {
+    if (playlist.unsupported.length > 0 && options.allowDivergence !== true) {
+      throw new Error(
+        `@pictor-sdk/video-android: refusing to build a playlist that would diverge from the timeline. ${playlist.unsupported.length} clip(s) cannot play:
+` + playlist.unsupported.map((u) => `  \xB7 ${u.message}`).join("\n") + "\nPass { allowDivergence: true } to play the remainder anyway."
+      );
+    }
+    const uris = [];
+    const bounds = [];
+    for (const item of playlist.items) {
+      uris.push(uriOf(item.source));
+      bounds.push(item.startUs, item.endUs, Math.round(item.speed * 1e3), item.muted ? 1 : 0);
+    }
+    return requireNative().media3SetPlaylist(uris, bounds, start.windowIndex, start.positionUs);
+  },
+  /** Seek in the player's coordinates. Pair with `projectTimeToWindow`. */
+  seekToWindow(windowIndex, positionUs) {
+    requireNative().media3SeekToWindow(windowIndex, positionUs);
+  },
+  play() {
+    requireNative().media3Play();
+  },
+  pause() {
+    requireNative().media3Pause();
+  },
+  /** Microseconds, like every other time in Pictor. */
+  seek(positionUs) {
+    requireNative().media3Seek(positionUs);
+  },
+  setRate(rate) {
+    requireNative().media3SetRate(rate);
+  },
+  /**
+   * 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() {
+    requireNative().media3Retry();
+  },
+  release() {
+    requireNative().media3Release();
+  },
+  /** A snapshot for throttled reads. Never call this per frame. */
+  state() {
+    const raw = requireNative().media3State();
+    return raw ? { ...EMPTY, ...raw } : EMPTY;
+  }
+};
+function uriOf(source) {
+  if (typeof source === "string") return source;
+  if (source && typeof source === "object" && "uri" in source) {
+    const uri = source.uri;
+    if (typeof uri === "string") return uri;
+  }
+  throw new Error(
+    `@pictor-sdk/video-android: a clip's source is not a URI. Normalise host media to { kind: 'uri', uri } before opening a project. Received: ${JSON.stringify(source)}`
+  );
+}
+
+// src/playlistSession.ts
+var NO_SURFACE = 0;
+function idlePlaylistSession() {
+  return { appliedSignature: null, appliedGeneration: NO_SURFACE, pending: false };
+}
+function shouldPrepare(session, intent) {
+  if (intent.generation === NO_SURFACE) return false;
+  if (session.pending) return true;
+  if (session.appliedSignature !== intent.signature) return true;
+  return session.appliedGeneration !== intent.generation;
+}
+function afterPrepare(session, intent, ok) {
+  if (!ok) return { ...session, pending: true };
+  return {
+    appliedSignature: intent.signature,
+    appliedGeneration: intent.generation,
+    pending: false
+  };
+}
+function retireSurface(session) {
+  return { ...session, appliedGeneration: NO_SURFACE, pending: true };
+}
+function isCurrentGeneration(generation, live) {
+  return generation !== NO_SURFACE && generation === live;
+}
+
+// src/surfaceOwner.ts
+function createSurfaceOwner(initial) {
+  let effects = initial;
+  let readiness = { generation: NO_SURFACE, error: "" };
+  let busy = false;
+  let retired = 0;
+  let activeToken = null;
+  let activeRetired = false;
+  let currentToken = null;
+  let queuedToken = null;
+  const listeners = /* @__PURE__ */ new Set();
+  const emit = () => {
+    for (const listener of listeners) listener();
+  };
+  const publish = (next) => {
+    if (next.generation === readiness.generation && next.error === readiness.error) return;
+    readiness = next;
+    emit();
+  };
+  const start = (token) => {
+    busy = true;
+    activeToken = token;
+    activeRetired = false;
+    effects.create();
+  };
+  const owner = {
+    get readiness() {
+      return readiness;
+    },
+    get busy() {
+      return busy;
+    },
+    get retired() {
+      return retired;
+    },
+    request(token) {
+      currentToken = token;
+      if (readiness.generation !== NO_SURFACE) return false;
+      if (busy) {
+        queuedToken = token;
+        return false;
+      }
+      start(token);
+      return true;
+    },
+    retireOwner(token) {
+      if (activeToken === token) activeRetired = true;
+      if (currentToken === token) currentToken = null;
+      if (queuedToken === token) queuedToken = null;
+    },
+    adopt(generation, token) {
+      currentToken = token;
+      if (generation === NO_SURFACE) return;
+      publish({ generation, error: "" });
+    },
+    complete(result) {
+      const wasRetired = activeRetired;
+      const hasOwner = currentToken !== null;
+      busy = false;
+      activeToken = null;
+      activeRetired = false;
+      if (result.ok && result.generation > NO_SURFACE) {
+        const superseded = wasRetired || !hasOwner;
+        const stale = result.generation < readiness.generation;
+        if (superseded || stale) {
+          retired += 1;
+          effects.retire(result.generation);
+        } else {
+          publish({ generation: result.generation, error: "" });
+        }
+      } else {
+        publish({
+          generation: readiness.generation,
+          error: result.error || "surface create failed"
+        });
+      }
+      const next = queuedToken;
+      queuedToken = null;
+      if (next !== null && readiness.generation === NO_SURFACE && next === currentToken) {
+        start(next);
+      }
+    },
+    useEffects(next) {
+      effects = next;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    }
+  };
+  return owner;
+}
+var singleton = null;
+function surfaceOwner(effects) {
+  if (!singleton) singleton = createSurfaceOwner(effects);
+  else singleton.useEffects(effects);
+  return singleton;
+}
+function resetSurfaceOwnerForTests() {
+  singleton = null;
+}
+var nextToken = 0;
+function nextOwnerToken() {
+  nextToken += 1;
+  return nextToken;
+}
+
+// src/useVideoSurface.ts
+var import_react = require("react");
+var import_react_native2 = require("react-native");
+var import_react_native_reanimated = require("react-native-reanimated");
+var CREATE_RETRY_MS = 250;
+function videoSurfaceSlot() {
+  const published = globalThis.__pictorVideoSurface;
+  if (published) return published;
+  if (!AndroidVideoPlayer.installVideoSurface()) return void 0;
+  return globalThis.__pictorVideoSurface;
+}
+function useVideoSurface(options) {
+  const { width, height, enabled = true } = options;
+  const [readiness, setReadiness] = (0, import_react.useState)({ generation: NO_SURFACE, error: "" });
+  const handleRef = (0, import_react.useRef)(void 0);
+  if (!handleRef.current) handleRef.current = videoSurfaceSlot();
+  const textureId = (0, import_react_native_reanimated.useSharedValue)(0);
+  const tokenRef = (0, import_react.useRef)(0);
+  if (tokenRef.current === 0) tokenRef.current = nextOwnerToken();
+  const token = tokenRef.current;
+  const [attempt, setAttempt] = (0, import_react.useState)(0);
+  const ownerRef = (0, import_react.useRef)(void 0);
+  const complete = (0, import_react.useCallback)((result) => {
+    ownerRef.current?.complete(result);
+  }, []);
+  const owner = surfaceOwner({
+    create() {
+      const published = handleRef.current;
+      if (!published) {
+        complete({ ok: false, generation: 0, textureId: 0, error: "__pictorVideoSurface missing" });
+        return;
+      }
+      (0, import_react_native_reanimated.runOnUI)(() => {
+        "worklet";
+        const created = published.create(width, height);
+        textureId.value = created.textureId;
+        if (created.ok && !(created.generation > 0)) {
+          (0, import_react_native_reanimated.runOnJS)(complete)({
+            ok: false,
+            generation: 0,
+            textureId: created.textureId,
+            error: "adapter too old: create() reports no generation"
+          });
+          return;
+        }
+        (0, import_react_native_reanimated.runOnJS)(complete)({
+          ok: created.ok && created.textureId > 0,
+          generation: created.generation,
+          textureId: created.textureId,
+          // The native reason, not a summary of it. "No EGL context current on
+          // this thread" and "no JNIEnv" send a reader to different places.
+          error: created.ok ? "" : created.error || "surface create failed"
+        });
+      })();
+    },
+    retire(generation) {
+      const published = handleRef.current;
+      if (!published || typeof published.releaseGeneration !== "function") return;
+      (0, import_react_native_reanimated.runOnUI)(() => {
+        "worklet";
+        published.releaseGeneration(generation);
+      })();
+    }
+  });
+  ownerRef.current = owner;
+  (0, import_react.useEffect)(() => {
+    const unsubscribe = owner.subscribe(() => setReadiness(owner.readiness));
+    setReadiness(owner.readiness);
+    return unsubscribe;
+  }, [owner]);
+  const ensure = (0, import_react.useCallback)(() => {
+    if (!enabled) return;
+    const published = videoSurfaceSlot();
+    if (!published) {
+      setReadiness((prev) => ({ ...prev, error: "__pictorVideoSurface missing" }));
+      return;
+    }
+    handleRef.current = published;
+    if (typeof published.alive === "function" && typeof published.generation === "function" && published.alive() && published.generation() !== NO_SURFACE) {
+      owner.adopt(published.generation(), token);
+      return;
+    }
+    owner.request(token);
+  }, [enabled, owner, token]);
+  (0, import_react.useEffect)(() => {
+    ensure();
+  }, [ensure, attempt]);
+  (0, import_react.useEffect)(() => {
+    if (!enabled) return;
+    if (readiness.generation !== NO_SURFACE) return;
+    const id = setInterval(() => setAttempt((n) => n + 1), CREATE_RETRY_MS);
+    return () => clearInterval(id);
+  }, [enabled, readiness.generation]);
+  (0, import_react.useEffect)(() => {
+    if (!enabled) return;
+    const onChange = (status) => {
+      if (status === "active") {
+        ensure();
+        return;
+      }
+      owner.retireOwner(token);
+    };
+    const subscription = import_react_native2.AppState.addEventListener("change", onChange);
+    return () => subscription.remove();
+  }, [enabled, ensure, owner, token]);
+  (0, import_react.useEffect)(() => () => owner.retireOwner(token), [owner, token]);
+  return {
+    // Always the slot, never undefined once installed. Gating this on readiness
+    // is what put a null into the consumer's closure and kept it there.
+    surface: handleRef.current,
+    generation: readiness.generation,
+    error: readiness.error
+  };
+}
+
+// src/useCompositionPlayback.ts
+var import_react2 = require("react");
+var import_video_core2 = require("@pictor-sdk/video-core");
+
+// src/compositionSpike.ts
+var import_video_core = require("@pictor-sdk/video-core");
+function compositionSpikeSpec(project, mix, resolve) {
+  const playlist = (0, import_video_core.playlistOf)(project);
+  const items = [];
+  const unsupported = playlist.unsupported.map((u) => `${u.clipId}: ${u.reason}`);
+  for (const item of playlist.items) {
+    const uri = resolve(item.source);
+    if (uri === null) {
+      unsupported.push(`${item.clipId}: unresolved`);
+      continue;
+    }
+    items.push({
+      uri,
+      startUs: Number(item.startUs),
+      endUs: Number(item.endUs),
+      speed: item.speed
+    });
+  }
+  return {
+    spec: {
+      items,
+      mixUri: mix.uri,
+      mixDurationUs: mix.durationUs,
+      width: project.size.width,
+      height: project.size.height
+    },
+    unsupported
+  };
+}
+function call(fn, label) {
+  try {
+    return JSON.parse(fn());
+  } catch (error) {
+    return { ok: false, error: `${label}: ${String(error)}` };
+  }
+}
+function spikeClaim() {
+  const result = call(() => requireNative().spikeClaim(), "spikeClaim");
+  return typeof result.requestId === "number" ? result.requestId : 0;
+}
+function spikeStart(spec) {
+  return call(() => requireNative().spikeStart(JSON.stringify(spec)), "spikeStart");
+}
+function spikePlay() {
+  return call(() => requireNative().spikePlay(), "spikePlay");
+}
+function spikePause() {
+  return call(() => requireNative().spikePause(), "spikePause");
+}
+function spikeSeek(positionUs) {
+  return call(() => requireNative().spikeSeek(positionUs), "spikeSeek");
+}
+function spikeState() {
+  return call(() => requireNative().spikeState(), "spikeState");
+}
+function spikeDrain(fromSeq, limit = 400) {
+  const page = call(() => requireNative().spikeDrain(fromSeq, limit), "spikeDrain");
+  return {
+    ok: page.ok === true,
+    rows: (page.rows ?? []).map((r) => ({
+      seq: r[0],
+      atNs: r[1],
+      positionUs: r[2],
+      playing: (r[3] & 1) === 1,
+      ready: (r[3] & 2) === 2,
+      epoch: r[4],
+      sinceEpochNs: r[5],
+      frameId: r[6],
+      frameGeneration: r[7],
+      frameWindow: r[8],
+      framePtsUs: r[9],
+      frameReleaseNs: r[10],
+      frameConsumedNs: r[11],
+      frameAvailableNs: r[12],
+      coalesced: r[13],
+      offered: r[14],
+      available: r[15],
+      taken: r[16],
+      readSpanNs: r[17],
+      frameMetadataNs: r[18] ?? -1
+    })),
+    nextSeq: page.nextSeq ?? fromSeq,
+    total: page.total ?? 0,
+    dropped: page.dropped ?? 0
+  };
+}
+function spikeRelease() {
+  return call(() => requireNative().spikeRelease(), "spikeRelease");
+}
+
+// src/playbackLifecycle.ts
+function createPlaybackLifecycle(effects) {
+  let active = true;
+  let released = false;
+  let reason = null;
+  let epoch = 1;
+  return {
+    get active() {
+      return active;
+    },
+    get released() {
+      return released;
+    },
+    get reason() {
+      return reason;
+    },
+    get epoch() {
+      return epoch;
+    },
+    accepts(at) {
+      if (released) return false;
+      return active && at === epoch;
+    },
+    suspend(why) {
+      if (released || !active) return;
+      active = false;
+      reason = why;
+      epoch += 1;
+      effects.pause();
+    },
+    resume() {
+      if (released || active) return;
+      active = true;
+      reason = null;
+      epoch += 1;
+    },
+    teardown(why) {
+      if (released) return;
+      const wasActive = active;
+      released = true;
+      active = false;
+      reason = why;
+      epoch += 1;
+      if (wasActive) effects.pause();
+      effects.release();
+    }
+  };
+}
+
+// src/useCompositionPlayback.ts
+var POLL_MS = 100;
+function composedState(snapshot) {
+  const playbackState = snapshot.playbackState ?? 1;
+  return {
+    playing: snapshot.playing === true,
+    ready: playbackState === 3,
+    buffering: playbackState === 2,
+    ended: playbackState === 4,
+    // `released` counts releases; a positive count with nothing attached is the
+    // released state this means.
+    released: snapshot.attached !== true && (snapshot.released ?? 0) > 0,
+    positionUs: snapshot.positionUs ?? 0,
+    durationUs: snapshot.durationUs ?? 0,
+    /*
+          Zero, and honestly so.
+    
+          A composition renders into the presentation surface at the size the host
+          gave it; it does not report a decoded size the way the video player did.
+          The host already knows the size it asked for, and a fabricated number here
+          would be worse than none.
+        */
+    width: 0,
+    height: 0,
+    error: snapshot.error ?? null
+  };
+}
+function useCompositionPlayback(options) {
+  const { project, mix, enabled = true } = options;
+  const surfaceGeneration = options.surfaceGeneration ?? 0;
+  const resolveSource = (0, import_react2.useRef)(options.resolveSource);
+  resolveSource.current = options.resolveSource;
+  const [state, setState] = (0, import_react2.useState)(null);
+  const [playing, setPlaying] = (0, import_react2.useState)(false);
+  const playheadRef = (0, import_react2.useRef)(options.playheadUs);
+  playheadRef.current = options.playheadUs;
+  const playlist = (0, import_react2.useMemo)(() => (0, import_video_core2.playlistOf)(project), [project]);
+  const items = playlist.items;
+  const durationUs = (0, import_react2.useMemo)(() => (0, import_video_core2.projectDuration)(project), [project]);
+  const needsMix = project.audio.length > 0;
+  const signature = (0, import_react2.useMemo)(() => {
+    if (needsMix && mix === null) return "";
+    const parts = items.map(
+      (i) => `${JSON.stringify(i.source)}|${i.startUs}|${i.endUs}|${i.speed}|${i.muted}`
+    );
+    const sound = mix === null ? "silent" : `${mix.uri}:${mix.durationUs}`;
+    return `${parts.join(";")}#${playlist.unsupported.length}@${sound}`;
+  }, [items, playlist.unsupported.length, mix, needsMix]);
+  const [unsupported, setUnsupported] = (0, import_react2.useState)([]);
+  const lastSeekRef = (0, import_react2.useRef)(null);
+  const lifecycleRef = (0, import_react2.useRef)(null);
+  if (lifecycleRef.current === null) {
+    lifecycleRef.current = createPlaybackLifecycle({
+      pause: () => void spikePause(),
+      release: () => void spikeRelease()
+    });
+  }
+  const lifecycle = lifecycleRef.current;
+  const [lifecycleEpoch, setLifecycleEpoch] = (0, import_react2.useState)(lifecycle.epoch);
+  const loaded = (0, import_react2.useRef)("");
+  (0, import_react2.useEffect)(() => {
+    if (!enabled || signature === "") return;
+    if (surfaceGeneration === 0) return;
+    if (loaded.current === signature) return;
+    const { spec, unsupported: refused } = compositionSpikeSpec(
+      project,
+      mix ?? { uri: "", durationUs: 0 },
+      (s) => resolveSource.current(s)
+    );
+    setUnsupported(
+      refused.map((reason) => ({ clipId: reason.split(":")[0] ?? "", reason }))
+    );
+    if (spec.items.length === 0) return;
+    const started = spikeStart(spec);
+    if (started.ok === true) loaded.current = signature;
+  }, [enabled, signature, surfaceGeneration, project, mix]);
+  (0, import_react2.useEffect)(() => {
+    return () => {
+      lifecycle.teardown("unmount");
+    };
+  }, [lifecycle]);
+  (0, import_react2.useEffect)(() => {
+    if (!enabled) return;
+    const epoch = lifecycle.epoch;
+    const id = setInterval(() => {
+      if (!lifecycle.accepts(epoch)) return;
+      const next = composedState(spikeState());
+      setState(
+        (previous) => previous !== null && previous.playing === next.playing && previous.ready === next.ready && previous.buffering === next.buffering && previous.ended === next.ended && previous.released === next.released && previous.error === next.error ? previous : next
+      );
+      setPlaying(next.playing);
+    }, POLL_MS);
+    return () => clearInterval(id);
+  }, [enabled, lifecycle, lifecycleEpoch]);
+  const seek = (0, import_react2.useCallback)((timeUs) => {
+    const at = Math.max(0, Math.round(timeUs));
+    lastSeekRef.current = { globalUs: at, windowIndex: 0, localUs: at };
+    spikeSeek(at);
+  }, []);
+  const positionUs = (0, import_react2.useCallback)(() => {
+    const snapshot = spikeState();
+    if (!snapshot.attached) return null;
+    const at = snapshot.positionUs;
+    return typeof at === "number" ? at : null;
+  }, []);
+  const play = (0, import_react2.useCallback)(() => {
+    const snapshot = spikeState();
+    const intent = (0, import_video_core2.playIntent)({
+      positionUs: typeof snapshot.positionUs === "number" ? snapshot.positionUs : 0,
+      durationUs,
+      playbackState: typeof snapshot.playbackState === "number" ? snapshot.playbackState : 1,
+      ended: snapshot.playbackState === 4
+    });
+    if (intent.seekToUs !== null) seek(intent.seekToUs);
+    if (!intent.play) return intent;
+    if (lifecycle.released) return intent;
+    spikePlay();
+    setPlaying(true);
+    return intent;
+  }, [durationUs, lifecycle, seek]);
+  (0, import_react2.useEffect)(() => {
+    setLifecycleEpoch(lifecycle.epoch);
+  }, [lifecycle, surfaceGeneration]);
+  return {
+    playing,
+    play,
+    get lastSeek() {
+      return lastSeekRef.current;
+    },
+    positionUs,
+    effectiveRate: 1,
+    pause: (0, import_react2.useCallback)(() => {
+      spikePause();
+      setPlaying(false);
+    }, []),
+    /*
+          Rate is the document's, not the transport's.
+    
+          Clip speed is compiled into the composition and into the mix, and a
+          preview-wide rate on top of it would be a second speed nobody asked for.
+          The contract keeps the method; this path has nothing to do with it.
+        */
+    setRate: (0, import_react2.useCallback)(() => {
+    }, []),
+    seek,
+    state,
+    items,
+    unsupported,
+    divergenceUs: 0,
+    lifecycle,
+    // One player, so there is no half to stall: the recovery this reported was
+    // the video player running while the audio player had stopped, or the
+    // reverse. @see docs/research/preview-acceptance.md
+    stall: null
+  };
+}
+
+// src/useMedia3Playback.ts
+var import_video_core3 = require("@pictor-sdk/video-core");
+var import_react3 = require("react");
+var import_react_native3 = require("react-native");
+
+// src/surfaceRecovery.ts
+var RECOVERY_GRACE_MS = 1500;
+function classifyStall(since, now) {
+  if (now.positionUs <= since.positionUs) return null;
+  if (now.pendingGeneration !== now.consumerGeneration || now.framesRejected > since.framesRejected) {
+    return "handshake";
+  }
+  const latched = now.framesLatched > since.framesLatched;
+  if (latched) {
+    return "resource";
+  }
+  const arrived = now.framesAvailable > since.framesAvailable;
+  if (arrived) return "consumer";
+  return "attachment";
+}
+function shouldRecover(since, now, graceMs = RECOVERY_GRACE_MS) {
+  if (now.atMs - since.atMs < graceMs) return false;
+  const kind = classifyStall(since, now);
+  return kind === "consumer" || kind === "handshake" || kind === "attachment";
+}
+
+// src/useMedia3Playback.ts
+var DEFAULT_POLL_MS = 100;
+var RETRY_INTERVAL_MS = 250;
+function useMedia3Playback(options) {
+  const { project, playheadUs, enabled = true } = options;
+  const surfaceGeneration = options.surfaceGeneration ?? NO_SURFACE;
+  const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
+  const [state, setState] = (0, import_react3.useState)(null);
+  const [playing, setPlaying] = (0, import_react3.useState)(false);
+  const playlist = (0, import_react3.useMemo)(() => (0, import_video_core3.playlistOf)(project), [project]);
+  const items = playlist.items;
+  const divergenceUs = (0, import_react3.useMemo)(
+    () => (0, import_video_core3.projectDuration)(project) - (0, import_video_core3.playableDuration)(playlist),
+    [project, playlist]
+  );
+  const signature = (0, import_react3.useMemo)(
+    () => items.map((i) => `${JSON.stringify(i.source)}|${i.startUs}|${i.endUs}|${i.speed}|${i.muted}`).join(";") + // Unsupported clips belong in the signature even though they are not
+    // windows. Adding a photo between two videos leaves the video windows
+    // identical, so a signature built from items alone would not change and
+    // the player would keep playing a timeline that had grown underneath it —
+    // the exact divergence this is all meant to prevent.
+    `!${playlist.unsupported.map((u) => `${u.clipId}:${u.reason}`).join(",")}`,
+    [items, playlist.unsupported]
+  );
+  const playheadRef = (0, import_react3.useRef)(playheadUs);
+  playheadRef.current = playheadUs;
+  const itemsRef = (0, import_react3.useRef)(items);
+  itemsRef.current = items;
+  const session = (0, import_react3.useRef)(idlePlaylistSession());
+  const [retry, setRetry] = (0, import_react3.useState)(0);
+  (0, import_react3.useEffect)(() => {
+    if (!enabled) return;
+    const intent = { signature, generation: surfaceGeneration };
+    if (!shouldPrepare(session.current, intent)) return;
+    let ok;
+    try {
+      if (playlist.unsupported.length > 0 || items.length === 0) {
+        ok = Media3.setPlaylist({ items: [], unsupported: [] }) !== false;
+      } else {
+        const start = (0, import_video_core3.projectTimeToWindow)(items, playheadRef.current) ?? {
+          windowIndex: 0,
+          positionUs: 0
+        };
+        ok = Media3.setPlaylist(playlist, start) !== false;
+      }
+    } catch {
+      ok = false;
+    }
+    session.current = afterPrepare(session.current, intent, ok);
+  }, [signature, items, playlist, enabled, surfaceGeneration, retry]);
+  (0, import_react3.useEffect)(() => {
+    if (!enabled) return;
+    if (!session.current.pending) return;
+    const id = setInterval(() => setRetry((n) => n + 1), RETRY_INTERVAL_MS);
+    return () => clearInterval(id);
+  }, [enabled, retry, surfaceGeneration, signature]);
+  const stallRef = (0, import_react3.useRef)(null);
+  const surfaceGenerationRef = (0, import_react3.useRef)(surfaceGeneration ?? 0);
+  surfaceGenerationRef.current = surfaceGeneration ?? 0;
+  const lifecycleRef = (0, import_react3.useRef)(null);
+  if (lifecycleRef.current === null) {
+    lifecycleRef.current = createPlaybackLifecycle({
+      pause: () => Media3.pause(),
+      release: () => Media3.release()
+    });
+  }
+  const lifecycle = lifecycleRef.current;
+  const [lifecycleEpoch, setLifecycleEpoch] = (0, import_react3.useState)(lifecycle.epoch);
+  (0, import_react3.useEffect)(() => {
+    const subscription = import_react_native3.AppState.addEventListener("change", (next) => {
+      if (next === "active") {
+        lifecycle.resume();
+        setLifecycleEpoch(lifecycle.epoch);
+        return;
+      }
+      lifecycle.suspend("background");
+      setLifecycleEpoch(lifecycle.epoch);
+      setPlaying(false);
+    });
+    return () => subscription.remove();
+  }, [lifecycle]);
+  (0, import_react3.useEffect)(() => {
+    return () => {
+      lifecycle.teardown("unmount");
+    };
+  }, [lifecycle]);
+  const healthy = (0, import_react3.useRef)(null);
+  const [stall, setStall] = (0, import_react3.useState)(null);
+  const lastMeaning = (0, import_react3.useRef)("");
+  (0, import_react3.useEffect)(() => {
+    if (!enabled) return;
+    const epoch = lifecycle.epoch;
+    const id = setInterval(() => {
+      if (!lifecycle.accepts(epoch)) return;
+      const snapshot = Media3.state();
+      const meaning = [
+        snapshot.playing,
+        snapshot.ready,
+        snapshot.buffering,
+        snapshot.ended,
+        snapshot.released,
+        snapshot.width,
+        snapshot.height,
+        snapshot.windowIndex,
+        snapshot.windowCount,
+        snapshot.errorCount,
+        snapshot.errorMessage,
+        snapshot.rateConstrained
+      ].join("|");
+      if (meaning !== lastMeaning.current) {
+        lastMeaning.current = meaning;
+        setState(snapshot);
+        setPlaying(snapshot.playing);
+      }
+      const sample = {
+        atMs: Date.now(),
+        positionUs: snapshot.windowPositionUs,
+        framesOffered: snapshot.framesOffered,
+        framesAvailable: snapshot.framesAvailable,
+        // Latched is not reported directly: what arrived, less what is still
+        // waiting, is the count the consumer has actually taken.
+        framesLatched: snapshot.framesAvailable - snapshot.pendingDepth,
+        framesRejected: snapshot.framesRejected,
+        pendingGeneration: snapshot.pendingGeneration,
+        consumerGeneration: surfaceGenerationRef.current
+      };
+      const since = healthy.current;
+      if (since === null) {
+        healthy.current = sample;
+      } else if (classifyStall(since, sample) === null) {
+        healthy.current = sample;
+        if (stallRef.current !== null) setStall(null);
+      } else if (shouldRecover(since, sample)) {
+        const kind = classifyStall(since, sample);
+        healthy.current = sample;
+        stallRef.current = kind;
+        setStall(kind);
+        session.current = { ...session.current, pending: true };
+        setRetry((n) => n + 1);
+      }
+      if (!snapshot.playing) return;
+      const projectUs = (0, import_video_core3.windowToProjectTime)(
+        itemsRef.current,
+        snapshot.windowIndex,
+        snapshot.windowPositionUs
+      );
+      if (projectUs !== null) options.onPositionUs?.(projectUs);
+    }, pollMs);
+    return () => clearInterval(id);
+  }, [enabled, pollMs, lifecycle, lifecycleEpoch]);
+  const lastSeekRef = (0, import_react3.useRef)(null);
+  const seek = (0, import_react3.useCallback)((timeUs) => {
+    const target = (0, import_video_core3.projectTimeToWindow)(itemsRef.current, timeUs);
+    if (!target) return;
+    lastSeekRef.current = {
+      globalUs: Math.round(timeUs),
+      windowIndex: target.windowIndex,
+      localUs: target.positionUs
+    };
+    Media3.seekToWindow(target.windowIndex, target.positionUs);
+  }, []);
+  const positionUs = (0, import_react3.useCallback)(() => {
+    const snapshot = Media3.state();
+    if (snapshot.released || itemsRef.current.length === 0) return null;
+    return (0, import_video_core3.windowToProjectTime)(
+      itemsRef.current,
+      snapshot.windowIndex,
+      snapshot.windowPositionUs
+    );
+  }, []);
+  const durationUsRef = (0, import_react3.useRef)(0);
+  durationUsRef.current = (0, import_video_core3.projectDuration)(project);
+  const play = (0, import_react3.useCallback)(() => {
+    const snapshot = Media3.state();
+    const intent = (0, import_video_core3.playIntent)({
+      positionUs: (0, import_video_core3.windowToProjectTime)(
+        itemsRef.current,
+        snapshot.windowIndex,
+        snapshot.windowPositionUs
+      ) ?? 0,
+      durationUs: durationUsRef.current,
+      playbackState: snapshot.playbackState,
+      ended: snapshot.ended
+    });
+    if (intent.seekToUs !== null) {
+      const target = (0, import_video_core3.projectTimeToWindow)(itemsRef.current, intent.seekToUs);
+      if (target) Media3.seekToWindow(target.windowIndex, target.positionUs);
+    }
+    if (!intent.play) return intent;
+    if (lifecycle.released) return intent;
+    Media3.play();
+    setPlaying(true);
+    return intent;
+  }, [lifecycle]);
+  return {
+    playing,
+    play,
+    get lastSeek() {
+      return lastSeekRef.current;
+    },
+    positionUs,
+    effectiveRate: state?.effectiveRate ?? 1,
+    pause: (0, import_react3.useCallback)(() => {
+      Media3.pause();
+      setPlaying(false);
+    }, []),
+    setRate: (0, import_react3.useCallback)((rate) => Media3.setRate(rate), []),
+    seek,
+    state,
+    items,
+    unsupported: playlist.unsupported,
+    divergenceUs,
+    lifecycle,
+    stall
+  };
+}
+
+// src/thumbnailProvider.ts
+var import_video_core4 = require("@pictor-sdk/video-core");
+var DEFAULT_CAPACITY = 240;
+var DEFAULT_POLL_MS2 = 16;
+function createAndroidThumbnailProvider(options = {}) {
+  const policy = (0, import_video_core4.createThumbnailPolicy)({
+    capacity: options.capacity ?? DEFAULT_CAPACITY
+  });
+  const pollMs = options.pollMs ?? DEFAULT_POLL_MS2;
+  const tokens = /* @__PURE__ */ new Map();
+  function uriOf2(source) {
+    if (typeof source === "string") return source;
+    if (source && typeof source === "object" && "uri" in source) {
+      const uri = source.uri;
+      if (typeof uri === "string") return uri;
+    }
+    throw new Error(
+      `@pictor-sdk/video-android: a thumbnail source is not a URI. Normalise host media to { kind: 'uri', uri } first. Received: ${JSON.stringify(source)}`
+    );
+  }
+  return {
+    async request(request, signal) {
+      const key = (0, import_video_core4.thumbnailKey)(request);
+      const cached = policy.get(request);
+      if (cached !== void 0) {
+        return { image: cached, sourceTimeUs: request.sourceTimeUs, size: { width: 0, height: 0 } };
+      }
+      if (signal?.aborted) return null;
+      const native = requireNative();
+      policy.begin(request);
+      const token = native.thumbnailRequest(
+        uriOf2(request.source),
+        request.sourceTimeUs,
+        request.widthPx
+      );
+      tokens.set(key, token);
+      const stop = () => {
+        native.thumbnailCancel(token);
+        tokens.delete(key);
+        policy.cancel(request);
+      };
+      signal?.addEventListener("abort", stop, { once: true });
+      try {
+        for (; ; ) {
+          if (signal?.aborted) return null;
+          const data = native.thumbnailTake(token);
+          if (data !== null && data !== void 0) {
+            tokens.delete(key);
+            const evicted = policy.store(request, `data:image/jpeg;base64,${data}`);
+            void evicted;
+            return {
+              image: policy.get(request),
+              sourceTimeUs: request.sourceTimeUs,
+              size: { width: request.widthPx, height: 0 }
+            };
+          }
+          const error = native.thumbnailError(token);
+          if (error !== null && error !== void 0) {
+            tokens.delete(key);
+            policy.cancel(request);
+            return null;
+          }
+          if (!native.thumbnailRunning(token)) {
+            tokens.delete(key);
+            policy.cancel(request);
+            return null;
+          }
+          await new Promise((resolve) => setTimeout(() => resolve(), pollMs));
+        }
+      } finally {
+        signal?.removeEventListener("abort", stop);
+      }
+    },
+    releaseSource(source) {
+      policy.evictSource(source);
+      requireNative().thumbnailReleaseSource(uriOf2(source));
+    },
+    release() {
+      for (const token of tokens.values()) requireNative().thumbnailCancel(token);
+      tokens.clear();
+      policy.clear();
+      requireNative().thumbnailReleaseAll();
+    }
+  };
+}
+function thumbnailCounters() {
+  return requireNative().thumbnailCounters();
+}
+
+// src/convergence.ts
+var CONVERGED_RUN = 8;
+var MAX_RECOVERY_SAMPLES = 600;
+function beginPhase(phase) {
+  return {
+    phase,
+    samples: [],
+    run: 0,
+    worstUs: 0,
+    recoverySamples: 0,
+    converged: phase === "steady",
+    timedOut: false
+  };
+}
+function observe(state, offsetUs, boundUs) {
+  if (state.converged) {
+    return { state, bucket: "steady" };
+  }
+  const magnitude = Math.abs(offsetUs);
+  const next = {
+    ...state,
+    samples: [...state.samples, offsetUs],
+    recoverySamples: state.recoverySamples + 1,
+    worstUs: Math.max(state.worstUs, magnitude),
+    run: magnitude <= boundUs ? state.run + 1 : 0
+  };
+  if (next.run >= CONVERGED_RUN) {
+    next.converged = true;
+  } else if (next.recoverySamples >= MAX_RECOVERY_SAMPLES) {
+    next.converged = true;
+    next.timedOut = true;
+  }
+  return { state: next, bucket: state.phase };
+}
+function recoveryFrames(state) {
+  return state.converged ? state.recoverySamples : null;
+}
+
+// src/exportJob.ts
+var import_video_core5 = require("@pictor-sdk/video-core");
+var EXPORT_STAGES = [
+  "resolving",
+  "overlays",
+  "shards",
+  "cadence",
+  "audio",
+  "concatenating",
+  "finalising",
+  "publishing"
+];
+var counter = 0;
+function createExportJobs(options) {
+  const now = options.now ?? (() => Date.now());
+  let active = null;
+  let cancelledAt = null;
+  let cancelRequested = false;
+  let settled = false;
+  let accepted = 0;
+  let succeeded = 0;
+  let cancelled = 0;
+  let failed = 0;
+  const clear = () => {
+    active = null;
+    cancelRequested = false;
+    cancelledAt = null;
+    settled = true;
+  };
+  return {
+    get active() {
+      return active;
+    },
+    get counts() {
+      return {
+        accepted,
+        succeeded,
+        cancelled,
+        failed,
+        active: active === null ? 0 : 1
+      };
+    },
+    async run(body) {
+      if (active !== null) {
+        throw new Error(
+          `createMedia3VideoExporter: an export is already running (${active}); cancel it before starting another`
+        );
+      }
+      counter += 1;
+      accepted += 1;
+      const id = `export_${now().toString(36)}_${counter.toString(36)}`;
+      active = id;
+      cancelRequested = false;
+      cancelledAt = null;
+      settled = false;
+      const job = {
+        id,
+        checkpoint(stage) {
+          if (cancelRequested) {
+            cancelledAt = stage;
+            throw new import_video_core5.VideoExportCancelled(id, stage);
+          }
+        },
+        progress(value, deliver) {
+          if (settled || cancelRequested) return;
+          deliver(value);
+        }
+      };
+      try {
+        const result = await body(job);
+        if (cancelRequested) {
+          throw new import_video_core5.VideoExportCancelled(id, cancelledAt ?? "finalising");
+        }
+        clear();
+        succeeded += 1;
+        return result;
+      } catch (error) {
+        const wasCancelled = cancelRequested;
+        const stage = cancelledAt ?? "finalising";
+        clear();
+        if (wasCancelled) cancelled += 1;
+        else failed += 1;
+        if (wasCancelled) {
+          if (error instanceof import_video_core5.VideoExportCancelled) throw error;
+          throw new import_video_core5.VideoExportCancelled(id, stage);
+        }
+        throw error;
+      }
+    },
+    cancel() {
+      if (active === null || cancelRequested) return;
+      cancelRequested = true;
+      options.cancelNative(active);
+    }
+  };
+}
+
+// src/mixSources.ts
+function mixSpanContext(project, spanId) {
+  const isClip = project.clips.some((clip) => clip.id === spanId);
+  const isAudio = project.audio.some((item) => item.id === spanId);
+  if (isClip === isAudio) return null;
+  return isClip ? { kind: "clip", clipId: spanId } : { kind: "audio", audioId: spanId };
+}
+function resolveMixSources(project, program, resolveSource) {
+  const uris = {};
+  const unresolved = [];
+  for (const span of program.spans) {
+    if (span.silent || span.source === null) continue;
+    const context = mixSpanContext(project, span.id);
+    if (context === null) {
+      unresolved.push(
+        `audio span '${span.id}' matches no clip or audio item, so it has no owner to resolve against`
+      );
+      continue;
+    }
+    const uri = resolveSource(span.source, context);
+    if (typeof uri !== "string" || uri.length === 0) {
+      unresolved.push(`audio span '${span.id}' could not be resolved to a readable source`);
+      continue;
+    }
+    uris[span.id] = uri;
+  }
+  return { uris, unresolved };
+}
+
+// src/exportDestination.ts
+function describeTarget(path) {
+  const trimmed = path.replace(/\/+$/, "");
+  const name = trimmed.slice(trimmed.lastIndexOf("/") + 1);
+  return name.length > 0 ? name : "(unnamed)";
+}
+var KNOWN_SCHEMES = {
+  "content:": "a content uri is not a filesystem path, so it cannot be published atomically",
+  "http:": "a remote destination cannot be written to directly",
+  "https:": "a remote destination cannot be written to directly",
+  "android.resource:": "app resources are read-only",
+  "asset:": "bundled assets are read-only"
+};
+function resolveDestination(destination) {
+  if (destination === void 0) return { destination: { kind: "temporary" }, reasons: [] };
+  if (destination.kind === "temporary") return { destination: { kind: "temporary" }, reasons: [] };
+  if (destination.kind !== "file") {
+    return {
+      destination: null,
+      reasons: [`destination kind '${String(destination.kind)}' is not supported`]
+    };
+  }
+  const uri = destination.uri;
+  if (typeof uri !== "string" || uri.trim().length === 0) {
+    return { destination: null, reasons: ["the file destination has no uri"] };
+  }
+  const scheme = /^[a-zA-Z][a-zA-Z0-9+.-]*:/.exec(uri)?.[0]?.toLowerCase();
+  if (scheme !== void 0 && scheme !== "file:") {
+    const known = KNOWN_SCHEMES[scheme];
+    return {
+      destination: null,
+      reasons: [
+        known !== void 0 ? `destination scheme '${scheme}' is not supported: ${known}` : `destination scheme '${scheme}' is not supported; only file: is`
+      ]
+    };
+  }
+  if (scheme === void 0) {
+    return { destination: null, reasons: ["the file destination must be a file: uri"] };
+  }
+  let path;
+  try {
+    const withoutScheme = uri.slice("file:".length);
+    const rest = withoutScheme.startsWith("//") ? withoutScheme.slice(2) : withoutScheme;
+    if (withoutScheme.startsWith("//") && !rest.startsWith("/")) {
+      return {
+        destination: null,
+        reasons: ["the file destination names a remote host, which is not supported"]
+      };
+    }
+    path = decodeURIComponent(rest);
+  } catch {
+    return { destination: null, reasons: ["the file destination uri is malformed"] };
+  }
+  if (!path.startsWith("/")) {
+    return { destination: null, reasons: ["the file destination must be an absolute path"] };
+  }
+  if (path.endsWith("/")) {
+    return {
+      destination: null,
+      reasons: ["the file destination is a directory; it must name the file to write"]
+    };
+  }
+  if (path.includes("\0")) {
+    return { destination: null, reasons: ["the file destination uri is malformed"] };
+  }
+  if (path.split("/").some((segment) => segment === "..")) {
+    return { destination: null, reasons: ['the file destination must not contain ".."'] };
+  }
+  const name = describeTarget(path);
+  if (name === "." || name === "(unnamed)") {
+    return {
+      destination: null,
+      reasons: ["the file destination is a directory; it must name the file to write"]
+    };
+  }
+  return {
+    destination: { kind: "file", path, overwrite: destination.overwrite === true },
+    reasons: []
+  };
+}
+
+// src/exportProgress.ts
+var STALL_GRACE_MS = 7e3;
+var MAX_OBSERVED_HEARTBEAT_GAP_MS = 2046;
+var AUDIO_UNIT = 1 / 512;
+var MUX_UNITS = 24;
+var PUBLISH_UNITS = 8;
+function planProgressWeights(input) {
+  const shardUnits = input.shards.map((s) => Math.max(0, s.frames));
+  const audioUnits = input.audioSamples > 0 ? input.audioSamples * AUDIO_UNIT : 0;
+  const total = shardUnits.reduce((a, b) => a + b, 0) + audioUnits + MUX_UNITS + PUBLISH_UNITS;
+  return {
+    shardWeights: shardUnits.map((u) => u / total),
+    audioWeight: audioUnits / total,
+    muxWeight: MUX_UNITS / total,
+    publishWeight: PUBLISH_UNITS / total,
+    durationUs: Math.max(0, input.durationUs),
+    shardFrames: shardUnits,
+    audioSamples: Math.max(0, input.audioSamples)
+  };
+}
+function createProgressReporter(options) {
+  const now = options.now ?? (() => Date.now());
+  const throttleMs = options.throttleMs ?? 120;
+  const plan = options.plan;
+  const shardDone = plan.shardWeights.map(() => 0);
+  let audioDone = 0;
+  let muxDone = 0;
+  let publishDone = 0;
+  let highest = 0;
+  let began = false;
+  let finished = false;
+  let stopped = false;
+  let lastEmitMs = Number.NEGATIVE_INFINITY;
+  let batching = 0;
+  let batchForce = false;
+  const fraction = () => {
+    let sum = 0;
+    for (let i = 0; i < shardDone.length; i += 1) {
+      sum += plan.shardWeights[i] * shardDone[i];
+    }
+    return sum + plan.audioWeight * audioDone + plan.muxWeight * muxDone + plan.publishWeight * publishDone;
+  };
+  const emit = (value, force) => {
+    if (stopped || !began) return;
+    if (batching > 0) {
+      batchForce = batchForce || force;
+      return;
+    }
+    const next = Math.max(highest, Math.min(1, value));
+    const at = now();
+    if (!force && at - lastEmitMs < throttleMs) return;
+    if (!force && began && next === highest) return;
+    highest = next;
+    lastEmitMs = at;
+    try {
+      options.onProgress?.({
+        progress: highest,
+        time: Math.min(plan.durationUs, Math.round(plan.durationUs * highest))
+      });
+    } catch {
+    }
+  };
+  return {
+    begin() {
+      if (began || stopped) return;
+      began = true;
+      emit(0, true);
+    },
+    shard(index, framesDone) {
+      if (finished || stopped) return;
+      if (index < 0 || index >= shardDone.length) return;
+      const total = Math.max(1, plan.shardFrames[index] ?? 1);
+      shardDone[index] = Math.max(shardDone[index], Math.min(1, framesDone / total));
+      emit(fraction(), false);
+    },
+    audio(samplesDone) {
+      if (finished || stopped) return;
+      const total = Math.max(1, plan.audioSamples);
+      audioDone = Math.max(audioDone, Math.min(1, samplesDone / total));
+      emit(fraction(), false);
+    },
+    muxed() {
+      if (finished || stopped) return;
+      muxDone = 1;
+      emit(fraction(), true);
+    },
+    complete() {
+      if (finished || stopped) return;
+      finished = true;
+      publishDone = 1;
+      emit(1, true);
+    },
+    batch(body) {
+      batching += 1;
+      try {
+        body();
+      } finally {
+        batching -= 1;
+      }
+      const force = batchForce;
+      batchForce = false;
+      emit(finished ? 1 : fraction(), force);
+    },
+    stop() {
+      stopped = true;
+    }
+  };
+}
+function createStallWatchdog(options = {}) {
+  const thresholdMs = options.thresholdMs ?? STALL_GRACE_MS;
+  let lastStage = null;
+  let lastUnits = 0;
+  let lastAtMs = 0;
+  let fired = false;
+  return {
+    advanced(stage, units, atMs) {
+      lastStage = stage;
+      lastUnits = units;
+      lastAtMs = atMs;
+    },
+    stalledFor(atMs) {
+      if (fired || lastStage === null) return null;
+      const idleMs = atMs - lastAtMs;
+      if (idleMs < thresholdMs) return null;
+      fired = true;
+      return { stage: lastStage, units: lastUnits, idleMs };
+    }
+  };
+}
+
+// src/exportProgressPump.ts
+function stageOf(snapshot, plan) {
+  if (snapshot.muxed) return "publishing";
+  const shardsDone = plan.shardFrames.every(
+    (total, index) => (snapshot.shards[index] ?? 0) >= total
+  );
+  if (!shardsDone) return "shards";
+  if (snapshot.audioPlanned > 0 && snapshot.audioSamples < snapshot.audioPlanned) return "audio";
+  return "concatenating";
+}
+function createProgressPump(options) {
+  const now = options.now ?? (() => Date.now());
+  const pollMs = options.pollMs ?? 125;
+  const plan = options.plan;
+  const reporter = createProgressReporter({
+    plan,
+    durationUs: options.durationUs,
+    onProgress: options.onProgress,
+    // The reporter's own throttle is the poll interval: a tick that finds
+    // nothing new should not be able to spend a crossing saying so.
+    throttleMs: pollMs,
+    now
+  });
+  const watchdog = createStallWatchdog({ thresholdMs: options.thresholdMs ?? STALL_GRACE_MS });
+  let lastBeats = -1;
+  let stopped = false;
+  let stalled = false;
+  return {
+    pollMs,
+    begin() {
+      reporter.begin();
+      watchdog.advanced("resolving", 0, now());
+    },
+    tick() {
+      if (stopped || stalled) return;
+      const snapshot = options.read();
+      reporter.batch(() => {
+        for (let i = 0; i < plan.shardFrames.length; i += 1) {
+          reporter.shard(i, snapshot.shards[i] ?? 0);
+        }
+        if (snapshot.audioPlanned > 0 && plan.audioSamples > 0) {
+          const fraction = Math.min(1, snapshot.audioSamples / snapshot.audioPlanned);
+          reporter.audio(plan.audioSamples * fraction);
+        }
+        if (snapshot.muxed) reporter.muxed();
+      });
+      const at = now();
+      if (snapshot.beats !== lastBeats) {
+        lastBeats = snapshot.beats;
+        watchdog.advanced(stageOf(snapshot, plan), snapshot.beats, at);
+      }
+      const verdict = watchdog.stalledFor(at);
+      if (verdict) {
+        stalled = true;
+        options.onStall(verdict);
+      }
+    },
+    complete() {
+      if (stopped) return;
+      reporter.complete();
+    },
+    stop() {
+      stopped = true;
+      reporter.stop();
+    }
+  };
+}
+
+// src/exporter.ts
+var import_video_core6 = require("@pictor-sdk/video-core");
+function nativeModule() {
+  if (!NativePictorVideo_default) {
+    throw new VideoExportRejected(["the Pictor video native module is not installed"]);
+  }
+  return NativePictorVideo_default;
+}
+var VideoExportRejected = class extends Error {
+  constructor(reasons) {
+    super(`export rejected: ${reasons.join("; ")}`);
+    this.name = "VideoExportRejected";
+    this.reasons = reasons;
+  }
+};
+var DEFAULT_FPS = 30;
+function describeUnsupported(project, spec) {
+  const reasons = [];
+  for (const clip of project.clips) {
+    if (clip.kind === "photo") {
+      reasons.push(`clip '${clip.id}' is a photo, which this exporter does not encode yet`);
+      continue;
+    }
+  }
+  if (spec.format !== void 0 && spec.format !== "mp4") {
+    reasons.push(`format '${spec.format}' is not supported; this exporter writes mp4`);
+  }
+  if (spec.scale !== void 0 && spec.scale !== 1) {
+    reasons.push(`scale ${spec.scale} is not supported yet; only 1 is`);
+  }
+  if (spec.fps !== void 0 && spec.fps !== DEFAULT_FPS) {
+    reasons.push(`fps ${spec.fps} is not supported yet; only ${DEFAULT_FPS} is`);
+  }
+  if (spec.bitrate !== void 0) {
+    reasons.push("bitrate is not supported yet; the encoder default is used");
+  }
+  return reasons;
+}
+function createMedia3VideoExporter(options) {
+  const jobs = createExportJobs({
+    cancelNative: (jobId) => {
+      nativeModule().exportCancelJob(jobId);
+    }
+  });
+  return {
+    async export(project, spec, onProgress) {
+      return jobs.run(async (job) => {
+        job.checkpoint("resolving");
+        const issues = (0, import_video_core6.validateProject)(project);
+        if (issues.length > 0) {
+          throw new VideoExportRejected(issues.map((issue) => issue.message));
+        }
+        const unsupported = describeUnsupported(project, spec);
+        if (unsupported.length > 0) throw new VideoExportRejected(unsupported);
+        const decision = resolveDestination(spec.destination);
+        if (decision.destination === null) throw new VideoExportRejected(decision.reasons);
+        const destination = decision.destination;
+        const playable = project.clips.filter((clip) => (0, import_video_core6.isPlayableWindow)(clip));
+        if (playable.length === 0) throw new VideoExportRejected(["the project has no playable clips"]);
+        if (!((0, import_video_core6.projectDuration)(project) > 0)) {
+          throw new VideoExportRejected(["the project has no duration"]);
+        }
+        const uris = [];
+        const unresolved = [];
+        for (const clip of playable) {
+          const uri = options.resolveSource(clip.source, { kind: "clip", clipId: clip.id });
+          if (typeof uri !== "string" || uri.length === 0) {
+            unresolved.push(`clip '${clip.id}' could not be resolved to a readable source`);
+            continue;
+          }
+          uris.push(uri);
+        }
+        if (unresolved.length > 0) throw new VideoExportRejected(unresolved);
+        const fps = DEFAULT_FPS;
+        const placements = (0, import_video_core6.layout)(project);
+        const requests = playable.map((clip) => ({
+          sourceStartUs: clip.sourceIn,
+          sourceEndUs: clip.sourceOut,
+          speed: clip.speed,
+          sourceFps: clip.metadata.fps ?? fps,
+          targetFps: fps
+        }));
+        const plan = (0, import_video_core6.planClipShards)(requests, fps);
+        const program = (0, import_video_core6.compileVideoSceneProgram)(project);
+        if (program.segments.length === 0) {
+          throw new VideoExportRejected(["the compiled program has no segments"]);
+        }
+        void placements;
+        const named = /* @__PURE__ */ new Set();
+        for (const segment of program.segments) {
+          for (const command of segment.commands) {
+            if (command.op === "overlay") named.add(command.overlayId);
+          }
+        }
+        const overlayPlan = options.prepareOverlays ? options.prepareOverlays(program, project.size, 1) : {
+          resources: [],
+          pending: [],
+          invalid: [...named].map((overlayId) => ({
+            overlayId,
+            kind: "unknown",
+            reason: "no prepareOverlays was supplied, so this overlay has no portable form"
+          }))
+        };
+        job.checkpoint("overlays");
+        const stagedNow = overlayPlan.resources.map((resource) => resource.file);
+        if (overlayPlan.pending.length > 0) {
+          options.releaseResources?.(stagedNow);
+          throw new VideoExportRejected(
+            overlayPlan.pending.map(
+              (id) => `overlay '${id}' is still preparing; export would omit it`
+            )
+          );
+        }
+        if (overlayPlan.invalid.length > 0) {
+          options.releaseResources?.(stagedNow);
+          throw new VideoExportRejected(
+            overlayPlan.invalid.map(
+              (bad) => `overlay '${bad.overlayId}' (${bad.kind}): ${bad.reason}`
+            )
+          );
+        }
+        const resources = overlayPlan.resources;
+        const shards = plan.map((shard, index) => {
+          const clip = playable[index];
+          const cadence = cadenceFor(shard.plan.frames);
+          return {
+            uri: uris[index],
+            startMs: Math.round(clip.sourceIn / 1e3),
+            endMs: Math.round(clip.sourceOut / 1e3),
+            speed: clip.speed,
+            timelineOffsetUs: shard.timelineOffsetUs,
+            /*
+                        The shard's own audio is dropped and replaced with generated silence.
+            
+                        Not because anything wants that silence — the final mux takes only
+                        the video track from this pipeline — but because Media3 drives its
+                        speed path through audio, and a video-only item at any rate other
+                        than 1 stalls with "no output sample written". So the track exists to
+                        satisfy the re-timing and is discarded.
+            
+                        What matters is that the *source's* audio never enters this pipeline:
+                        a per-shard audio track has to be re-encoded to concatenate, which is
+                        what put a second generation on everything the user hears.
+                      */
+            forceAudioTrack: true,
+            removeAudio: true,
+            emitsPerInput: cadence.emitsPerInput,
+            outputPtsUs: cadence.outputPtsUs,
+            spanUs: Math.round(shard.plan.frameCount * 1e6 / fps)
+          };
+        });
+        const mixProgram = (0, import_video_core6.compileAudioMixProgram)(project);
+        const mixProblems = (0, import_video_core6.validateAudioMixProgram)(mixProgram);
+        if (mixProblems.length > 0) throw new VideoExportRejected(mixProblems);
+        const resolved = resolveMixSources(project, mixProgram, options.resolveSource);
+        const mixUris = resolved.uris;
+        if (resolved.unresolved.length > 0) throw new VideoExportRejected(resolved.unresolved);
+        job.checkpoint("resolving");
+        job.checkpoint("overlays");
+        const staged = resources.map((resource) => resource.file);
+        const durationUs = (0, import_video_core6.projectDuration)(project);
+        const progressPlan = planProgressWeights({
+          shards: plan.map((shard) => ({ frames: shard.plan.frameCount })),
+          audioSamples: mixProgram.spans.some((span) => !span.silent) ? Math.max(0, mixProgram.durationUs) : 0,
+          durationUs
+        });
+        const stalled = { at: null };
+        const pump = createProgressPump({
+          plan: progressPlan,
+          durationUs,
+          read: () => JSON.parse(nativeModule().exportProgressSnapshot()),
+          // Delivered through the job, so nothing arrives after settlement: a
+          // host that has already shown a result must not be told 90%.
+          onProgress: onProgress ? (value) => {
+            job.progress(value.progress, () => onProgress(value));
+          } : void 0,
+          onStall: (verdict) => {
+            stalled.at = { stage: String(verdict.stage), idleMs: verdict.idleMs };
+            nativeModule().exportCancelJob(job.id);
+          },
+          thresholdMs: options.stallGraceMs,
+          pollMs: options.progressPollMs
+        });
+        pump.begin();
+        const ticker = setInterval(() => {
+          pump.tick();
+        }, pump.pollMs);
+        let outcome;
+        try {
+          outcome = JSON.parse(
+            await nativeModule().exportRunProjectAsync(
+              job.id,
+              JSON.stringify(shards),
+              JSON.stringify({
+                version: import_video_core6.VIDEO_SCENE_PROGRAM_VERSION,
+                projectSize: { width: project.size.width, height: project.size.height },
+                durationUs: program.durationUs,
+                segments: program.segments
+              }),
+              JSON.stringify(resources),
+              JSON.stringify(mixProgram),
+              JSON.stringify(mixUris),
+              /* timeoutSeconds= */
+              600,
+              destination.kind === "file" ? JSON.stringify({
+                kind: "file",
+                path: destination.path,
+                overwrite: destination.overwrite
+              }) : ""
+            )
+          );
+        } finally {
+          clearInterval(ticker);
+          options.releaseResources?.(staged);
+        }
+        const wedged = stalled.at;
+        if (wedged) {
+          pump.stop();
+          throw new import_video_core6.VideoExportStalled(job.id, wedged.stage, wedged.idleMs);
+        }
+        const cancelledDuring = /^cancelled during (\w+)/.exec(outcome.error ?? "");
+        if (!outcome.ok && cancelledDuring) {
+          pump.stop();
+          throw new import_video_core6.VideoExportCancelled(job.id, cancelledDuring[1]);
+        }
+        if (!outcome.ok) {
+          pump.stop();
+          const error = outcome.error || "the export failed";
+          if (isRefusal(error)) throw new VideoExportRejected([error]);
+          throw new import_video_core6.VideoExportFailed(job.id, "encoding", error);
+        }
+        job.checkpoint("publishing");
+        const probe = JSON.parse(nativeModule().exportProbeOutput(outcome.uri));
+        if (!probe.readable) {
+          pump.stop();
+          throw new import_video_core6.VideoExportFailed(
+            job.id,
+            "publishing",
+            `${describeTarget(outcome.uri)} could not be read back: ${probe.error ?? "no video track"}`
+          );
+        }
+        pump.complete();
+        pump.stop();
+        if (destination.kind === "file") return { kind: "file", uri: outcome.uri };
+        const temporaryUri = outcome.uri;
+        return {
+          kind: "temporary",
+          uri: temporaryUri,
+          release: async () => {
+            await Promise.resolve();
+            nativeModule().exportReleaseTemporaryOutput(temporaryUri);
+          }
+        };
+      });
+    },
+    /**
+     * Ask the running export to stop.
+     *
+     * Idempotent, and a no-op when nothing is running. Reaches the native job
+     * before the promise settles: a Transformer nobody is listening to still
+     * encodes, still writes and still holds its codecs, so rejecting in
+     * JavaScript alone would show a cancelled state over a running export.
+     */
+    cancel() {
+      jobs.cancel();
+    }
+  };
+}
+var REFUSAL_PATTERNS = [
+  /^program rejected/,
+  /^overlay resources? /,
+  /^overlay resource /,
+  /^no shards/,
+  /already exists; pass overwrite/,
+  /^the directory for /,
+  /^the destination /,
+  /cannot be written without overwrite/,
+  /^the staged file could not be read back/
+];
+function isRefusal(error) {
+  return REFUSAL_PATTERNS.some((pattern) => pattern.test(error));
+}
+function cadenceFor(frames) {
+  const first = frames[0].sourceFrameIndex;
+  const last = frames[frames.length - 1].sourceFrameIndex;
+  const emitsPerInput = [];
+  for (let i = 0; i <= last - first; i += 1) emitsPerInput.push(0);
+  const outputPtsUs = [];
+  for (const frame of frames) {
+    const slot = frame.sourceFrameIndex - first;
+    emitsPerInput[slot] = (emitsPerInput[slot] ?? 0) + 1;
+    outputPtsUs.push(frame.outputPtsUs);
+  }
+  return { emitsPerInput, outputPtsUs };
+}
+
+// src/mediaStore.ts
+var MediaSaveFailed = class extends Error {
+  constructor(reason) {
+    super(`save failed: ${reason}`);
+    this.name = "MediaSaveFailed";
+    this.reason = reason;
+  }
+};
+var MediaSaveCancelled = class extends Error {
+  constructor() {
+    super("save cancelled");
+    this.name = "MediaSaveCancelled";
+  }
+};
+function shareSavedMedia(uri) {
+  if (!NativePictorVideo_default) {
+    return { ok: false, noTargets: false, reason: "sharing is not available" };
+  }
+  if (!uri.startsWith("content://")) {
+    return { ok: false, noTargets: false, reason: "only a saved video can be shared" };
+  }
+  const result = JSON.parse(NativePictorVideo_default.mediaShare(uri));
+  return {
+    ok: result.ok === true,
+    noTargets: result.noTargets === true,
+    reason: result.error ?? ""
+  };
+}
+var counter2 = 0;
+function createMediaStoreSaver() {
+  let active = null;
+  const native = () => {
+    if (!NativePictorVideo_default) {
+      throw new MediaSaveFailed("the Pictor video native module is not installed");
+    }
+    return NativePictorVideo_default;
+  };
+  return {
+    async save(sourceUri) {
+      if (active !== null) {
+        throw new MediaSaveFailed("a save is already running");
+      }
+      counter2 += 1;
+      const id = `save_${counter2.toString(36)}`;
+      active = id;
+      let outcome;
+      try {
+        outcome = JSON.parse(await native().mediaSaveAsync(id, sourceUri));
+      } finally {
+        active = null;
+      }
+      if (outcome.cancelled === true) throw new MediaSaveCancelled();
+      if (!outcome.ok || typeof outcome.uri !== "string") {
+        throw new MediaSaveFailed(outcome.error ?? "the file could not be saved");
+      }
+      return {
+        uri: outcome.uri,
+        displayName: outcome.displayName ?? "",
+        location: outcome.location ?? ""
+      };
+    },
+    cancel() {
+      if (active === null) return;
+      native().mediaSaveCancel(active);
+    }
+  };
+}
+function sweepPendingMediaSaves() {
+  if (!NativePictorVideo_default) return { swept: 0, inspected: 0, skipped: 0 };
+  const result = JSON.parse(NativePictorVideo_default.mediaSaveSweepPending());
+  return {
+    swept: result.swept ?? 0,
+    inspected: result.inspected ?? 0,
+    skipped: result.skipped ?? 0
+  };
+}
+
+// src/overlayStaging.ts
+var installed = false;
+function installOverlayStaging() {
+  if (installed && global.__pictorOverlayStaging !== void 0) return true;
+  installed = requireNative().installOverlayStaging();
+  return installed && global.__pictorOverlayStaging !== void 0;
+}
+function host() {
+  const h = global.__pictorOverlayStaging;
+  if (h === void 0) {
+    throw new Error("@pictor-sdk/video-android: overlay staging is not installed");
+  }
+  return h;
+}
+function sweepOverlayStaging() {
+  if (!installOverlayStaging()) return 0;
+  return host().sweep();
+}
+function createOverlayStagingSink() {
+  if (!installOverlayStaging()) {
+    throw new Error("@pictor-sdk/video-android: overlay staging could not be installed");
+  }
+  const tokens = /* @__PURE__ */ new Map();
+  return {
+    stage(bytes, meta) {
+      const exact = bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength ? bytes.buffer : bytes.slice().buffer;
+      const staged = host().stage(exact, meta.rasterWidth, meta.rasterHeight);
+      tokens.set(staged.file, staged.token);
+      return {
+        file: staged.file,
+        byteLength: staged.byteLength,
+        checksum: staged.checksum
+      };
+    },
+    remove(file) {
+      const token = tokens.get(file);
+      if (token === void 0) return;
+      tokens.delete(file);
+      host().release(token);
+    },
+    releaseAll() {
+      tokens.clear();
+      return host().releaseAll();
+    },
+    ledger() {
+      return host().ledger();
+    }
+  };
+}
+function measureStagingStall(sink, width, height) {
+  const bytes = new Uint8Array(width * height * 4);
+  const at = Date.now();
+  const staged = sink.stage(bytes, {
+    overlayId: "measure",
+    resourceId: "measure",
+    rasterWidth: width,
+    rasterHeight: height
+  });
+  const ms = Date.now() - at;
+  sink.remove(staged.file);
+  return { ms, bytes: bytes.byteLength };
+}
+
+// src/audioProbe.ts
+function probeAudioSource(uri) {
+  let raw;
+  try {
+    raw = requireNative().probeAudioSource(uri);
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { ok: false, reason: "probe returned unparseable JSON" };
+  }
+  const value = parsed;
+  if (value.ok !== true) {
+    return { ok: false, reason: typeof value.reason === "string" ? value.reason : "probe failed" };
+  }
+  return {
+    ok: true,
+    durationUs: Number.isFinite(value.durationUs) ? Number(value.durationUs) : 0,
+    hasAudioTrack: value.hasAudioTrack === true,
+    seekable: value.seekable === true,
+    mimeType: typeof value.mimeType === "string" ? value.mimeType : ""
+  };
+}
+
+// src/managedSources.ts
+function ingestManagedSource(uri) {
+  return parse(
+    () => requireNative().ingestManagedSource(uri),
+    (value) => ({
+      ok: true,
+      uri: String(value.uri ?? ""),
+      token: String(value.token ?? ""),
+      byteLength: Number(value.byteLength ?? 0),
+      sha256: String(value.sha256 ?? ""),
+      created: value.created === true
+    })
+  );
+}
+function releaseManagedSource(token) {
+  try {
+    const value = JSON.parse(requireNative().releaseManagedSource(token));
+    return value.removed === true;
+  } catch {
+    return false;
+  }
+}
+function sweepManagedSources(keepTokens) {
+  try {
+    const value = JSON.parse(
+      requireNative().sweepManagedSources(JSON.stringify([...keepTokens]))
+    );
+    if (value.ok !== true) return { removed: 0, kept: 0, partials: 0, skipped: 0 };
+    return {
+      removed: Number(value.removed ?? 0),
+      kept: Number(value.kept ?? 0),
+      partials: Number(value.partials ?? 0),
+      skipped: Number(value.skipped ?? 0)
+    };
+  } catch {
+    return { removed: 0, kept: 0, partials: 0, skipped: 0 };
+  }
+}
+function managedSourceList() {
+  try {
+    const value = JSON.parse(requireNative().managedSourceList());
+    return value.items ?? [];
+  } catch {
+    return [];
+  }
+}
+function seedManagedSourceForGate(name, bytes) {
+  try {
+    const value = JSON.parse(requireNative().managedSourceGateSeed(name, bytes));
+    return value.ok === true;
+  } catch {
+    return false;
+  }
+}
+function sweepManagedSourcesRawForGate(rawKeep) {
+  try {
+    const value = JSON.parse(requireNative().managedSourceGateSweepRaw(rawKeep));
+    return {
+      ok: value.ok === true,
+      removed: Number(value.removed ?? 0),
+      kept: Number(value.kept ?? 0),
+      partials: Number(value.partials ?? 0),
+      skipped: Number(value.skipped ?? 0)
+    };
+  } catch {
+    return { ok: false, removed: 0, kept: 0, partials: 0, skipped: 0 };
+  }
+}
+function managedSourceLedger() {
+  try {
+    const value = JSON.parse(requireNative().managedSourceLedger());
+    return {
+      count: Number(value.count ?? 0),
+      bytes: Number(value.bytes ?? 0),
+      items: value.items ?? []
+    };
+  } catch {
+    return { count: 0, bytes: 0, items: [] };
+  }
+}
+function managedSourceToken(uri) {
+  const match = /\/([0-9a-f]{64})\.bin$/.exec(uri);
+  return match ? match[1] : null;
+}
+function parse(call2, build) {
+  let raw;
+  try {
+    raw = call2();
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+  }
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return { ok: false, reason: "native returned unparseable JSON" };
+  }
+  if (value.ok !== true) {
+    return { ok: false, reason: typeof value.reason === "string" ? value.reason : "failed" };
+  }
+  return build(value);
+}
+
+// src/previewMix.ts
+async function preparePreviewMix(jobId, programJson, urisJson) {
+  let raw;
+  try {
+    raw = await requireNative().previewMixPrepare(jobId, programJson, urisJson);
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+  }
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return { ok: false, reason: "native returned unparseable JSON" };
+  }
+  if (value.ok === true) {
+    return {
+      ok: true,
+      uri: String(value.uri ?? ""),
+      key: String(value.key ?? ""),
+      cached: value.cached === true,
+      byteLength: Number(value.byteLength ?? 0),
+      ...value.profile ? { profile: value.profile } : {}
+    };
+  }
+  if (value.superseded === true) {
+    return { ok: false, superseded: true, key: String(value.key ?? "") };
+  }
+  return {
+    ok: false,
+    ...typeof value.key === "string" ? { key: value.key } : {},
+    reason: typeof value.error === "string" ? value.error : "the mix could not be prepared"
+  };
+}
+function cancelPreviewMix() {
+  try {
+    requireNative().previewMixCancel();
+  } catch {
+  }
+}
+function previewMixKey(programJson, urisJson) {
+  try {
+    return requireNative().previewMixKey(programJson, urisJson);
+  } catch {
+    return "";
+  }
+}
+function releasePreviewMix(key) {
+  try {
+    const value = JSON.parse(requireNative().previewMixRelease(key));
+    return value.removed === true;
+  } catch {
+    return false;
+  }
+}
+function sweepPreviewMixes(keepKeys) {
+  const none = { removed: 0, kept: 0, partials: 0, skipped: 0 };
+  try {
+    const value = JSON.parse(requireNative().previewMixSweep(JSON.stringify([...keepKeys])));
+    if (value.ok !== true) return none;
+    return {
+      removed: Number(value.removed ?? 0),
+      kept: Number(value.kept ?? 0),
+      partials: Number(value.partials ?? 0),
+      skipped: Number(value.skipped ?? 0)
+    };
+  } catch {
+    return none;
+  }
+}
+function previewMixLedger() {
+  try {
+    const value = JSON.parse(requireNative().previewMixLedger());
+    return {
+      count: Number(value.count ?? 0),
+      bytes: Number(value.bytes ?? 0),
+      items: value.items ?? []
+    };
+  } catch {
+    return { count: 0, bytes: 0, items: [] };
+  }
+}
+
+// src/previewAudioSession.ts
+var import_video_core7 = require("@pictor-sdk/video-core");
+function previewAudioNeeded(project) {
+  return project.audio.length > 0;
+}
+function decidePreviewAudio(inputs) {
+  const { wantedKey, readyKey, preparingKey, failedKey } = inputs;
+  if (wantedKey === "") {
+    return {
+      status: "source",
+      wantedKey,
+      shouldPrepare: false,
+      muteSourceAudio: false,
+      canPlay: true
+    };
+  }
+  if (readyKey === wantedKey) {
+    return {
+      status: "ready",
+      wantedKey,
+      shouldPrepare: false,
+      // The mix contains the clips' audio too. Leaving the source audible
+      // would play the whole timeline twice.
+      muteSourceAudio: true,
+      canPlay: true
+    };
+  }
+  if (failedKey === wantedKey) {
+    return {
+      status: "failed",
+      wantedKey,
+      shouldPrepare: false,
+      muteSourceAudio: true,
+      canPlay: false
+    };
+  }
+  return {
+    status: "preparing",
+    wantedKey,
+    shouldPrepare: preparingKey !== wantedKey,
+    muteSourceAudio: true,
+    canPlay: false
+  };
+}
+function previewProgramJson(project) {
+  return JSON.stringify((0, import_video_core7.compileAudioMixProgram)(project));
+}
+var PREVIEW_DRIFT_TOLERANCE_US = 6e4;
+
+// src/tracePhases.ts
+var PHASE_MARK_PREFIX = "phase:";
+function num(v) {
+  return typeof v === "number" ? v : Number(v);
+}
+function empty(label, index) {
+  return {
+    label,
+    index,
+    samples: 0,
+    playingSamples: 0,
+    freshPlayingSamples: 0,
+    stalePlayingSamples: 0,
+    longestStaleRun: 0,
+    minUs: 0,
+    maxUs: 0,
+    meanUs: 0,
+    worstAbsUs: 0,
+    freshWorstAbsUs: 0,
+    overToleranceSamples: 0,
+    settledAfterUs: 0
+  };
+}
+function summarisePhases(events, toleranceUs) {
+  const phases = [];
+  let current = empty("start", 0);
+  let sum = 0;
+  let staleRun = 0;
+  let firstPlayingNs = 0;
+  let lastOverNs = 0;
+  let sawPlaying = false;
+  let stillOver = false;
+  const close = () => {
+    current.meanUs = current.playingSamples > 0 ? Math.round(sum / current.playingSamples) : 0;
+    current.settledAfterUs = current.overToleranceSamples === 0 ? 0 : stillOver ? -1 : Math.round((lastOverNs - firstPlayingNs) / 1e3);
+    phases.push(current);
+    sum = 0;
+    staleRun = 0;
+    firstPlayingNs = 0;
+    lastOverNs = 0;
+    sawPlaying = false;
+    stillOver = false;
+  };
+  for (const e of events) {
+    if (e.type !== "sample") {
+      const label = e.type === "mark" ? String(e.v.label ?? "") : "";
+      if (label.startsWith(PHASE_MARK_PREFIX)) {
+        close();
+        current = empty(label.slice(PHASE_MARK_PREFIX.length), phases.length);
+      }
+      continue;
+    }
+    current.samples += 1;
+    if (e.v.videoPlaying !== true || e.v.audioPlaying !== true) {
+      staleRun = 0;
+      continue;
+    }
+    const offset = num(e.v.offsetUs);
+    if (!Number.isFinite(offset)) continue;
+    current.playingSamples += 1;
+    if (!sawPlaying) {
+      sawPlaying = true;
+      firstPlayingNs = num(e.atNs);
+    }
+    sum += offset;
+    if (current.playingSamples === 1) {
+      current.minUs = offset;
+      current.maxUs = offset;
+    } else {
+      current.minUs = Math.min(current.minUs, offset);
+      current.maxUs = Math.max(current.maxUs, offset);
+    }
+    const abs = Math.abs(offset);
+    if (abs > current.worstAbsUs) current.worstAbsUs = abs;
+    if (abs > toleranceUs) {
+      current.overToleranceSamples += 1;
+      lastOverNs = num(e.atNs);
+      stillOver = true;
+    } else {
+      stillOver = false;
+    }
+    if (e.v.pfFresh === true) {
+      current.freshPlayingSamples += 1;
+      if (abs > current.freshWorstAbsUs) current.freshWorstAbsUs = abs;
+      staleRun = 0;
+    } else {
+      current.stalePlayingSamples += 1;
+      staleRun += 1;
+      if (staleRun > current.longestStaleRun) current.longestStaleRun = staleRun;
+    }
+  }
+  close();
+  const worstAbsUs = phases.reduce((w, p) => Math.max(w, p.worstAbsUs), 0);
+  const freshWorstAbsUs = phases.reduce((w, p) => Math.max(w, p.freshWorstAbsUs), 0);
+  const overToleranceSamples = phases.reduce((n, p) => n + p.overToleranceSamples, 0);
+  return {
+    toleranceUs,
+    phases,
+    worstAbsUs,
+    freshWorstAbsUs,
+    overToleranceSamples,
+    pass: overToleranceSamples === 0
+  };
+}
+
+// src/spikeExcursions.ts
+var SPIKE_TOLERANCE_US = 6e4;
+function offsetAt(sample, releaseAtNs = 0) {
+  if (releaseAtNs > 0 && sample.frameConsumedNs < releaseAtNs) {
+    const raw = sample.positionUs - sample.framePtsUs;
+    return { atLatch: raw, atIntended: raw };
+  }
+  return {
+    atLatch: sample.positionUs - (sample.atNs - sample.frameConsumedNs) / 1e3 - sample.framePtsUs,
+    atIntended: sample.positionUs - (sample.atNs - sample.frameReleaseNs) / 1e3 - sample.framePtsUs
+  };
+}
+function classifyExcursions(samples, options = {}) {
+  const toleranceUs = options.toleranceUs ?? SPIKE_TOLERANCE_US;
+  const frameIntervalUs = options.frameIntervalUs ?? 33333;
+  const ADVANCE_WINDOW_NS = 2e8;
+  const advancing = samples.map((s, i) => {
+    for (let j = i - 1; j >= 0; j -= 1) {
+      if (s.atNs - samples[j].atNs > ADVANCE_WINDOW_NS) break;
+      if (samples[j].positionUs !== s.positionUs) return true;
+    }
+    return false;
+  });
+  const releaseAtNs = [];
+  let intervalStart = 0;
+  for (let i = 0; i < samples.length; i += 1) {
+    if (!advancing[i]) intervalStart = 0;
+    else if (intervalStart === 0) intervalStart = samples[i].atNs;
+    releaseAtNs.push(intervalStart);
+  }
+  const isActive = (s, i) => s.playing && s.ready && s.framePtsUs >= 0 && s.frameConsumedNs > 0 && // The picture for this epoch has arrived.
+  s.frameConsumedNs >= s.atNs - s.sinceEpochNs && advancing[i] === true;
+  const active = samples.filter(isActive);
+  const preparing = samples.length - active.length;
+  const excursions = [];
+  const byCause = {};
+  let worstAbsUs = 0;
+  let worstAtIntendedUs = 0;
+  let overAtIntended = 0;
+  let readSpanUs = 0;
+  let latchLagSum = 0;
+  let preReleaseSamples = 0;
+  let preReleaseWorstUs = 0;
+  const releaseFor = /* @__PURE__ */ new Map();
+  samples.forEach((s, i) => releaseFor.set(s.seq, releaseAtNs[i]));
+  for (let i = 0; i < active.length; i += 1) {
+    const s = active[i];
+    const previous = i > 0 ? active[i - 1] : null;
+    readSpanUs = Math.max(readSpanUs, s.readSpanNs / 1e3);
+    const releasedAt = releaseFor.get(s.seq) ?? 0;
+    const both = offsetAt(s, releasedAt);
+    const offsetUs = both.atLatch;
+    const abs = Math.abs(offsetUs);
+    const absIntended = Math.abs(both.atIntended);
+    if (releasedAt > 0 && s.frameConsumedNs < releasedAt) {
+      preReleaseSamples += 1;
+      if (abs > preReleaseWorstUs) preReleaseWorstUs = abs;
+    }
+    if (abs > worstAbsUs) worstAbsUs = abs;
+    if (absIntended > worstAtIntendedUs) worstAtIntendedUs = absIntended;
+    if (absIntended > toleranceUs) overAtIntended += 1;
+    if (abs <= toleranceUs) continue;
+    const frameAgeUs = (s.atNs - s.frameConsumedNs) / 1e3;
+    const latchLagUs = (s.frameConsumedNs - s.frameReleaseNs) / 1e3;
+    latchLagSum += latchLagUs;
+    const positionStepUs = previous ? s.positionUs - previous.positionUs : 0;
+    const wallStepUs = previous ? (s.atNs - previous.atNs) / 1e3 : 0;
+    let cause;
+    if (releasedAt > 0 && s.frameConsumedNs < releasedAt) {
+      cause = "pre-release-frame";
+    } else if (s.frameConsumedNs > 0 && s.frameConsumedNs < s.atNs - s.sinceEpochNs) {
+      cause = "cross-epoch";
+    } else if (previous && s.frameGeneration !== previous.frameGeneration) {
+      cause = "cross-epoch";
+    } else if (frameAgeUs > 2 * frameIntervalUs) {
+      cause = "stale-pairing";
+    } else if (s.sinceEpochNs / 1e3 < 5e5) {
+      cause = "first-frame-after-seek";
+    } else if (latchLagUs > frameIntervalUs) {
+      cause = "delayed-presentation";
+    } else if (previous && Math.abs(positionStepUs - wallStepUs) > toleranceUs) {
+      cause = "audio-discontinuity";
+    } else if (previous && s.frameWindow !== previous.frameWindow) {
+      cause = "mapping";
+    } else {
+      cause = "unexplained";
+    }
+    byCause[cause] = (byCause[cause] ?? 0) + 1;
+    excursions.push({
+      seq: s.seq,
+      offsetUs: Math.round(offsetUs),
+      offsetAtIntendedUs: Math.round(both.atIntended),
+      cause,
+      epoch: s.epoch,
+      sinceEpochMs: Math.round(s.sinceEpochNs / 1e6),
+      frameWindow: s.frameWindow,
+      framePtsUs: s.framePtsUs,
+      latchLagUs: Math.round(latchLagUs),
+      frameAgeUs: Math.round(frameAgeUs),
+      positionStepUs: Math.round(positionStepUs),
+      wallStepUs: Math.round(wallStepUs)
+    });
+  }
+  return {
+    toleranceUs,
+    activeSamples: active.length,
+    preparingSamples: preparing,
+    excursions,
+    byCause,
+    preReleaseSamples,
+    preReleaseWorstUs: Math.round(preReleaseWorstUs),
+    worstAbsUs: Math.round(worstAbsUs),
+    worstAtIntendedUs: Math.round(worstAtIntendedUs),
+    overAtIntended,
+    passAtIntended: active.length > 0 && overAtIntended === 0,
+    meanLatchLagUs: excursions.length ? Math.round(latchLagSum / excursions.length) : 0,
+    // No samples is not a pass. A run that never played has not been judged.
+    pass: active.length > 0 && excursions.length === 0,
+    uncertainty: {
+      frameQuantumUs: Math.round(frameIntervalUs / 2),
+      readSpanUs: Math.round(readSpanUs),
+      positionQuantumUs: 1e3
+    }
+  };
+}
+function windowAround(samples, seq, spanUs = 25e4) {
+  const centre = samples.find((s) => s.seq === seq);
+  if (!centre) return [];
+  const spanNs = spanUs * 1e3;
+  return samples.filter((s) => Math.abs(s.atNs - centre.atNs) <= spanNs);
+}
+
+// src/previewCadence.ts
+var import_video_core8 = require("@pictor-sdk/video-core");
+var PREVIEW_TOLERANCE_US = 6e4;
+var PARITY_LEVEL_TOLERANCE = 12;
+var PARITY_BAR_TOLERANCE = 4 / 960;
+var PREVIEW_OUTPUT_FPS = 30;
+function wallClockAt(samples, projectUs, intervalUs) {
+  let before = null;
+  let after = null;
+  for (const s of samples) {
+    if (!s.playing || s.positionUs < 0 || s.atNs <= 0) continue;
+    if (s.positionUs <= projectUs && (before === null || s.positionUs > before.positionUs)) before = s;
+    if (s.positionUs >= projectUs && (after === null || s.positionUs < after.positionUs)) after = s;
+  }
+  if (after === null) {
+    if (before === null || projectUs - before.positionUs > intervalUs) return null;
+    return before.atNs + (projectUs - before.positionUs) * 1e3;
+  }
+  if (before === null) {
+    if (after.positionUs - projectUs > intervalUs) return null;
+    return after.atNs - (after.positionUs - projectUs) * 1e3;
+  }
+  if (before.epoch !== after.epoch) return null;
+  if (after.positionUs === before.positionUs) return before.atNs;
+  const t = (projectUs - before.positionUs) / (after.positionUs - before.positionUs);
+  return before.atNs + t * (after.atNs - before.atNs);
+}
+function displayedAt(submissions, projectUs, atNs, intervalNs) {
+  if (atNs === null) return null;
+  const deadlineNs = atNs + intervalNs;
+  let best = null;
+  for (const s of submissions) {
+    if (s.ptsUs > projectUs) continue;
+    if (s.submittedNs > deadlineNs) continue;
+    if (best === null || s.submittedNs > best.submittedNs) best = s;
+  }
+  return best;
+}
+function checkCadence(clip, submissions, outputFps = PREVIEW_OUTPUT_FPS, toleranceUs = PREVIEW_TOLERANCE_US, samples = []) {
+  const request = {
+    sourceStartUs: clip.sourceStartUs,
+    sourceEndUs: clip.sourceEndUs,
+    speed: clip.speed,
+    sourceFps: clip.sourceFps,
+    targetFps: outputFps
+  };
+  const plan = (0, import_video_core8.resampleClip)(request);
+  const outputIntervalUs = Math.round(1e6 / outputFps);
+  const inClip = submissions.filter((s) => s.ptsUs >= clip.timelineStartUs && s.ptsUs < clip.timelineEndUs).sort((a, b) => a.ptsUs - b.ptsUs);
+  const skews = inClip.filter((s) => s.texturePtsUs >= 0).map((s) => Math.abs(s.texturePtsUs - s.ptsUs)).sort((a, b) => a - b);
+  const medianSkewUs = skews.length > 0 ? skews[Math.floor(skews.length / 2)] : -1;
+  const timestampDomain = skews.length === 0 ? "unknown" : medianSkewUs < 1e6 ? "media" : "system";
+  const unique = new Set(inClip.map((s) => s.ptsUs));
+  const delivered = /* @__PURE__ */ new Set();
+  let markersRead = 0;
+  let markersFailed = 0;
+  for (const record2 of inClip) {
+    if (record2.acquiredMarker >= 0) delivered.add(record2.acquiredMarker);
+    if (record2.submittedMarker >= 0) markersRead += 1;
+    else if (record2.markerFailure !== "" && record2.markerFailure !== "unread") markersFailed += 1;
+  }
+  const pixelIdentity = markersRead > 0;
+  const first = inClip.length > 0 ? inClip[0].ptsUs : 0;
+  const last = inClip.length > 0 ? inClip[inClip.length - 1].ptsUs : 0;
+  const clockOffsets = inClip.filter((r) => r.submittedNs > 0).map((r) => r.submittedNs - r.ptsUs * 1e3).sort((a, b) => a - b);
+  const playerOffsets = samples.filter((s) => s.playing && s.atNs > 0 && s.positionUs >= 0).map((s) => s.atNs - s.positionUs * 1e3).sort((a, b) => a - b);
+  const frameDerivedOffsetNs = clockOffsets.length > 0 && playerOffsets.length > 0 ? clockOffsets[Math.floor(clockOffsets.length / 2)] - playerOffsets[Math.floor(playerOffsets.length / 2)] : 0;
+  let expectedInstants = 0;
+  let leadingExcluded = 0;
+  let trailingExcluded = 0;
+  let covered = 0;
+  let wrong = 0;
+  let unverified = 0;
+  let unplaceable = 0;
+  let exact = 0;
+  const offsets = {};
+  const sourceIntervalUs = clip.sourceFps > 0 ? 1e6 / clip.sourceFps / clip.speed : 0;
+  const wrongInstants = [];
+  for (const frame of plan.frames) {
+    const projectUs = clip.timelineStartUs + Number(frame.outputPtsUs);
+    if (inClip.length === 0) continue;
+    const boundary = projectUs < first || projectUs > last;
+    if (projectUs < first) leadingExcluded += 1;
+    else if (projectUs > last) trailingExcluded += 1;
+    else expectedInstants += 1;
+    const instantNs = wallClockAt(samples, projectUs, outputIntervalUs);
+    if (instantNs === null && !boundary) unplaceable += 1;
+    const shown = instantNs === null ? null : displayedAt(inClip, projectUs, instantNs, outputIntervalUs * 1e3);
+    if (shown === null) {
+      if (boundary) {
+        wrongInstants.push({
+          projectUs,
+          expectedSourceFrame: frame.sourceFrameIndex,
+          expectedSourcePtsUs: Number(frame.sourceTimeUs),
+          shownSourceFrame: -1,
+          shownPtsUs: -1,
+          acquiredTexturePtsUs: -1,
+          acquiredMarker: -1,
+          submittedMarker: -1,
+          slot: -1,
+          frameId: -1,
+          submittedNs: 0,
+          cause: "uncovered",
+          boundary
+        });
+      }
+      continue;
+    }
+    if (!boundary) covered += 1;
+    const shownProjectUs = timestampDomain === "media" ? shown.texturePtsUs : shown.ptsUs;
+    const shownSourceUs = clip.sourceStartUs + (shownProjectUs - clip.timelineStartUs) * clip.speed;
+    const derivedIndex = Math.floor(shownSourceUs * clip.sourceFps / 1e6);
+    const shownIndex = shown.submittedMarker >= 0 ? shown.submittedMarker : derivedIndex;
+    const verified = shown.submittedMarker >= 0 || timestampDomain === "media";
+    if (!verified) {
+      if (!boundary) unverified += 1;
+      continue;
+    }
+    const offset = shownIndex - frame.sourceFrameIndex;
+    if (!boundary) {
+      const key = String(offset);
+      offsets[key] = (offsets[key] ?? 0) + 1;
+    }
+    const offsetUs = Math.abs(offset) * sourceIntervalUs;
+    const slack = shown.submittedMarker >= 0 ? 0 : sourceIntervalUs;
+    if (offset === 0) exact += 1;
+    if (offsetUs <= Math.max(toleranceUs, slack)) continue;
+    if (!boundary) wrong += 1;
+    const acquired = shown.texturePtsUs;
+    const late = shown.submittedNs > 0 && shown.ptsUs < projectUs - outputIntervalUs;
+    const hadItByThen = inClip.some(
+      (r) => r.acquiredMarker === frame.sourceFrameIndex && r.acquiredNs > 0 && r.acquiredNs <= shown.submittedNs
+    );
+    let cause;
+    if (shown.submittedMarker >= 0) {
+      if (shown.acquiredMarker >= 0 && shown.submittedMarker !== shown.acquiredMarker) {
+        cause = "storage-aliased";
+      } else if (!hadItByThen) cause = "not-delivered";
+      else cause = "wrong-selection";
+    } else if (late) cause = "late-delivery";
+    else cause = "wrong-submitted-identity";
+    wrongInstants.push({
+      projectUs,
+      expectedSourceFrame: frame.sourceFrameIndex,
+      expectedSourcePtsUs: Number(frame.sourceTimeUs),
+      shownSourceFrame: shownIndex,
+      shownPtsUs: shownProjectUs,
+      acquiredTexturePtsUs: acquired,
+      acquiredMarker: shown.acquiredMarker,
+      submittedMarker: shown.submittedMarker,
+      slot: shown.slot,
+      frameId: shown.frameId,
+      submittedNs: shown.submittedNs,
+      cause,
+      boundary
+    });
+  }
+  const walls = [];
+  for (let i = 1; i < inClip.length; i += 1) {
+    const gap = (inClip[i].submittedNs - inClip[i - 1].submittedNs) / 1e3;
+    if (gap > 0) walls.push(gap);
+  }
+  walls.sort((a, b) => a - b);
+  const tail = (fraction) => walls.length === 0 ? 0 : Math.round(walls[Math.min(walls.length - 1, Math.floor(walls.length * fraction))]);
+  const frameTimes = {
+    p50: tail(0.5),
+    p95: tail(0.95),
+    p99: tail(0.99),
+    max: walls.length > 0 ? Math.round(walls[walls.length - 1]) : 0,
+    samples: walls.length
+  };
+  let parityMeasured = 0;
+  let worstLevelDelta = 0;
+  let worstBarDelta = 0;
+  let parityFailures = 0;
+  for (const record2 of inClip) {
+    if (record2.levelDelta < 0 || record2.barDelta < 0) continue;
+    parityMeasured += 1;
+    if (record2.levelDelta > worstLevelDelta) worstLevelDelta = record2.levelDelta;
+    if (record2.barDelta > worstBarDelta) worstBarDelta = record2.barDelta;
+    if (record2.levelDelta > PARITY_LEVEL_TOLERANCE || record2.barDelta > PARITY_BAR_TOLERANCE) {
+      parityFailures += 1;
+    }
+  }
+  const stamps = [...unique].sort((a, b) => a - b);
+  const holds = [];
+  for (let i = 1; i < stamps.length; i += 1) holds.push(stamps[i] - stamps[i - 1]);
+  const repeats = Math.max(1, Math.round(1 / clip.speed));
+  const expectedHoldUs = outputIntervalUs * repeats;
+  const missedDeadlines = holds.filter((h) => h > expectedHoldUs * 1.5).length;
+  holds.sort((a, b) => a - b);
+  let verdict = "pass";
+  let verdictReason = "";
+  if (expectedInstants === 0) {
+    verdict = "invalid";
+    verdictReason = "no instants covered";
+  } else if (!pixelIdentity) {
+    verdict = "invalid";
+    verdictReason = "identity not read from pixels";
+  } else if (parityMeasured === 0) {
+    verdict = "invalid";
+    verdictReason = "rendering parity not measured";
+  } else if (unplaceable > 0) {
+    verdict = "invalid";
+    verdictReason = `${unplaceable} instants could not be placed on the clock`;
+  } else if (unverified > 0) {
+    verdict = "invalid";
+    verdictReason = `${unverified} instants unverified`;
+  } else if (wrong > 0) {
+    verdict = "fail";
+    verdictReason = `${wrong} wrong instants`;
+  } else if (covered !== expectedInstants) {
+    verdict = "fail";
+    verdictReason = `${expectedInstants - covered} instants uncovered`;
+  } else if (missedDeadlines > 0) {
+    verdict = "fail";
+    verdictReason = `${missedDeadlines} missed deadlines`;
+  } else if (parityFailures > 0) {
+    verdict = "fail";
+    verdictReason = `${parityFailures} parity failures`;
+  }
+  return {
+    clip: clip.name,
+    nominalInstants: plan.frames.length,
+    leadingExcluded,
+    trailingExcluded,
+    expectedInstants,
+    coveredInstants: covered,
+    wrongFrameInstants: wrong,
+    uncoveredInstants: expectedInstants - covered,
+    submittedUnique: unique.size,
+    ruleSkippedSourceFrames: plan.droppedSourceFrameCount,
+    outputIntervalUs,
+    medianHoldUs: holds.length > 0 ? holds[Math.floor(holds.length / 2)] : 0,
+    maxHoldUs: holds.length > 0 ? holds[holds.length - 1] : 0,
+    expectedHoldUs,
+    missedDeadlines,
+    parity: {
+      measured: parityMeasured,
+      worstLevelDelta,
+      worstBarDelta: Number(worstBarDelta.toFixed(5)),
+      failures: parityFailures,
+      // No measurement is not a pass: a run that never looked has not looked.
+      pass: parityMeasured > 0 && parityFailures === 0
+    },
+    offsets,
+    unplaceableInstants: unplaceable,
+    frameDerivedOffsetUs: Math.round(frameDerivedOffsetNs / 1e3),
+    exactInstants: exact,
+    worstOffsetUs: Math.round(
+      Object.keys(offsets).reduce((worst, k) => Math.max(worst, Math.abs(Number(k))), 0) * (clip.sourceFps > 0 ? 1e6 / clip.sourceFps / clip.speed : 0)
+    ),
+    identity: {
+      timestampDomain,
+      medianTextureSkewUs: medianSkewUs,
+      pixelIdentity,
+      identityUnverified: unverified,
+      deliveredFrames: delivered.size,
+      markersRead,
+      markersFailed
+    },
+    frameTimeUs: frameTimes,
+    wrong: wrongInstants,
+    // Every expected instant covered, by the frame the shared rule names, and
+    // no picture held past its turn.
+    /*
+          An unverified instant is not a passing one.
+    
+          With the probe off and the timestamps in the system domain there is no
+          evidence about which frame was shown, and a check that reported that
+          absence as success would be the same mistake as the one the band was
+          built to correct.
+        */
+    /*
+          The preview contract: temporally accurate, correctly rendered, covered.
+    
+          Exact export-frame identity is deliberately absent. `exactInstants` and
+          `offsets` record it, and `@see PREVIEW_TOLERANCE_US` for why requiring it
+          here would be requiring a per-frame seek.
+        */
+    pass: verdict === "pass",
+    verdict,
+    verdictReason
+  };
+}
+
+// src/submissionScoring.ts
+function audioAt(samples, atNs, windowNs) {
+  let before = null;
+  let after = null;
+  for (const s of samples) {
+    if (!s.playing) continue;
+    if (s.atNs <= atNs && (before === null || s.atNs > before.atNs)) before = s;
+    if (s.atNs >= atNs && (after === null || s.atNs < after.atNs)) after = s;
+  }
+  if (before !== null && after !== null && after.atNs > before.atNs) {
+    const spanUs = (after.atNs - before.atNs) / 1e3;
+    const movedUs = after.positionUs - before.positionUs;
+    if (Math.abs(movedUs - spanUs) <= DISCONTINUITY_US) {
+      const t = (atNs - before.atNs) / (after.atNs - before.atNs);
+      return before.positionUs + t * movedUs;
+    }
+    return before.positionUs + (atNs - before.atNs) / 1e3;
+  }
+  const nearest = before ?? after;
+  if (nearest === null) return null;
+  if (Math.abs(nearest.atNs - atNs) > windowNs) return null;
+  return nearest.positionUs + (atNs - nearest.atNs) / 1e3;
+}
+var DISCONTINUITY_US = 1e5;
+function scoreSubmissions(submissions, samples, options = {}) {
+  const toleranceUs = options.toleranceUs ?? 6e4;
+  const pairWindowNs = options.pairWindowNs ?? 5e7;
+  const scored = [];
+  const excursions = [];
+  let unpaired = 0;
+  let worstErrorUs = 0;
+  let peakOccupancy = 0;
+  for (const record2 of submissions) {
+    if (record2.ptsUs < 0 || record2.submittedNs <= 0) continue;
+    if (record2.occupancy > peakOccupancy) peakOccupancy = record2.occupancy;
+    const audioUs = audioAt(samples, record2.submittedNs, pairWindowNs);
+    if (audioUs === null) {
+      unpaired += 1;
+      continue;
+    }
+    const start = record2.ptsUs;
+    const end = record2.ptsUs + Math.max(record2.intervalUs, 0);
+    const signedUs = audioUs < start ? audioUs - start : audioUs > end ? audioUs - end : 0;
+    const errorUs = Math.abs(signedUs);
+    const entry = {
+      frameId: record2.frameId,
+      ptsUs: record2.ptsUs,
+      intervalUs: record2.intervalUs,
+      submittedNs: record2.submittedNs,
+      audioUs: Math.round(audioUs),
+      errorUs: Math.round(errorUs),
+      signedUs: Math.round(signedUs),
+      occupancy: record2.occupancy
+    };
+    scored.push(entry);
+    if (errorUs > worstErrorUs) worstErrorUs = errorUs;
+    if (errorUs > toleranceUs) excursions.push(entry);
+  }
+  const gaps = [];
+  const frameTimes = [];
+  for (let i = 1; i < scored.length; i += 1) {
+    const gap = scored[i].ptsUs - scored[i - 1].ptsUs;
+    if (gap > 0) gaps.push(gap);
+    const wall = (scored[i].submittedNs - scored[i - 1].submittedNs) / 1e3;
+    if (wall > 0) frameTimes.push(wall);
+  }
+  gaps.sort((a, b) => a - b);
+  frameTimes.sort((a, b) => a - b);
+  const at = (fraction) => frameTimes.length === 0 ? 0 : Math.round(frameTimes[Math.min(frameTimes.length - 1, Math.floor(frameTimes.length * fraction))]);
+  return {
+    toleranceUs,
+    scored: scored.length,
+    unpaired,
+    excursions,
+    worstErrorUs: Math.round(worstErrorUs),
+    // No submissions is not a pass: a run that showed nothing was not judged.
+    pass: scored.length > 0 && excursions.length === 0,
+    verdict: scored.length === 0 ? "invalid" : excursions.length === 0 ? "pass" : "fail",
+    verdictReason: scored.length === 0 ? "no submissions scored" : excursions.length === 0 ? "" : `${excursions.length} excursions, worst ${Math.round(worstErrorUs / 1e3)} ms`,
+    cadenceUs: {
+      median: gaps.length > 0 ? gaps[Math.floor(gaps.length / 2)] : 0,
+      min: gaps.length > 0 ? gaps[0] : 0,
+      max: gaps.length > 0 ? gaps[gaps.length - 1] : 0,
+      samples: gaps.length
+    },
+    frameTimeUs: {
+      p50: at(0.5),
+      p95: at(0.95),
+      p99: at(0.99),
+      max: frameTimes.length > 0 ? Math.round(frameTimes[frameTimes.length - 1]) : 0,
+      samples: frameTimes.length
+    },
+    peakOccupancy
+  };
+}
+function traceSubmission(records, scored, frameId, span = 8) {
+  const ordered = records.filter((r) => r.submittedNs > 0).sort((a, b) => a.submittedNs - b.submittedNs);
+  const centre = ordered.findIndex((r) => r.frameId === frameId);
+  if (centre < 0) {
+    return {
+      frameId,
+      rows: [],
+      spentOn: "unknown",
+      spentUs: 0,
+      invalid: true,
+      reason: "frame not retained"
+    };
+  }
+  const from = Math.max(0, centre - span);
+  const window = ordered.slice(from, centre + span + 1);
+  const base = window[0].submittedNs;
+  const ms = (ns) => ns > 0 ? Math.round((ns - base) / 1e6) : -1;
+  const rows = window.map((r) => {
+    const match = scored.find((s) => s.frameId === r.frameId);
+    return {
+      frameId: r.frameId,
+      acquiredMs: ms(r.acquiredNs),
+      dueMs: ms(r.dueNs),
+      promotedMs: ms(r.promotedNs),
+      submittedMs: ms(r.submittedNs),
+      waitUs: r.acquiredNs > 0 && r.dueNs > 0 ? Math.round((r.dueNs - r.acquiredNs) / 1e3) : -1,
+      promoteUs: r.dueNs > 0 && r.promotedNs > 0 ? Math.round((r.promotedNs - r.dueNs) / 1e3) : -1,
+      submitUs: r.promotedNs > 0 && r.submittedNs > 0 ? Math.round((r.submittedNs - r.promotedNs) / 1e3) : -1,
+      ptsUs: r.ptsUs,
+      audioUs: match === void 0 ? -1 : match.audioUs,
+      errorUs: match === void 0 ? -1 : match.errorUs,
+      slot: r.slot,
+      occupancy: r.occupancy,
+      marker: r.submittedMarker
+    };
+  });
+  const target = rows.find((r) => r.frameId === frameId);
+  const raw = window.find((r) => r.frameId === frameId);
+  if (raw.acquiredNs <= 0 || raw.dueNs <= 0 || raw.promotedNs <= 0) {
+    return {
+      frameId,
+      rows,
+      spentOn: "unknown",
+      spentUs: 0,
+      invalid: true,
+      reason: "incomplete stamps"
+    };
+  }
+  const index = rows.indexOf(target);
+  const previous = index > 0 ? rows[index - 1] : null;
+  const arrivalUs = previous === null ? 0 : Math.round((target.acquiredMs - previous.submittedMs) * 1e3);
+  const promoteUs = target.waitUs < 0 ? target.promoteUs + target.waitUs : target.promoteUs;
+  const legs = [
+    ["arrival", arrivalUs],
+    ["due", Math.max(0, target.waitUs)],
+    ["promotion", promoteUs],
+    ["submission", target.submitUs]
+  ];
+  let spentOn = "unknown";
+  let worst = -1;
+  for (const [name, value] of legs) {
+    if (value > worst) {
+      worst = value;
+      spentOn = name;
+    }
+  }
+  return { frameId, rows, spentOn, spentUs: Math.max(0, worst), invalid: false, reason: "" };
+}
+function traceSeam(samples, atUs, spanUs = 6e5) {
+  const near = samples.filter(
+    (s) => s.framePtsUs >= 0 && s.framePtsUs >= atUs - spanUs && s.framePtsUs <= atUs + spanUs && s.frameConsumedNs > 0
+  ).sort((a, b) => a.frameConsumedNs - b.frameConsumedNs);
+  const unique = [];
+  for (const s of near) {
+    if (unique.length === 0 || unique[unique.length - 1].frameId !== s.frameId) unique.push(s);
+  }
+  if (unique.length < 3) {
+    return {
+      atUs,
+      outputGapUs: -1,
+      acquireGapUs: -1,
+      owner: "unknown",
+      stages: [],
+      invalid: true,
+      reason: "too few frames around the boundary"
+    };
+  }
+  const base = unique[0].frameConsumedNs;
+  const ms = (ns) => ns > 0 ? Math.round((ns - base) / 1e6) : -1;
+  const stages = unique.map((s) => ({
+    framePtsUs: s.framePtsUs,
+    metadataMs: ms(s.frameMetadataNs),
+    availableMs: ms(s.frameAvailableNs),
+    consumedMs: ms(s.frameConsumedNs),
+    graphUs: s.frameMetadataNs > 0 && s.frameAvailableNs > 0 ? Math.round((s.frameAvailableNs - s.frameMetadataNs) / 1e3) : -1,
+    latchUs: s.frameAvailableNs > 0 && s.frameConsumedNs > 0 ? Math.round((s.frameConsumedNs - s.frameAvailableNs) / 1e3) : -1
+  }));
+  let outputGapUs = 0;
+  let acquireGapUs = 0;
+  let at = -1;
+  for (let i = 1; i < unique.length; i += 1) {
+    const acquire = Math.round((unique[i].frameConsumedNs - unique[i - 1].frameConsumedNs) / 1e3);
+    if (acquire > acquireGapUs) {
+      acquireGapUs = acquire;
+      at = i;
+    }
+    const a = unique[i].frameMetadataNs;
+    const b = unique[i - 1].frameMetadataNs;
+    if (a > 0 && b > 0) outputGapUs = Math.max(outputGapUs, Math.round((a - b) / 1e3));
+  }
+  let owner = "unknown";
+  if (at > 0) {
+    const s = stages[at];
+    if (s.graphUs < 0 || s.latchUs < 0) owner = "unknown";
+    else if (s.graphUs >= s.latchUs && s.graphUs > 16e3) owner = "graph";
+    else if (s.latchUs > 16e3) owner = "consumer";
+    else owner = "production";
+  }
+  return { atUs, outputGapUs, acquireGapUs, owner, stages, invalid: false, reason: "" };
+}
+function traceStartup(samples, records, options) {
+  const count = options.count ?? 10;
+  if (options.sourceFps <= 0 || options.speed <= 0) {
+    return { rows: [], missingSourceFrames: [], misassociated: [], invalid: true, reason: "no clip rate" };
+  }
+  const stepUs = 1e6 / options.sourceFps / options.speed;
+  const byFrame = /* @__PURE__ */ new Map();
+  for (const s of samples) {
+    if (s.frameId < 0 || s.frameConsumedNs <= 0) continue;
+    const seen = byFrame.get(s.frameId);
+    if (seen === void 0 || s.frameConsumedNs < seen.frameConsumedNs) byFrame.set(s.frameId, s);
+  }
+  const ordered = records.filter((r) => r.submittedNs > 0).sort((a, b) => a.submittedNs - b.submittedNs).slice(0, count);
+  if (ordered.length === 0) {
+    return { rows: [], missingSourceFrames: [], misassociated: [], invalid: true, reason: "no submissions" };
+  }
+  const base = ordered[0].submittedNs;
+  const ms = (ns) => ns > 0 ? Math.round((ns - base) / 1e6) : -1;
+  const rows = ordered.map((r) => {
+    const s = byFrame.get(r.frameId);
+    return {
+      frameId: r.frameId,
+      renderedPtsUs: s === void 0 ? -1 : s.framePtsUs,
+      recordedPtsUs: r.ptsUs,
+      marker: r.submittedMarker,
+      markerPtsUs: r.submittedMarker >= 0 ? Math.round(r.submittedMarker * stepUs) : -1,
+      metadataMs: s === void 0 ? -1 : ms(s.frameMetadataNs),
+      consumedMs: s === void 0 ? -1 : ms(s.frameConsumedNs),
+      submittedMs: ms(r.submittedNs)
+    };
+  });
+  const misassociated = [];
+  const rendered = /* @__PURE__ */ new Set();
+  for (const row of rows) {
+    if (row.renderedPtsUs >= 0) rendered.add(Math.round(row.renderedPtsUs / stepUs));
+    if (row.marker < 0 || row.renderedPtsUs < 0) continue;
+    if (Math.abs(row.markerPtsUs - row.renderedPtsUs) > stepUs / 2) misassociated.push(row.frameId);
+  }
+  const last = rows[rows.length - 1];
+  const highest = Math.max(
+    last.marker >= 0 ? last.marker : 0,
+    last.renderedPtsUs >= 0 ? Math.round(last.renderedPtsUs / stepUs) : 0
+  );
+  const missingSourceFrames = [];
+  for (let i = 0; i <= highest; i += 1) if (!rendered.has(i)) missingSourceFrames.push(i);
+  return { rows, missingSourceFrames, misassociated, invalid: false, reason: "" };
+}
+
+// src/usePreviewAudio.ts
+var import_video_core9 = require("@pictor-sdk/video-core");
+var import_react4 = require("react");
+
+// src/previewAudioDiagnostics.ts
+var previewAudioDiagnostics = {
+  suppressPublications: false,
+  logPublications: false,
+  published: 0,
+  suppressed: 0
+};
+function publishState(name, set) {
+  return (value) => {
+    if (previewAudioDiagnostics.suppressPublications) {
+      previewAudioDiagnostics.suppressed += 1;
+      return;
+    }
+    previewAudioDiagnostics.published += 1;
+    if (previewAudioDiagnostics.logPublications) {
+      console.log(`AUDIOPUB ${name} ${JSON.stringify(value ?? null)}`);
+    }
+    set(value);
+  };
+}
+
+// src/usePreviewAudio.ts
+function usePreviewAudio(options) {
+  const { project, enabled = true } = options;
+  const resolveSource = (0, import_react4.useRef)(options.resolveSource);
+  resolveSource.current = options.resolveSource;
+  const [status, setStatusState] = (0, import_react4.useState)("source");
+  const [error, setErrorState] = (0, import_react4.useState)(null);
+  const [readyKey, setReadyKeyState] = (0, import_react4.useState)(null);
+  const [lastPrepareMs, setLastPrepareMsState] = (0, import_react4.useState)(null);
+  const [lastProfile, setLastProfileState] = (0, import_react4.useState)(null);
+  const [mix, setMix] = (0, import_react4.useState)(null);
+  const setStatus = (0, import_react4.useMemo)(() => publishState("status", setStatusState), [setStatusState]);
+  const setError = (0, import_react4.useMemo)(() => publishState("error", setErrorState), [setErrorState]);
+  const setReadyKey = (0, import_react4.useMemo)(
+    () => publishState("readyKey", setReadyKeyState),
+    [setReadyKeyState]
+  );
+  const setLastPrepareMs = (0, import_react4.useMemo)(
+    () => publishState("lastPrepareMs", setLastPrepareMsState),
+    [setLastPrepareMsState]
+  );
+  const setLastProfile = (0, import_react4.useMemo)(
+    () => publishState("lastProfile", setLastProfileState),
+    [setLastProfileState]
+  );
+  const preparingKey = (0, import_react4.useRef)(null);
+  const failedKey = (0, import_react4.useRef)(null);
+  const epoch = (0, import_react4.useRef)(0);
+  const mounted = (0, import_react4.useRef)(true);
+  const wanted = (0, import_react4.useMemo)(() => {
+    if (!enabled || project.audio.length === 0) {
+      return {
+        key: "",
+        programJson: "",
+        urisJson: "",
+        durationUs: 0,
+        unresolved: []
+      };
+    }
+    const program = (0, import_video_core9.compileAudioMixProgram)(project);
+    const resolved = resolveMixSources(project, program, (s, c) => resolveSource.current(s, c));
+    const programJson = JSON.stringify(program);
+    const urisJson = JSON.stringify(resolved.uris);
+    return {
+      key: resolved.unresolved.length > 0 ? "" : previewMixKey(programJson, urisJson),
+      programJson,
+      urisJson,
+      durationUs: Number(program.durationUs),
+      unresolved: resolved.unresolved
+    };
+  }, [project, enabled]);
+  const decision = decidePreviewAudio({
+    wantedKey: wanted.key,
+    readyKey,
+    preparingKey: preparingKey.current,
+    failedKey: failedKey.current
+  });
+  const unresolved = wanted.unresolved.length > 0 && enabled && project.audio.length > 0;
+  (0, import_react4.useEffect)(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+  (0, import_react4.useEffect)(() => {
+    if (!enabled) return;
+    try {
+      requireNative().previewMuteSourceAudio(decision.muteSourceAudio || unresolved);
+    } catch {
+    }
+  }, [decision.muteSourceAudio, unresolved, enabled]);
+  (0, import_react4.useEffect)(() => {
+    if (unresolved) {
+      setStatus("failed");
+      setError(wanted.unresolved[0] ?? "a sound could not be read");
+      return;
+    }
+    setStatus(decision.status);
+    if (decision.status !== "failed") setError(null);
+  }, [decision.status, unresolved, wanted.unresolved, setError, setStatus]);
+  (0, import_react4.useEffect)(() => {
+    if (!decision.shouldPrepare || unresolved) return;
+    const key = wanted.key;
+    preparingKey.current = key;
+    const jobId = `preview-${key.slice(0, 8)}-${epoch.current + 1}`;
+    const startedAt = Date.now();
+    void preparePreviewMix(jobId, wanted.programJson, wanted.urisJson).then((result) => {
+      if (!mounted.current) return;
+      if (result.ok === false && result.superseded) return;
+      if (key !== preparingKey.current) return;
+      preparingKey.current = null;
+      if (result.ok === false) {
+        failedKey.current = key;
+        setError(result.reason);
+        setStatus("failed");
+        return;
+      }
+      failedKey.current = null;
+      epoch.current += 1;
+      setLastPrepareMs(result.cached ? null : Date.now() - startedAt);
+      setLastProfile(result.cached ? null : result.profile ?? null);
+      try {
+        requireNative().previewAudioLoad(result.uri, epoch.current);
+      } catch {
+        failedKey.current = key;
+        setError("the prepared mix could not be opened");
+        setStatus("failed");
+        return;
+      }
+      setMix({ uri: result.uri, durationUs: Number(wanted.durationUs) });
+      setReadyKey(result.key);
+      sweepPreviewMixes([result.key]);
+    });
+  }, [
+    decision.shouldPrepare,
+    wanted.key,
+    wanted.programJson,
+    wanted.urisJson,
+    unresolved,
+    setError,
+    setLastPrepareMs,
+    setLastProfile,
+    setReadyKey,
+    setStatus
+  ]);
+  const release = (0, import_react4.useCallback)(() => {
+    cancelPreviewMix();
+    try {
+      requireNative().previewSyncStop("release");
+      requireNative().previewAudioRelease();
+      requireNative().previewMuteSourceAudio(false);
+    } catch {
+    }
+    preparingKey.current = null;
+    setReadyKey(null);
+    setMix(null);
+  }, [setReadyKey]);
+  (0, import_react4.useEffect)(() => release, [release]);
+  return {
+    status: unresolved ? "failed" : status,
+    error,
+    canPlay: !unresolved && decision.canPlay,
+    ready: decision.status === "ready",
+    lastPrepareMs,
+    lastProfile,
+    // Null until a mix matching the document is ready, so a composition built
+    // from it is never built from a stale one.
+    mix: decision.status === "ready" ? mix : null,
+    release
+  };
+}
+
+// src/encoderGate.ts
+var ENCODER_GATE_FIXTURES = [
+  "short",
+  "acceptance",
+  "silence",
+  "saturated",
+  "markers"
+];
+function runEncoderGate(fixture, maxInputSize = 65536) {
+  try {
+    return JSON.parse(requireNative().encoderGateRun(fixture, maxInputSize));
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+// src/previewTrace.ts
+var EMPTY2 = {
+  ok: false,
+  valid: false,
+  fault: "trace unavailable",
+  events: [],
+  nextSeq: 0,
+  total: 0,
+  dropped: 0
+};
+function armPreviewTrace(on, intervalMs = 25) {
+  try {
+    const value = JSON.parse(requireNative().previewTraceArm(on, intervalMs));
+    return value.ok === true;
+  } catch {
+    return false;
+  }
+}
+function markPreviewTrace(label) {
+  try {
+    requireNative().previewTraceMark(label);
+  } catch {
+  }
+}
+function drainPreviewTrace(fromSeq, limit = 200) {
+  try {
+    const value = JSON.parse(requireNative().previewTraceDrain(fromSeq, limit));
+    return value.ok ? value : EMPTY2;
+  } catch {
+    return EMPTY2;
+  }
+}
+function drainAllPreviewTrace(limit = 200) {
+  const events = [];
+  let seq = 0;
+  let dropped = 0;
+  let total = 0;
+  let valid = true;
+  let fault = null;
+  for (let guard = 0; guard < 200; guard += 1) {
+    const page = drainPreviewTrace(seq, limit);
+    if (page.fault) {
+      valid = false;
+      fault = page.fault;
+    }
+    if (!page.ok || page.events.length === 0) {
+      total = page.total || total;
+      break;
+    }
+    events.push(...page.events);
+    dropped += page.dropped;
+    total = page.total;
+    if (page.nextSeq === seq) break;
+    seq = page.nextSeq;
+  }
+  return { ok: true, valid, fault, events, nextSeq: seq, total, dropped };
+}
+function summariseOffsets(events) {
+  let n = 0;
+  let stale = 0;
+  let absent = 0;
+  let fresh = 0;
+  let staleRun = 0;
+  let longestStaleRun = 0;
+  let min = Number.POSITIVE_INFINITY;
+  let max = Number.NEGATIVE_INFINITY;
+  let sum = 0;
+  let samples = 0;
+  for (const e of events) {
+    if (e.type !== "sample") continue;
+    samples += 1;
+    if (e.v.pfFresh === void 0) {
+      absent += 1;
+      staleRun += 1;
+      if (staleRun > longestStaleRun) longestStaleRun = staleRun;
+    } else if (e.v.pfFresh === false) {
+      stale += 1;
+      staleRun += 1;
+      if (staleRun > longestStaleRun) longestStaleRun = staleRun;
+    } else {
+      fresh += 1;
+      staleRun = 0;
+    }
+    if (e.v.videoPlaying !== true || e.v.audioPlaying !== true) continue;
+    const offset = Number(e.v.offsetUs);
+    if (!Number.isFinite(offset)) continue;
+    n += 1;
+    sum += offset;
+    if (offset < min) min = offset;
+    if (offset > max) max = offset;
+  }
+  return {
+    samples,
+    playingSamples: n,
+    staleFrameSamples: stale,
+    absentFrameSamples: absent,
+    freshFrameSamples: fresh,
+    longestStaleRun,
+    minUs: n > 0 ? min : 0,
+    maxUs: n > 0 ? max : 0,
+    meanUs: n > 0 ? Math.round(sum / n) : 0,
+    worstAbsUs: n > 0 ? Math.max(Math.abs(min), Math.abs(max)) : 0
+  };
+}
+function previewSyncCounters() {
+  try {
+    return JSON.parse(requireNative().previewSyncCounters());
+  } catch {
+    return { ok: false };
+  }
+}
+function stopPreviewForHost(reason) {
+  try {
+    requireNative().previewSyncStop(reason);
+  } catch {
+  }
+}
+function previewFramePipeline() {
+  try {
+    return JSON.parse(requireNative().previewFramePipeline());
+  } catch {
+    return {};
+  }
+}
+function setPreviewParts(parts) {
+  try {
+    const v = JSON.parse(requireNative().previewConfigSet(JSON.stringify(parts)));
+    return v.ok ? v : null;
+  } catch {
+    return null;
+  }
+}
+function previewParts() {
+  try {
+    return JSON.parse(requireNative().previewConfigGet());
+  } catch {
+    return null;
+  }
+}
+function muteSourceAudio(muted) {
+  try {
+    requireNative().previewMuteSourceAudio(muted);
+  } catch {
+  }
+}
+function previewCodecLedger() {
+  try {
+    return JSON.parse(requireNative().previewCodecLedger());
+  } catch {
+    return { live: -1, peakLive: -1, total: 0, entries: [] };
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AndroidVideoPlayer,
+  CONVERGED_RUN,
+  DEFAULT_CEILING_BYTES,
+  DEFAULT_RISE_BYTES,
+  DEFAULT_WINDOW_SAMPLES,
+  ENCODER_GATE_FIXTURES,
+  EXPORT_STAGES,
+  MAX_OBSERVED_HEARTBEAT_GAP_MS,
+  MAX_RECOVERY_SAMPLES,
+  Media3,
+  MediaSaveCancelled,
+  MediaSaveFailed,
+  NO_SURFACE,
+  PHASE_MARK_PREFIX,
+  PREVIEW_DRIFT_TOLERANCE_US,
+  PREVIEW_OUTPUT_FPS,
+  PREVIEW_TOLERANCE_US,
+  RECOVERY_GRACE_MS,
+  SPIKE_TOLERANCE_US,
+  STALL_GRACE_MS,
+  VideoExportRejected,
+  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,
+  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
+});
+//# sourceMappingURL=index.js.map