supervision 0.2.4 → 0.2.6

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

@@ -165,7 +165,7 @@ export declare const FRAME_TIMELINE: {
  * session path that is a probe plus a walk from the enclosing sync sample,
  * measured at 49ms mean / 80ms worst on a 2840x2840 15fps source, flat in how
  * far the jump travelled. Coverage past the window is worth having, not worth
- * having crisp, so it lives in the preview tier at a 79th of the bytes.
+ * having crisp, so it lives in the smaller preview tier.
  *
  * resolveCacheBudgets turns these into a per-source budget from
  * navigator.deviceMemory and the decode frame size. A crisp slot costs
@@ -187,9 +187,8 @@ export declare const FRAME_TIMELINE: {
  * PREVIEW_SLOTS_MAX: the preview slot count is its byte budget over the
  * downscaled frame size, capped here. No floor pairs with it: raising a starved
  * count means overspending the byte budget, when the frame width is what a wide
- * preview has to give up. At a 79th of a crisp slot the tier carries the
- * timeline coverage an 8MP source cannot afford crisply: 163 slots against the
- * exact tier's 13, 11s of a 15fps clip.
+ * preview has to give up. A 320px square preview costs about a 79th of an
+ * 8MP crisp slot, so that source keeps coarse history beyond its exact window.
  *
  * SKIP_NEAR_MS: cache lookups that resolve to a frame within this many
  * milliseconds of what the visible canvas already shows are rejected so the

package/dist/web-video-engine/create-scrub-cursor.d.ts

@@ -16,6 +16,7 @@ export interface ScrubViewport {
  */
 export interface ScrubCacheConfig {
     previewWidth: number;
+    fitPreviewToOutput?: boolean;
     previewCapacity?: number;
     exactBudgetBytes?: number;
 }

package/dist/web-video-engine/decode-resolution-fynpRIAG.js

@@ -0,0 +1,109 @@
+/**
+ * Decode-resolution strategies. A strategy decides the pixel width each video
+ * frame is decoded to, independent of the source's native resolution. Height
+ * follows from native aspect, so a strategy only ever returns a width.
+ *
+ * Decoding below native trades preview sharpness for paint cost and frame-cache
+ * memory. It does NOT cut decode cost: the codec decodes the full coded frame
+ * regardless of target width, and CanvasSink resizes the result afterward. The
+ * win scales with the gap between source resolution and the on-screen box: a 4K
+ * source shown in a 640px surface still pays full 4K decode, but the smaller
+ * surface cuts the per-frame paint work and the cached blit size.
+ *
+ * A strategy applies wherever frames decode through this seam: the live scrub
+ * surface and the analysis / extraction path alike. AnalysisSession decodes at
+ * whatever strategy it is given (native when omitted), so a thumbnail pass can
+ * cache a small blit instead of a native-size one.
+ */
+/** Decode at native resolution. The conservative default. */
+function nativeResolution() {
+    return { kind: "native" };
+}
+/**
+ * Decode at the on-screen size: canvas CSS width times devicePixelRatio. Best
+ * for fixed-size surfaces fed by a much larger source (frame sampler, inline
+ * players). Falls back to native while the box is unmeasured.
+ *
+ * The box it reads is the one bindCanvas measures, so this strategy resolves to
+ * native under presentation "frames", where the engine holds no canvas and
+ * nothing ever measures one. A frames-mode consumer passes displayBoxResolution
+ * instead.
+ */
+function viewportResolution(options = {}) {
+    return {
+        kind: "viewport",
+        maxDevicePixelRatio: options.maxDevicePixelRatio ?? 2,
+    };
+}
+/**
+ * Decode at no more than maxWidth regardless of display size. For consumers
+ * with a hard throughput or memory ceiling (batch surfaces, thumbnail farms).
+ */
+function cappedResolution(maxWidth) {
+    return { kind: "capped", maxWidth };
+}
+/**
+ * Decode at the size the frame will actually occupy inside a box the consumer
+ * describes: native aspect fitted into boxWidth x boxHeight, times the clamped
+ * device pixel ratio. Letterboxing is why the box is two numbers and not one,
+ * since a portrait source in a landscape box paints far narrower than the box.
+ *
+ * This is the strategy for presentation "frames". There the consumer owns the
+ * compositor, so it is the only side that knows the box, and viewportResolution
+ * has nothing to read.
+ */
+function displayBoxResolution(options) {
+    return {
+        kind: "displayBox",
+        boxWidth: options.boxWidth,
+        boxHeight: options.boxHeight,
+        devicePixelRatio: options.devicePixelRatio,
+        maxDevicePixelRatio: options.maxDevicePixelRatio ?? 2,
+    };
+}
+/** Runs the descriptor against a context to produce a target decode width. */
+function strategyWidth(strategy, ctx) {
+    switch (strategy.kind) {
+        case "native":
+            return ctx.nativeWidth;
+        case "viewport": {
+            if (ctx.displayWidth === null || ctx.displayWidth <= 0)
+                return ctx.nativeWidth;
+            const dpr = clampDpr(ctx.devicePixelRatio, strategy.maxDevicePixelRatio);
+            return Math.ceil(ctx.displayWidth * dpr);
+        }
+        case "capped":
+            return Math.min(strategy.maxWidth, ctx.nativeWidth);
+        case "displayBox": {
+            const { boxWidth, boxHeight } = strategy;
+            if (!(boxWidth > 0) || !(boxHeight > 0))
+                return ctx.nativeWidth;
+            const fit = Math.min(boxWidth / ctx.nativeWidth, boxHeight / ctx.nativeHeight);
+            const dpr = clampDpr(strategy.devicePixelRatio, strategy.maxDevicePixelRatio);
+            return Math.ceil(ctx.nativeWidth * fit * dpr);
+        }
+    }
+}
+/**
+ * Runs a strategy and returns native-bounded, aspect-preserving integer
+ * dimensions safe to hand to CanvasSink and to size a canvas backing store.
+ * A strategy that returns garbage (non-finite, non-positive) falls back to
+ * native rather than producing a broken surface.
+ */
+function resolveDecodeDimensions(strategy, ctx) {
+    const nativeWidth = Math.max(1, Math.round(ctx.nativeWidth));
+    const nativeHeight = Math.max(1, Math.round(ctx.nativeHeight));
+    const raw = strategyWidth(strategy, ctx);
+    const width = Number.isFinite(raw) && raw > 0
+        ? Math.min(Math.round(raw), nativeWidth)
+        : nativeWidth;
+    const height = Math.max(1, Math.round((width * nativeHeight) / nativeWidth));
+    return { width, height };
+}
+function clampDpr(dpr, maxDpr) {
+    if (!Number.isFinite(dpr) || dpr <= 0)
+        return 1;
+    return Math.min(dpr, maxDpr);
+}
+
+export { cappedResolution as c, displayBoxResolution as d, nativeResolution as n, resolveDecodeDimensions as r, viewportResolution as v };

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

@@ -324,6 +324,7 @@ export declare class DecodeScheduler implements ScrubCursor {
     private runPrefetch;
     private runExactWindow;
     private runPreviewSweep;
+    private residentPreviewAt;
     private decodeInto;
     /**
      * One sweep pull, ended by abandonment rather than by the decode it is

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

@@ -211,8 +211,10 @@ export declare class EngineCore {
      *
      * An exact walk answers at or before the frame it aimed at, and no further
      * back than the sample next to it, so the target falls inside the answering
-     * frame's own span. That span is the whole test: a frame decoded for some
-     * earlier position sits outside it however recently it was painted.
+     * frame's own span. That span is the test: a frame decoded for some earlier
+     * position sits outside it however recently it was painted. The aimed-at
+     * frame answers without it, because a track's last frame has an empty span
+     * when its file states no duration for it.
      */
     private answersAwaitedSeek;
     /** The frame table of the loaded source. Reached only from paths that have