@hyperframes/engine 0.6.111 → 0.6.113

package/src/services/frameCapture.ts

@@ -51,6 +51,30 @@ export interface CaptureSession {
   outputDir: string;
   onBeforeCapture: BeforeCaptureHook | null;
   isInitialized: boolean;
+  /**
+   * Static-frame dedup (default-on; opt out with `HF_STATIC_DEDUP=false`): indices of frames byte-identical
+   * to their predecessor (no GSAP tween / clip cut active in either), predicted from
+   * window.__timelines and empirically anchor-verified. These reuse `lastFrameBuffer`
+   * instead of re-seeking + re-screenshotting. Undefined when disabled or ineligible.
+   */
+  staticFrames?: Set<number>;
+  /** Last non-deduped frame buffer, reused for every `staticFrames` index in its run. */
+  lastFrameBuffer?: Buffer;
+  /** Count of frames served from a reused buffer (dedup telemetry). */
+  staticDedupCount?: number;
+  // ── Static-dedup observability (set by armStaticDedup; surfaced via
+  // getCapturePerfSummary → RenderPerfSummary → the render_complete event) ──
+  // NOTE: `armed` and `predicted` are NOT stored — they derive from
+  // `staticFrames` (armed ⟺ non-empty set; predicted === size) in
+  // getCapturePerfSummary, so they can't desync from the actual reuse set.
+  /** Dedup was enabled for this render (default-on; opt out with `HF_STATIC_DEDUP=false`). */
+  staticDedupEnabled?: boolean;
+  /**
+   * Short machine code for WHY dedup did not arm, for a low-cardinality breakdown.
+   * One of: `capture_mode` | `video_injection` | `page_composite` |
+   * `ineligible` | `verification_failed` | `verification_budget`. Undefined when armed or disabled.
+   */
+  staticDedupSkipReason?: string;
   // Tracks whether the page/browser handles have already been released by
   // closeCaptureSession. Used to make closeCaptureSession idempotent under
   // browser-pool semantics (see the function body for the full invariant).
@@ -1021,6 +1045,7 @@ export async function initializeSession(session: CaptureSession): Promise<void>
       await initTransparentBackground(session.page);
     }
 
+    await armStaticDedup(session, session.page, logInitPhase);
     session.isInitialized = true;
     return;
   }
@@ -1170,6 +1195,7 @@ export async function initializeSession(session: CaptureSession): Promise<void>
     await initTransparentBackground(session.page);
   }
 
+  await armStaticDedup(session, session.page, logInitPhase);
   session.isInitialized = true;
 }
 
@@ -1280,6 +1306,335 @@ async function prepareFrameForCapture(
   return { quantizedTime, seekMs, beforeCaptureMs };
 }
 
