supervision 0.2.0-next.0 → 0.2.0-next.2

package/dist/web-video-engine/decode-source.d.ts

@@ -1,6 +1,7 @@
 import { BlobSource, ReadableStreamSource, UrlSource } from "mediabunny";
 import type { CreateScrubCursorOptions } from "./create-scrub-cursor";
 import { type SessionFrameSource } from "./decode-session";
+import { type DecodeDimensions } from "./decode-resolution";
 import type { SourceResidency } from "./source-residency";
 import type { KeyframeProbe } from "./keyframe-index";
 import { type ScrubTrackInfo, type VideoSampleLike } from "./scrub-cursor";
@@ -97,6 +98,7 @@ export type DecodedFrame = {
  * which the scheduler reports so a human can see which machinery is decoding.
  */
 export interface FrameProvider {
+    resizeOutput?(dimensions: DecodeDimensions): Promise<void>;
     readonly decodePath: DecodePath;
     readonly track: ScrubTrackInfo;
     readonly keyframeProbe: KeyframeProbe;
@@ -220,6 +222,15 @@ export interface DecodeSessionContext {
      *  anchor trick applies to this bitstream. */
     readonly decoderConfig: VideoDecoderConfig;
 }
+/** Platform facts used to contain decoder-output ownership to Android.
+ * Client hints win when available so desktop UA emulation cannot accidentally
+ * turn the expensive path on. */
+export interface DecodeSessionPixelOwnershipContext {
+    readonly clientPlatform?: string;
+    readonly userAgent?: string;
+    readonly offscreenCanvasAvailable: boolean;
+}
+export declare function shouldOwnDecodeSessionPixels(context: DecodeSessionPixelOwnershipContext): boolean;
 /**
  * The gate. The session reaches a non-IDR anchor by declaring it a recovery
  * point, which only holds for AVCC-framed H.264 carrying its parameter sets, so
@@ -247,4 +258,3 @@ export declare function toMediabunnySource(source: VideoSource, residency?: Sour
  * to a degraded-but-alive state instead of rebuilding for that kind.
  */
 export declare function isReopenableSource(source: VideoSource): boolean;
-//# sourceMappingURL=decode-source.d.ts.map

package/dist/web-video-engine/diagnostics-store.d.ts

@@ -15,4 +15,3 @@ export declare class DiagnosticsStore {
     write(snapshot: DiagnosticsSnapshot): void;
     subscribe(listener: () => void): () => void;
 }
-//# sourceMappingURL=diagnostics-store.d.ts.map

package/dist/web-video-engine/diagnostics.d.ts

@@ -20,9 +20,10 @@ export interface DiagnosticsTrack {
  * owned, null on the uncached cursor). All plain data, so it crosses the worker
  * boundary by structured clone.
  *
- * This is the legacy getStats shape, kept as a back-compat subset of the richer
- * DiagnosticsSnapshot the broadcast plane carries. Existing getStats consumers
- * read these three fields; the diagnostics instrument reads the superset.
+ * What `getStats` answers with, one round trip per call and no broadcast timer
+ * required. {@link DiagnosticsSnapshot} opens with these same three fields and
+ * carries the rest of the instrument payload, but only while the diagnostics
+ * broadcast is running.
  */
 export interface EngineDiagnostics {
     readonly renderer: RendererName | null;
@@ -182,21 +183,6 @@ export interface Warning {
     readonly advice: string;
     readonly evidence: string;
 }
-/**
- * The clone-safe wire snapshot the worker broadcasts at BROADCAST_HZ. A superset
- * of EngineDiagnostics: it keeps renderer/track/scheduler verbatim so legacy
- * readers still resolve, and adds the realtime needles, the pipeline ledger,
- * derived cache bytes, track geometry, GOP block, scrub aggregates, the
- * play-time seek block, counters, memory, the clock/screen pair, and the
- * worker-evaluated warnings. Only plain data crosses the boundary.
- *
- * webgpuAvailable and memory.jsHeapUsedBytes are the fields the worker leaves at
- * their empty value for the main thread to fill after the broadcast, so a rule
- * in evaluateWarnings (which runs in the worker) can never read them, and an
- * exported trace, assembled worker-side, carries the unfilled value. Warnings
- * are evaluated once, worker-side, so the HUD and an exported trace always show
- * the same diagnoses.
- */
 /**
  * Source bytes this process holds, for a host that wants to show a viewer how
  * much of the clip is local. Null unless the engine was loaded with
@@ -213,6 +199,21 @@ export interface SourceResidencyDiagnostics {
     readonly prefetchedBytes: number;
     readonly warming: boolean;
 }
+/**
+ * The clone-safe wire snapshot the worker broadcasts at BROADCAST_HZ. A superset
+ * of {@link EngineDiagnostics}: renderer, track and scheduler carry the same
+ * values, and it adds the realtime needles, the pipeline ledger, derived cache
+ * bytes, track geometry, GOP block, scrub aggregates, the play-time seek block,
+ * counters, memory, the clock/screen pair, and the worker-evaluated warnings.
+ * Only plain data crosses the boundary.
+ *
+ * webgpuAvailable and memory.jsHeapUsedBytes are the fields the worker leaves at
+ * their empty value for the main thread to fill after the broadcast, so a rule
+ * in evaluateWarnings (which runs in the worker) can never read them, and an
+ * exported trace, assembled worker-side, carries the unfilled value. Warnings
+ * are evaluated once, worker-side, so the HUD and an exported trace always show
+ * the same diagnoses.
+ */
 export interface DiagnosticsSnapshot {
     /**
      * Which presentation the engine was loaded for. `renderer` and the geometry
@@ -313,4 +314,3 @@ export declare function cacheLookups(cache: FrameCacheStats | null | undefined):
  * UI and the trace share) and in tests. No I/O, no side effects.
  */
 export declare function evaluateWarnings(snapshot: DiagnosticsSnapshot): Warning[];
-//# sourceMappingURL=diagnostics.d.ts.map

package/dist/web-video-engine/embedded-engine-worker.d.ts

@@ -1,2 +1 @@
 export declare const EMBEDDED_ENGINE_WORKER_SOURCE = "__SUPERVISION_JS_EMBEDDED_ENGINE_WORKER_SOURCE__";
-//# sourceMappingURL=embedded-engine-worker.d.ts.map

package/dist/web-video-engine/engine-core.d.ts

@@ -1,5 +1,6 @@
 import { type MediaClock } from "./clock";
-import type { FrameLanding } from "./frame-timeline";
+import { type DisplayBoxResolutionOptions } from "./decode-resolution";
+import type { FrameId, FrameLanding } from "./frame-timeline";
 import { type EngineDiagnostics } from "./diagnostics";
 import { type SeekIntent } from "./scrub-cursor";
 import { type EngineTrace } from "./trace-recorder";
@@ -38,6 +39,8 @@ export interface EngineCoreOptions {
  * the core never emits a competing time that would yank a settled playhead.
  */
 export declare class EngineCore {
+    private decodeStrategy;
+    private displayResize;
     private readonly emit;
     private readonly emitDiagnostics;
     private readonly emitPresentedFrame;
@@ -82,6 +85,7 @@ export declare class EngineCore {
      *  so without the target on it any leftover frame answers for the seek in
      *  flight and publishes itself as the playhead. */
     private awaitedSeek;
+    private seekGeneration;
     /** Wall stamp of a seek being served by re-anchoring the playback walk, or
      *  null when no such seek is waiting on its crisp frame. */
     private playSeekStartedAtMs;
@@ -91,7 +95,13 @@ export declare class EngineCore {
     private playSeekMaxMs;
     /** The frame the last paint put up, for the diagnostics screen readout. */
     private lastPaintedId;
-    /** Mirrors VideoEngine's interactive-seek latch: true when a drag paused a
+    /** Last frame the host confirmed reached its display surface. */
+    private lastHostFrame;
+    /** Rejects an older refresh that completes after a newer one in one epoch. */
+    private lastHostPaintSeq;
+    /** Main-thread visibility pauses only the wait for host presentation. */
+    private presentationVisible;
+    /** Mirrors WebVideoEngine's interactive-seek latch: true when a drag paused a
      *  playing engine, so endInteractiveSeek knows to resume. */
     private resumeAfterInteractiveSeek;
     /** Worker-realm broadcast timer handle, or null when diagnostics are off. */
@@ -117,6 +127,8 @@ export declare class EngineCore {
      */
     setCanvas(canvas: OffscreenCanvas | null, viewport?: SerializedViewport): void;
     load(config: EngineLoadConfig): Promise<EngineReadySnapshot>;
+    setDisplay(display: DisplayBoxResolutionOptions): Promise<boolean>;
+    private afterDisplayResize;
     play(): void;
     pause(): void;
     togglePlayback(): void;
@@ -160,13 +172,11 @@ export declare class EngineCore {
      *  exported trace shows the playback-state timeline alongside paints/seeks. */
     private emitStatus;
     /**
-     * The decoder cannot decode this source, and nothing else was going to say
-     * so: a stalled decoder keeps accepting commands and the clock keeps
-     * running, so playback reads as healthy over a canvas that will never change
-     * again. Stop the transport first, then report, so the status a consumer
-     * sees and what the engine is doing agree.
+     * The runtime can no longer deliver pixels, whether decoding stopped or the
+     * frames handoff failed. Stop the transport first, then report, so the status
+     * a consumer sees and what the engine is doing agree.
      */
-    private handleDecodeFailure;
+    private handleTerminalFailure;
     /** Says the failure again for whoever just asked the transport to move. A
      *  consumer that only listens for changes has already been told; one that
      *  reads the status after its own command has to find the same answer. */
@@ -175,7 +185,7 @@ export declare class EngineCore {
     endInteractiveSeek(): void;
     dispose(): Promise<void>;
     /** True only when the cursor exists and reports settled. Mirrors
-     *  VideoEngine.isIdle for tests; the facade derives its own from state. */
+     *  WebVideoEngine.isIdle for tests; the facade derives its own from state. */
     isIdle(): boolean;
     /** Engine diagnostics snapshot (renderer, track facts, scheduler stats), or
      *  null before load. The scheduler field is null on the uncached cursor. */
@@ -183,7 +193,14 @@ export declare class EngineCore {
     private observeSeekIdle;
     private handleEnded;
     private awaitSeekLanding;
+    /** Main-thread document visibility; decoding/watchdogs remain active. */
+    setPresentationVisibility(visible: boolean): void;
+    private isCurrentSeek;
     private forgetSeekLanding;
+    private abandonAwaitedSeek;
+    /** Ends an impossible landing. Awaitable movement rejects with the engine's
+     *  terminal error; a scrub has no consumer, so it is released quietly. */
+    private failAwaitedSeek;
     /** Releases the latch of a seek that has already answered its caller. The
      *  landing rode back on the return value, so a paint arriving after it would
      *  move the playhead to somewhere the caller was never told about. */
@@ -200,7 +217,6 @@ export declare class EngineCore {
     /** The frame table of the loaded source. Reached only from paths that have
      *  already established a cursor, which is what carries it. */
     private timeline;
-    private landingOf;
     /**
      * Points the background walk at where the viewer is, as a byte offset. The
      * file's own byte layout is not exposed, so this reads position as a share of
@@ -209,6 +225,11 @@ export declare class EngineCore {
      */
     private aimResidency;
     private onPaint;
+    /** Makes only a frame the host actually rendered authoritative for playback
+     *  time and pause settlement. An older navigation or refresh cannot move the
+     *  clock backward after a newer frame has won. */
+    acknowledgePresentedFrame(paintSeq: number, frameId: FrameId, navigationGeneration: number): void;
+    private beginPresentationGeneration;
     /**
      * Posts one frame with the identity of the paint it came from, in the same
      * message. With no sink wired there is no receiver, so the frame is closed
@@ -255,4 +276,3 @@ export declare class EngineCore {
     private devicePixelRatio;
     private traceEnvironment;
 }
-//# sourceMappingURL=engine-core.d.ts.map

package/dist/web-video-engine/engine.d.ts

@@ -1,5 +1,5 @@
-export { VideoEngine } from "./video-engine";
-export type { VideoEngineHandle, VideoEngineOptions } from "./video-engine";
+export { WebVideoEngine } from "./video-engine";
+export type { WebVideoEngineHandle, WebVideoEngineOptions, } from "./video-engine";
 export { SourceKind } from "./types";
 export type { BlobVideoSource, StreamVideoSource, UrlSourceReadConfig, UrlVideoSource, VideoMetadata, VideoSource, } from "./types";
 export { PlaybackStatus } from "./types";
@@ -18,9 +18,8 @@ export { asFps, asPaintSeq, asSec } from "./types";
 export type { Fps, Sec } from "./types";
 export { cappedResolution, displayBoxResolution, nativeResolution, viewportResolution, } from "./decode-resolution";
 export type { DecodeResolutionStrategy, DisplayBoxResolutionOptions, ViewportResolutionOptions, } from "./decode-resolution";
-export { VideoEngineError, VideoEngineErrorCode } from "./types";
+export { WebVideoEngineError, WebVideoEngineErrorCode } from "./types";
 export type { Warning, WarningSeverity } from "./diagnostics";
 export type { DiagnosticsSnapshot, SourceResidencyDiagnostics, } from "./diagnostics";
 export type { SourceResidencyConfig } from "./worker-protocol";
 export { DIAGNOSTICS, TRACE_RING_BOUNDS } from "./constants";
-//# sourceMappingURL=engine.d.ts.map