+// ── Static-frame dedup (default-on, opt-out HF_STATIC_DEDUP=false) ─────────────
+// Skip re-seeking + re-screenshotting frames that are byte-identical to their
+// predecessor. A frame is dedupable iff no GSAP tween or clip cut is active in it or
+// its predecessor (predicted from window.__timelines), AND an empirical anchor-compare
+// confirms it. Capture-mode-independent (works on screenshot + beginframe), lossless
+// (verification disables the whole comp on any drift), default off. Pays on
+// static-hold content (title cards, slideshows, data-viz pauses); a no-op on
+// continuously-animated comps and disqualified by video/canvas/non-GSAP animation.
+
+/**
+ * Clip-cut boundary frames (±1) from the [data-start] schedule. A hard scene swap at a
+ * cut changes content with no tween; treat those frames as animated so the post-cut
+ * frame is captured fresh and later static frames reuse the correct scene.
+ */
+async function computeClipBoundaryFrames(page: Page, fps: number): Promise<Set<number>> {
+  const schedule = await page.evaluate(() =>
+    Array.from(document.querySelectorAll("[data-start]")).map((el) => ({
+      start: parseFloat((el as HTMLElement).dataset.start || ""),
+      dur: parseFloat((el as HTMLElement).dataset.duration || ""),
+    })),
+  );
+  const frames = new Set<number>();
+  for (const { start, dur } of schedule) {
+    if (Number.isNaN(start)) continue;
+    const edges = [Math.round(start * fps)];
+    if (!Number.isNaN(dur)) edges.push(Math.round((start + dur) * fps));
+    for (const e of edges) {
+      for (const f of [e - 1, e, e + 1]) {
+        if (f >= 0) frames.add(f);
+      }
+    }
+  }
+  return frames;
+}
+
+/**
+ * Predict the dedupable (static) frame set from window.__timelines. A frame f (f>0) is
+ * static iff NEITHER f NOR f-1 falls inside any GSAP tween interval — content didn't
+ * change f-1→f, so f can reuse f-1's buffer. Requiring BOTH neighbours static under-
+ * claims by one frame at each tween edge (the SAFE direction). Disqualifies the whole
+ * comp on any signal the tween-walker can't see: video / canvas / webgl (redraw without
+ * a tween), zero tweens (non-GSAP animation), or a running CSS/WAAPI animation.
+ */
+async function computeStaticFrameSet(
+  page: Page,
+  fps: number,
+): Promise<{
+  totalFrames: number;
+  staticFrameSet: Set<number>;
+  hasVideo: boolean;
+  hasCanvas: boolean;
+  hasNonGsapAnim: boolean;
+  tweenCount: number;
+  eligible: boolean;
+  reason: string;
+}> {
+  const result = await page.evaluate(() => {
+    type AnyTween = {
+      startTime(): number;
+      duration(): number;
+      totalDuration?(): number;
+      getChildren?(nested: boolean, tweens: boolean, timelines: boolean): AnyTween[];
+    };
+    const intervals: Array<{ start: number; end: number }> = [];
+    let tweenCount = 0;
+    // totalDuration() (NOT duration()): a repeat/yoyo tween animates past one iteration;
+    // a repeating timeline is marked opaque over its whole span (conservative).
+    function walk(tl: AnyTween, offset: number): void {
+      if (typeof tl.getChildren !== "function") return;
+      for (const child of tl.getChildren(false, true, true)) {
+        const start = offset + (typeof child.startTime === "function" ? child.startTime() : 0);
+        const single = typeof child.duration === "function" ? child.duration() : 0;
+        const total = typeof child.totalDuration === "function" ? child.totalDuration() : single;
+        if (typeof child.getChildren === "function") {
+          if (total > single + 1e-6) intervals.push({ start, end: start + total });
+          else walk(child, start);
+        } else {
+          tweenCount++;
+          intervals.push({ start, end: start + total });
+        }
+      }
+    }
+    const w = window as unknown as {
+      __timelines?: Record<string, AnyTween>;
+      __hf?: { duration?: number };
+    };
+    for (const tl of Object.values(w.__timelines || {})) {
+      if (tl && typeof tl.getChildren === "function") walk(tl, 0);
+    }
+    const hasVideo = !!document.querySelector("video");
+    const hasCanvas = !!document.querySelector("canvas");
+    // A non-numeric data-start (reference expression like "intro+0.5") can't be turned
+    // into a clip-cut boundary by computeClipBoundaryFrames' parseFloat, so the cut goes
+    // unprotected and could be deduped into the previous scene. Disqualify the comp.
+    const hasUnresolvableClipStart = Array.from(document.querySelectorAll("[data-start]")).some(
+      (el) => {
+        const v = (el as HTMLElement).dataset.start;
+        return v != null && v.trim() !== "" && !Number.isFinite(parseFloat(v));
+      },
+    );
+    // Non-GSAP animation (CSS @keyframes / transitions / WAAPI) surfaces via
+    // getAnimations(); any running/paused one can change content without a tween.
+    let hasNonGsapAnim = false;
+    try {
+      const docAnims = (document as unknown as { getAnimations?: () => Animation[] }).getAnimations;
+      if (typeof docAnims === "function") {
+        hasNonGsapAnim = docAnims.call(document).some((a) => {
+          const t = a as Animation & { playState?: string };
+          return t.playState === "running" || t.playState === "paused";
+        });
+      }
+    } catch {
+      hasNonGsapAnim = true;
+    }
+    return {
+      intervals,
+      tweenCount,
+      duration: w.__hf?.duration ?? 0,
+      hasVideo,
+      hasCanvas,
+      hasNonGsapAnim,
+      hasUnresolvableClipStart,
+    };
+  });
+
+  const {
+    intervals,
+    tweenCount,
+    duration,
+    hasVideo,
+    hasCanvas,
+    hasNonGsapAnim,
+    hasUnresolvableClipStart,
+  } = result as {
+    intervals: Array<{ start: number; end: number }>;
+    tweenCount: number;
+    duration: number;
+    hasVideo: boolean;
+    hasCanvas: boolean;
+    hasNonGsapAnim: boolean;
+    hasUnresolvableClipStart: boolean;
+  };
+  const totalFrames = Math.max(1, Math.ceil(duration * fps));
+  const animated = new Set<number>();
+  for (const { start, end } of intervals) {
+    const lo = Math.max(0, Math.floor(start * fps));
+    const hi = Math.min(totalFrames - 1, Math.ceil(end * fps));
+    for (let f = lo; f <= hi; f++) animated.add(f);
+  }
+  for (const f of await computeClipBoundaryFrames(page, fps)) animated.add(f);
+  const reasons: string[] = [];
+  if (!(duration > 0)) reasons.push("unknown/zero duration");
+  if (hasVideo) reasons.push("video");
+  if (hasCanvas) reasons.push("canvas/webgl");
+  if (tweenCount === 0) reasons.push("no GSAP tweens (non-GSAP animation)");
+  if (hasNonGsapAnim) reasons.push("running CSS/WAAPI animation");
+  if (hasUnresolvableClipStart) reasons.push("unresolvable clip start (reference expression)");
+  const eligible = reasons.length === 0;
+  const staticFrameSet = new Set<number>();
+  if (eligible) {
+    for (let f = 1; f < totalFrames; f++) {
+      if (!animated.has(f) && !animated.has(f - 1)) staticFrameSet.add(f);
+    }
+  }
+  return {
+    totalFrames,
+    staticFrameSet,
+    hasVideo,
+    hasCanvas,
+    hasNonGsapAnim,
+    tweenCount,
+    eligible,
+    reason: eligible ? "eligible" : reasons.join("+"),
+  };
+}
+
+/**
+ * Empirically verify the predicted-static set before trusting it. Group static frames
+ * into runs; each run [a..b] reuses anchor a-1. CRITICAL: compare against the ANCHOR,
+ * not the predecessor — a slow drift with sub-quantization per-frame deltas is byte-
+ * identical frame-to-frame yet drifts far from the anchor by the run's end (the real
+ * frozen error). Capture each run's anchor once, compare END + a midpoint to it; any
+ * mismatch ⇒ the run isn't truly static ⇒ disable dedup whole-comp. Capture-mode-
+ * independent (seeks + screenshots in normal DOM). Returns the first bad frame, or null.
+ */
+async function verifyStaticFramesSafe(
+  session: CaptureSession,
+  page: Page,
+  staticFrames: Set<number>,
+  fps: number,
+  sampleCount: number,
+): Promise<{ badFrame: number; budgetExhausted: boolean } | null> {
+  const frames = [...staticFrames].sort((a, b) => a - b);
+  if (frames.length === 0) return null;
+  // Runs are maximal-contiguous (adjacent frames merge), so a run's anchor a-1 is
+  // guaranteed NOT static — always a freshly-captured frame.
+  const runs: Array<{ a: number; b: number }> = [];
+  for (const f of frames) {
+    const last = runs[runs.length - 1];
+    if (last && f === last.b + 1) last.b = f;
+    else runs.push({ a: f, b: f });
+  }
+  const seekCapture = async (frameIdx: number): Promise<Buffer> => {
+    const t = quantizeTimeToFrame(frameIdx / fps, fps);
+    await page.evaluate((tt: number) => {
+      const hf = (window as unknown as { __hf?: { seek?: (t: number) => void } }).__hf;
+      if (hf && typeof hf.seek === "function") hf.seek(tt);
+    }, t);
+    return pageScreenshotCapture(page, session.options);
+  };
+  // Verify EVERY run in order (no longest-first truncation that would leave runs armed
+  // but unverified). Per run, compare the FIRST reused frame `a`, the END `b` (max
+  // accumulated drift), and interior points at a stride — against the anchor the run
+  // actually reuses. `sampleCount` sets the interior density (points per run ~ that many
+  // for a long run); a hard cap bounds pathological run counts, and hitting it DISABLES
+  // dedup (conservative: never trust an unverified set).
+  const perRun = Math.max(3, Math.min(sampleCount, 8));
+  const hardCap = Math.max(sampleCount * 8, 400);
+  let spent = 0;
+  for (const { a, b } of runs) {
+    const anchor = a - 1;
+    if (anchor < 0) continue;
+    const anchorBuf = await seekCapture(anchor);
+    spent++;
+    const span = b - a;
+    const stride = span > 0 ? Math.max(1, Math.floor(span / (perRun - 1))) : 1;
+    const pts = new Set<number>();
+    for (let f = a; f <= b; f += stride) pts.add(f);
+    pts.add(b); // always include the end (max drift)
+    for (const f of [...pts].sort((x, y) => x - y)) {
+      const cur = await seekCapture(f);
+      spent++;
+      if (!anchorBuf.equals(cur)) return { badFrame: f, budgetExhausted: false };
+    }
+    // Budget exhausted → can't fully verify → disarm. Reported distinctly from real
+    // drift so a `verification_budget` spike in telemetry signals "tune HF_STATIC_DEDUP_SAMPLES",
+    // not "compositions are non-static".
+    if (spent > hardCap) return { badFrame: a, budgetExhausted: true };
+  }
+  return null;
+}
+
+/**
+ * Arm static-frame dedup for this render (default-on; opt out with HF_STATIC_DEDUP=false).
+ * Runs at init in normal DOM state so the verification screenshots are valid. Predicts
+ * the static set, anchor-verifies it (skip with HF_STATIC_DEDUP_VERIFY=false — unsafe),
+ * and on success stores it on the session for captureFrameCore to reuse. Sample budget
+ * via HF_STATIC_DEDUP_SAMPLES (default 24).
+ */
+async function armStaticDedup(
+  session: CaptureSession,
+  page: Page,
+  logInitPhase: (phase: string) => void,
+): Promise<void> {
+  // Default ON for everyone; opt out via HF_STATIC_DEDUP in {false,0,off} (resolved into
+  // EngineConfig.staticFrameDedup by resolveConfig). Verification is the safety net at scale.
+  // Default-on: only an explicit `staticFrameDedup === false` (resolved from
+  // HF_STATIC_DEDUP) disables; a missing config leaves dedup enabled.
+  session.staticDedupEnabled = session.config?.staticFrameDedup !== false;
+  if (!session.staticDedupEnabled) return;
+  // Conservative gates: dedup is verified against the plain screenshot path, so only arm
+  // where the production capture matches what verification measures, and where reuse is
+  // sound. Skip when:
+  //  - capture mode is not screenshot (BeginFrame advances the compositor clock per
+  //    frame; skipping beginFrame for static frames gaps the tick sequence, and the
+  //    verifier uses pageScreenshotCapture not beginFrameCapture — its proof wouldn't
+  //    transfer);
+  //  - a before-capture hook is set (per-frame video-frame injection — those frames are
+  //    NOT static even if the GSAP timeline is idle, and the injector is skipped on reuse);
+  //  - page-side compositing is active (shader transitions / drawElement composite paint
+  //    a frame the plain verification screenshot doesn't reproduce).
+  if (session.captureMode !== "screenshot") {
+    session.staticDedupSkipReason = "capture_mode";
+    logInitPhase(
+      `static-frame dedup: disabled (capture mode ${session.captureMode}, not screenshot)`,
+    );
+    return;
+  }
+  if (session.onBeforeCapture) {
+    session.staticDedupSkipReason = "video_injection";
+    logInitPhase("static-frame dedup: disabled (before-capture hook / video injection active)");
+    return;
+  }
+  const pageComposite = await page
+    .evaluate(
+      () =>
+        typeof (window as unknown as { __hf_page_composite_prepare?: unknown })
+          .__hf_page_composite_prepare === "function",
+    )
+    .catch(() => true); // fail CLOSED: if we can't determine, assume compositing → skip dedup
+  if (pageComposite) {
+    session.staticDedupSkipReason = "page_composite";
+    logInitPhase("static-frame dedup: disabled (page-side compositing active)");
+    return;
+  }
+  const fps = fpsToNumber(session.options.fps);
+  const stats = await computeStaticFrameSet(page, fps);
+  if (!stats.eligible || stats.staticFrameSet.size === 0) {
+    session.staticDedupSkipReason = "ineligible";
+    logInitPhase(`static-frame dedup: disabled (${stats.reason})`);
+    return;
+  }
+  const rawSamples = Number(process.env.HF_STATIC_DEDUP_SAMPLES ?? "24");
+  const samples = Number.isFinite(rawSamples) && rawSamples >= 1 ? rawSamples : 24;
+  const verdict =
+    process.env.HF_STATIC_DEDUP_VERIFY === "false"
+      ? null
+      : await verifyStaticFramesSafe(session, page, stats.staticFrameSet, fps, samples);
+  if (verdict !== null) {
+    session.staticDedupSkipReason = verdict.budgetExhausted
+      ? "verification_budget"
+      : "verification_failed";
+    logInitPhase(
+      verdict.budgetExhausted
+        ? `static-frame dedup: disabled (verification budget exhausted before frame ${verdict.badFrame}; ` +
+            `raise HF_STATIC_DEDUP_SAMPLES to verify more)`
+        : `static-frame dedup: disabled (verification failed — content drifts from anchor at ` +
+            `predicted-static frame ${verdict.badFrame})`,
+    );
+    return;
+  }
+  // armed + predicted are derived from staticFrames in getCapturePerfSummary.
+  session.staticFrames = stats.staticFrameSet;
+  logInitPhase(
+    `static-frame dedup: ${stats.staticFrameSet.size}/${stats.totalFrames} frame(s) reusable ` +
+      `(${Math.round((stats.staticFrameSet.size / stats.totalFrames) * 100)}%, verified)`,
+  );
+}
+
 /**
  * Internal core: prepare, screenshot, and track perf.
  * Shared by captureFrame (disk) and captureFrameToBuffer (buffer).
@@ -1293,6 +1648,30 @@ async function captureFrameCore(
   const { page, options } = session;
   const startTime = Date.now();
 
+  // Static-frame dedup: this frame is byte-identical to its predecessor (predicted +
+  // anchor-verified at init) → reuse the prior buffer, skip the seek + screenshot.
+  // KEY: index by the ABSOLUTE composition frame (derived from `time`), NOT the
+  // `frameIndex` arg — chunked/parallel/distributed callers pass a chunk-RELATIVE
+  // frameIndex (captureStage passes the loop `i`, parallelCoordinator passes
+  // `i-outputFrameOffset`) while staticFrames is keyed in absolute frames. Using `time`
+  // is correct on every path (sequential, per-worker range, distributed chunk) because
+  // `time` is always the absolute composition time for the frame. Each session captures
+  // its range in ascending order, so lastFrameBuffer is the correct in-range anchor (and
+  // since a static run is verified identical, reusing the run's first in-range capture
+  // equals reusing the global anchor). Telemetry: count reuses separately; do NOT bump
+  // capturePerf.frames (that would dilute the per-frame timing averages).
+  // Use the SAME floor+epsilon idiom as quantizeTimeToFrame so the dedup lookup agrees
+  // with the frame the seek actually lands on, even if `time` ever isn't exactly i/fps.
+  const absFrameIndex = Math.floor(time * fpsToNumber(options.fps) + 1e-9);
+  if (session.staticFrames?.has(absFrameIndex) && session.lastFrameBuffer) {
+    session.staticDedupCount = (session.staticDedupCount ?? 0) + 1;
+    return {
+      buffer: session.lastFrameBuffer,
+      quantizedTime: quantizeTimeToFrame(time, fpsToNumber(options.fps)),
+      captureTimeMs: Date.now() - startTime,
+    };
+  }
+
   try {
     const { quantizedTime, seekMs, beforeCaptureMs } = await prepareFrameForCapture(
       session,
@@ -1328,6 +1707,9 @@ async function captureFrameCore(
     session.capturePerf.screenshotMs += screenshotMs;
     session.capturePerf.totalMs += captureTimeMs;
 
+    // Retain this freshly-captured buffer so the following static frames can reuse it.
+    if (session.staticFrames) session.lastFrameBuffer = screenshotBuffer;
+
     return { buffer: screenshotBuffer, quantizedTime, captureTimeMs };
   } catch (captureError) {
     if (session.isInitialized) {
@@ -1428,18 +1810,40 @@ export async function discardWarmupCapture(
   const perfBefore = { ...session.capturePerf };
   const hasDamageBefore = session.beginFrameHasDamageCount;
   const noDamageBefore = session.beginFrameNoDamageCount;
+  const dedupCountBefore = session.staticDedupCount;
+  const lastFrameBufferBefore = session.lastFrameBuffer;
   try {
     await innerCapture(session, frameIndex, time);
   } finally {
     // Always restore — even on error. A failed warmup capture should not
-    // leak inflated perf counters into the real capture summary.
+    // leak inflated perf counters, a phantom dedup reuse, or a warmup-era
+    // lastFrameBuffer anchor into the real capture summary/state.
     session.capturePerf = perfBefore;
     session.beginFrameHasDamageCount = hasDamageBefore;
     session.beginFrameNoDamageCount = noDamageBefore;
+    session.staticDedupCount = dedupCountBefore;
+    session.lastFrameBuffer = lastFrameBufferBefore;
   }
 }
 
 export async function closeCaptureSession(session: CaptureSession): Promise<void> {
+  // Realized static-dedup telemetry: how much the cache actually helped this
+  // render (vs the prediction logged at arm time). Both capture paths
+  // (sequential orchestrator + parallel workers) close their session here, so
+  // this is the one uniform emit point. Zero the count afterward so the
+  // idempotent re-close (HDR cleanup) doesn't double-log.
+  const reused = session.staticDedupCount ?? 0;
+  if (session.staticFrames && reused > 0) {
+    const captured = session.capturePerf.frames; // excludes reuses by design
+    const total = captured + reused;
+    const pct = total > 0 ? Math.round((reused / total) * 100) : 0;
+    const avgTotalMs = captured > 0 ? Math.round(session.capturePerf.totalMs / captured) : 0;
+    console.log(
+      `[static-dedup] reused ${reused}/${total} frame(s) (${pct}%), ` +
+        `est. ~${reused * avgTotalMs}ms saved (avg ${avgTotalMs}ms/frame)`,
+    );
+    session.staticDedupCount = 0;
+  }
   // INVARIANT: closeCaptureSession is idempotent. The renderOrchestrator HDR
   // cleanup path tracks a `domSessionClosed` flag and may still re-call this
   // in the outer finally if the inner cleanup raised before the flag flipped.
@@ -1496,6 +1900,12 @@ export function prepareCaptureSessionForReuse(
   };
   session.beginFrameHasDamageCount = 0;
   session.beginFrameNoDamageCount = 0;
+  // Reset per-render dedup state so a buffer captured by the prior render/probe can't
+  // bleed into this render's first static frame. staticFrames (the armed set) is left
+  // intact: it's keyed in absolute frames and stays valid for a same-composition reuse;
+  // lastFrameBuffer must be re-seeded by this render's first fresh capture.
+  session.lastFrameBuffer = undefined;
+  session.staticDedupCount = 0;
 }
 
 export async function getCompositionDuration(session: CaptureSession): Promise<number> {
@@ -1514,5 +1924,11 @@ export function getCapturePerfSummary(session: CaptureSession): CapturePerfSumma
     avgSeekMs: Math.round(session.capturePerf.seekMs / frames),
     avgBeforeCaptureMs: Math.round(session.capturePerf.beforeCaptureMs / frames),
     avgScreenshotMs: Math.round(session.capturePerf.screenshotMs / frames),
+    staticDedupReused: session.staticDedupCount ?? 0,
+    staticDedupEnabled: session.staticDedupEnabled ?? false,
+    // armed ⟺ a non-empty static set survived verification; predicted === its size.
+    staticDedupArmed: (session.staticFrames?.size ?? 0) > 0,
+    staticDedupPredicted: session.staticFrames?.size ?? 0,
+    staticDedupSkipReason: session.staticDedupSkipReason,
   };
 }

package/src/services/videoFrameExtractor.test.ts

@@ -328,6 +328,71 @@ describe("FrameLookupTable", () => {
     expect(table.getActiveFramePayloads(0.5).has("hero")).toBe(true);
     expect(table.getActiveFramePayloads(1.5).has("hero")).toBe(false);
   });
+
+  it("holds the last frame at the inclusive clip end (t === end)", () => {
+    // clip [1,3] with exactly 2s of source frames (60 @ 30fps). The frame
+    // landing on t === end used to deactivate one frame early and render blank,
+    // while the runtime keeps the element visible on its last frame.
+    const table = createFrameLookupTable(
+      [
+        {
+          id: "hero",
+          src: "clip.webm",
+          start: 1,
+          end: 3,
+          mediaStart: 0,
+          loop: false,
+          hasAudio: false,
+        },
+      ],
+      [fakeExtracted(60, 30)],
+    );
+    const atEnd = table.getActiveFramePayloads(3.0).get("hero");
+    expect(atEnd?.frameIndex).toBe(59);
+    // mid-clip is unaffected
+    expect(table.getActiveFramePayloads(2.5).get("hero")?.frameIndex).toBe(45);
+  });
+
+  it("holds the last frame at the clip end even when the source is shorter than the window", () => {
+    // clip [0,5] with only 1s of source (30 @ 30fps). The mid-clip tail stays
+    // blank (source exhausted), but t === end still holds the last frame to
+    // match the runtime's inclusive visibility.
+    const table = createFrameLookupTable(
+      [
+        {
+          id: "hero",
+          src: "clip.webm",
+          start: 0,
+          end: 5,
+          mediaStart: 0,
+          loop: false,
+          hasAudio: false,
+        },
+      ],
+      [fakeExtracted(30, 30)],
+    );
+    expect(table.getActiveFramePayloads(1.5).has("hero")).toBe(false);
+    expect(table.getActiveFramePayloads(5.0).get("hero")?.frameIndex).toBe(29);
+  });
+
+  it("keeps both clips active at a shared adjacent boundary, matching the runtime", () => {
+    // clip A ends at 3.0, clip B starts at 3.0. The runtime shows both at the
+    // shared instant; the active set must too.
+    const table = createFrameLookupTable(
+      [
+        { id: "a", src: "a.webm", start: 0, end: 3, mediaStart: 0, loop: false, hasAudio: false },
+        { id: "b", src: "b.webm", start: 3, end: 6, mediaStart: 0, loop: false, hasAudio: false },
+      ],
+      // createFrameLookupTable maps each clip to extracted frames by id.
+      [
+        { ...fakeExtracted(90, 30), videoId: "a" },
+        { ...fakeExtracted(90, 30), videoId: "b" },
+      ],
+    );
+    const payloads = table.getActiveFramePayloads(3.0);
+    expect(payloads.has("a")).toBe(true);
+    expect(payloads.has("b")).toBe(true);
+  });
 });
 
 describe("parseImageElements", () => {

package/src/services/videoFrameExtractor.ts

@@ -1003,7 +1003,7 @@ export class FrameLookupTable {
   getFrame(videoId: string, globalTime: number): string | null {
     const video = this.videos.get(videoId);
     if (!video) return null;
-    if (globalTime < video.start || globalTime >= video.end) return null;
+    if (globalTime < video.start || globalTime > video.end) return null;
     return getFrameAtTime(video.extracted, globalTime, video.start, video.loop, video.mediaStart);
   }
 
@@ -1014,11 +1014,16 @@ export class FrameLookupTable {
   }
 
   private refreshActiveSet(globalTime: number): void {
+    // The active window is [start, end] INCLUSIVE of the end, mirroring the
+    // runtime's element-visibility contract (core/runtime init.ts keeps an
+    // element visible through `currentTime <= end`). An exclusive end-bound
+    // here deactivated the video one frame early, so the frame landing exactly
+    // on a clip's end rendered blank while the runtime still showed it.
     if (this.lastTime == null || globalTime < this.lastTime) {
       this.activeVideoIds.clear();
       this.startCursor = 0;
       for (const entry of this.orderedVideos) {
-        if (entry.start <= globalTime && globalTime < entry.end) {
+        if (entry.start <= globalTime && globalTime <= entry.end) {
           this.activeVideoIds.add(entry.videoId);
         }
         if (entry.start <= globalTime) {
@@ -1037,7 +1042,7 @@ export class FrameLookupTable {
       if (candidate.start > globalTime) {
         break;
       }
-      if (globalTime < candidate.end) {
+      if (globalTime <= candidate.end) {
         this.activeVideoIds.add(candidate.videoId);
       }
       this.startCursor += 1;
@@ -1045,7 +1050,7 @@ export class FrameLookupTable {
 
     for (const videoId of Array.from(this.activeVideoIds)) {
       const video = this.videos.get(videoId);
-      if (!video || globalTime < video.start || globalTime >= video.end) {
+      if (!video || globalTime < video.start || globalTime > video.end) {
         this.activeVideoIds.delete(videoId);
       }
     }
@@ -1073,7 +1078,18 @@ export class FrameLookupTable {
         }
         continue;
       }
-      if (frameIndex < 0 || frameIndex >= video.extracted.totalFrames) continue;
+      if (frameIndex < 0 || frameIndex >= video.extracted.totalFrames) {
+        // At the inclusive clip end (globalTime === end), hold the last
+        // extracted frame so the render matches the runtime, which keeps the
+        // element visible on its final frame at `t === end`. Mid-clip source
+        // exhaustion (globalTime < end) stays blank — unchanged.
+        if (globalTime >= video.end && video.extracted.totalFrames > 0) {
+          const lastIndex = video.extracted.totalFrames - 1;
+          const lastPath = video.extracted.framePaths.get(lastIndex);
+          if (lastPath) frames.set(videoId, { framePath: lastPath, frameIndex: lastIndex });
+        }
+        continue;
+      }
       const framePath = video.extracted.framePaths.get(frameIndex);
       if (!framePath) continue;
       frames.set(videoId, { framePath, frameIndex });

package/src/types.ts

@@ -160,6 +160,26 @@ export interface CapturePerfSummary {
   avgSeekMs: number;
   avgBeforeCaptureMs: number;
   avgScreenshotMs: number;
+  /**
+   * Frames served from the static-dedup cache instead of a real seek+screenshot
+   * (opt-out HF_STATIC_DEDUP=false). 0 when dedup was off or never armed. NOT counted
+   * in `frames` (reuses are excluded so they don't dilute the per-frame
+   * averages) — the captured total this session is `frames + staticDedupReused`.
+   */
+  staticDedupReused: number;
+  /** `HF_STATIC_DEDUP=true` was set for this render (adoption signal). */
+  staticDedupEnabled: boolean;
+  /** Dedup passed every gate + verification and was active. */
+  staticDedupArmed: boolean;
+  /** Predicted reusable frame count when armed; 0 otherwise. */
+  staticDedupPredicted: number;
+  /**
+   * Low-cardinality reason dedup did not arm: `capture_mode` | `video_injection`
+   * | `page_composite` | `ineligible` | `verification_failed` | `verification_budget`.
+   * Undefined when armed or when dedup was disabled. (Render-level aggregation may
+   * `|`-join distinct reasons when parallel workers diverge.)
+   */
+  staticDedupSkipReason?: string;
 }
 
 // ── Global Augmentation ────────────────────────────────────────────────────────