@crouton-kit/capture 1.4.2 → 1.4.11

package/src/cdp/motion/jank.ts

@@ -13,15 +13,6 @@ export interface JankFrame {
   readonly tMs: number;
 }
 
-export interface DroppedFrameFact {
-  readonly afterFrame: number;
-  readonly beforeFrame: number;
-  readonly startMs: number;
-  readonly endMs: number;
-  readonly intervalMs: number;
-  readonly estimatedDroppedFrames: number;
-}
-
 export type LongTaskTimingDomain = 'recorder-performance' | 'trace-relative-first-event' | 'unavailable';
 
 export interface LongTaskFact {
@@ -32,8 +23,6 @@ export interface LongTaskFact {
   readonly durationMs: number;
   /** Null when no synchronized recorder-relative observer baseline was retained. */
   readonly endMs: number | null;
-  /** Null when task/frame timing is incomparable or unavailable. */
-  readonly overlapsDroppedFrames: readonly number[] | null;
 }
 
 export interface LayoutShiftRectFact {
@@ -57,7 +46,7 @@ export interface LayoutShiftFact {
   readonly rects: readonly LayoutShiftRectFact[];
 }
 
-export type JankCount = 'dropped-frames' | 'long-task-records' | 'layout-shift-records';
+export type JankCount = 'long-task-records' | 'layout-shift-records';
 
 export interface ArtifactLossFact {
   readonly kind: string;
@@ -69,15 +58,13 @@ export interface ArtifactLossFact {
 
 export interface MotionJankAnalysis {
   readonly frameCount: number;
-  readonly cadenceMs: number | null;
   readonly missingFrameSampleCount: number;
-  readonly droppedFrames: readonly DroppedFrameFact[];
-  readonly droppedFrameCount: number;
-  readonly droppedFramesIncomplete: boolean;
   readonly longTasks: readonly LongTaskFact[];
   readonly longTasksIncomplete: boolean;
   readonly layoutShifts: readonly LayoutShiftFact[];
   readonly layoutShiftsIncomplete: boolean;
+  /** Buffered PerformanceObserver entries that predate the recorder arm baseline and are excluded from result records. */
+  readonly preRecordingObserverEntriesExcluded: number;
   readonly artifactLoss: readonly ArtifactLossFact[];
   readonly frameTimestampUncertainty: '±frame' | 'unavailable';
   readonly timingNote: string;
@@ -202,13 +189,6 @@ function inferredRectFacts(shiftAtMs: number, frames: readonly { tMs: number; el
   return { rects, beforeFrameMs: before.tMs, afterFrameMs: after.tMs };
 }
 
-/** The lower quartile keeps a frequent long interval from redefining the nominal frame cadence. */
-function stableLowCadence(intervals: readonly number[]): number | null {
-  if (intervals.length < 2) return null;
-  const sorted = [...intervals].sort((a, b) => a - b);
-  return sorted[Math.floor((sorted.length - 1) * 0.25)] ?? null;
-}
-
 function missingFrameSamples(frames: readonly JankFrame[]): number {
   let missing = 0;
   for (let i = 1; i < frames.length; i++) {
@@ -257,12 +237,12 @@ function artifactLoss(events: readonly unknown[]): ArtifactLossFact[] {
       case 'error': {
         const lower = (message ?? '').toLowerCase();
         const affectedCounts: JankCount[] = lower.includes('rect sample')
-          ? ['dropped-frames']
+          ? []
           : lower.includes('observer')
             ? ['long-task-records', 'layout-shift-records']
             : lower.includes('trace')
               ? ['long-task-records']
-              : ['dropped-frames', 'long-task-records', 'layout-shift-records'];
+              : ['long-task-records', 'layout-shift-records'];
         facts.push({ kind: event.kind, count, reason, message, affectedCounts });
         break;
       }
@@ -280,42 +260,29 @@ export function analyzeMotionJank(input: { rects: readonly unknown[]; events: re
     .filter((item): item is { item: UnknownRecord; tMs: number } => item.tMs !== null)
     .sort((a, b) => a.tMs - b.tMs);
   const frames: JankFrame[] = frameRecords.map(({ item, tMs }, index) => ({ frame: finite(item.frame) ?? index, tMs }));
-  const intervals = frames.slice(1).map((frame, index) => frame.tMs - frames[index].tMs).filter((interval) => interval > 0);
-  const cadenceMs = stableLowCadence(intervals);
   const missingFrameSampleCount = missingFrameSamples(frames);
-  const droppedFrames: DroppedFrameFact[] = [];
-  if (cadenceMs !== null && cadenceMs > 0) {
-    for (let i = 1; i < frames.length; i++) {
-      const intervalMs = frames[i].tMs - frames[i - 1].tMs;
-      const estimatedDroppedFrames = Math.max(0, Math.round(intervalMs / cadenceMs) - 1);
-      if (estimatedDroppedFrames > 0) droppedFrames.push({ afterFrame: frames[i].frame, beforeFrame: frames[i - 1].frame, startMs: frames[i - 1].tMs, endMs: frames[i].tMs, intervalMs, estimatedDroppedFrames });
-    }
-  }
 
   const traceEvents = flattenTraceEvents(input.events);
   const observedTraceBaselineUs = traceEvents.map((event) => finite(event.ts)).filter((ts): ts is number => ts !== undefined).sort((a, b) => a - b)[0];
   const observerEntries = observerRecords(input.events);
-  // The two distinct causes of unavailable observer timing, tracked separately so the
-  // user-visible note attributes each factually instead of blaming navigation for both.
-  let observerNavGapUnavailable = false; // null recorder-relative time: no synchronized baseline (post-navigation-gap).
-  let observerPreArmUnavailable = false; // negative recorder-relative time: buffered entry whose document timestamp predates the arm baseline.
+  let observerNavGapUnavailable = false;
+  let preRecordingObserverEntriesExcluded = 0;
   const longTasks: LongTaskFact[] = [];
   for (const { item, timingAvailable } of observerEntries) {
     if (item.entryType !== 'longtask') continue;
     const durationMs = finite(item.duration);
     if (durationMs === undefined) continue;
-    // A negative recorder-relative start comes from a buffered entry whose document
-    // time origin predates the recorder arm baseline; it has no valid recorder-relative
-    // baseline, so route it (like a null or post-navigation-gap start) to 'unavailable'
-    // rather than emitting a negative time or silently dropping it.
     const startMs = timingAvailable ? observerToPerformanceMs(item, input.markers) : null;
-    if (startMs === null || startMs < 0) {
-      if (startMs === null) observerNavGapUnavailable = true;
-      else observerPreArmUnavailable = true;
-      longTasks.push({ source: 'observer', timingDomain: 'unavailable', startMs: null, durationMs, endMs: null, overlapsDroppedFrames: null });
+    if (startMs === null) {
+      observerNavGapUnavailable = true;
+      longTasks.push({ source: 'observer', timingDomain: 'unavailable', startMs: null, durationMs, endMs: null });
       continue;
     }
-    longTasks.push(longTask('observer', 'recorder-performance', startMs, durationMs, droppedFrames));
+    if (startMs < 0) {
+      preRecordingObserverEntriesExcluded++;
+      continue;
+    }
+    longTasks.push(longTask('observer', 'recorder-performance', startMs, durationMs));
   }
   for (const trace of traceEvents) {
     const name = typeof trace.name === 'string' ? trace.name : '';
@@ -323,7 +290,7 @@ export function analyzeMotionJank(input: { rects: readonly unknown[]; events: re
     const timestampUs = finite(trace.ts);
     if (!/(longtask|run(task|microtasks)|task)/i.test(name) || durationMs === undefined || durationMs < 50_000 || timestampUs === undefined) continue;
     const timing = traceTime(timestampUs, input.markers, observedTraceBaselineUs);
-    if (timing !== null) longTasks.push(longTask('trace', timing.domain, timing.tMs, durationMs / 1000, droppedFrames));
+    if (timing !== null) longTasks.push(longTask('trace', timing.domain, timing.tMs, durationMs / 1000));
   }
 
   const frameElementRecords = frameRecords.map(({ item, tMs }) => ({ tMs, elements: (Array.isArray(item.elements) ? item.elements : []).map(record).filter((v): v is UnknownRecord => v !== null) }));
@@ -332,14 +299,9 @@ export function analyzeMotionJank(input: { rects: readonly unknown[]; events: re
     if (item.entryType !== 'layout-shift') continue;
     const value = finite(item.value);
     if (value === undefined) continue;
-    // A negative recorder-relative time comes from a buffered entry whose document
-    // time origin predates the recorder arm baseline; it has no valid recorder-relative
-    // baseline, so route it (like a null or post-navigation-gap time) to 'unavailable'
-    // rather than emitting a negative time or silently dropping it.
     const tMs = timingAvailable ? observerToPerformanceMs(item, input.markers) : null;
-    if (tMs === null || tMs < 0) {
-      if (tMs === null) observerNavGapUnavailable = true;
-      else observerPreArmUnavailable = true;
+    if (tMs === null) {
+      observerNavGapUnavailable = true;
       layoutShifts.push({
         tMs: null,
         value,
@@ -349,6 +311,10 @@ export function analyzeMotionJank(input: { rects: readonly unknown[]; events: re
       });
       continue;
     }
+    if (tMs < 0) {
+      preRecordingObserverEntriesExcluded++;
+      continue;
+    }
     const explicit = rectFactsFromObserverSources(item);
     const inferred = explicit.length ? undefined : inferredRectFacts(tMs, frameElementRecords);
     layoutShifts.push({
@@ -367,22 +333,15 @@ export function analyzeMotionJank(input: { rects: readonly unknown[]; events: re
     losses.push({
       kind: 'orphaned-finalized',
       message: 'recorder was finalized best-effort from artifacts already flushed to disk',
-      affectedCounts: ['dropped-frames', 'long-task-records', 'layout-shift-records'],
+      affectedCounts: ['long-task-records', 'layout-shift-records'],
     });
   }
   const incomplete = new Set<JankCount>(losses.flatMap((loss) => loss.affectedCounts));
-  if (missingFrameSampleCount > 0 || cadenceMs === null) incomplete.add('dropped-frames');
   const traceAligned = longTasks.some((task) => task.source === 'trace' && task.timingDomain === 'recorder-performance');
   const traceRelative = longTasks.some((task) => task.source === 'trace' && task.timingDomain === 'trace-relative-first-event');
   const frameTimestampUncertainty: '±frame' | 'unavailable' = frames.length ? '±frame' : 'unavailable';
-  // Attribute each unavailable-timing cause factually. A navigation gap and a pre-arm
-  // buffered entry both route to 'unavailable', but only the former involves a navigation;
-  // asserting navigation for a pre-arm entry would be false provenance.
-  const observerUnavailableCauses: string[] = [];
-  if (observerNavGapUnavailable) observerUnavailableCauses.push('some occurred after a navigation gap with no synchronized recorder-relative baseline');
-  if (observerPreArmUnavailable) observerUnavailableCauses.push('some were buffered from before the recorder arm baseline, with a document timestamp that predates it');
-  const observerTiming = observerUnavailableCauses.length
-    ? `Observer entries with unavailable timing (${observerUnavailableCauses.join('; ')}) have no recorder-relative baseline; their timing, dropped-frame overlap, and frame-diff attribution are unavailable.`
+  const observerTiming = observerNavGapUnavailable
+    ? 'Observer entries after a navigation gap with no synchronized recorder-relative baseline have unavailable timing and frame-diff attribution.'
     : 'Observer and screencast timestamps are recorder-relative performance.now() milliseconds.';
   const timingNote = traceRelative
     ? `${observerTiming} Frame-derived intervals have ±frame uncertainty. Trace timestamps are relative to the first trace event because no explicit trace/performance baseline marker was retained.`
@@ -394,33 +353,20 @@ export function analyzeMotionJank(input: { rects: readonly unknown[]; events: re
 
   return {
     frameCount: frames.length,
-    cadenceMs,
     missingFrameSampleCount,
-    droppedFrames,
-    droppedFrameCount: droppedFrames.reduce((count, item) => count + item.estimatedDroppedFrames, 0),
-    droppedFramesIncomplete: incomplete.has('dropped-frames'),
     longTasks,
     longTasksIncomplete: incomplete.has('long-task-records'),
     layoutShifts,
     layoutShiftsIncomplete: incomplete.has('layout-shift-records'),
+    preRecordingObserverEntriesExcluded,
     artifactLoss: losses,
     frameTimestampUncertainty,
     timingNote,
   };
 }
 
-function longTask(source: 'observer' | 'trace', timingDomain: LongTaskTimingDomain, startMs: number, durationMs: number, droppedFrames: readonly DroppedFrameFact[]): LongTaskFact {
-  const endMs = startMs + durationMs;
-  return {
-    source,
-    timingDomain,
-    startMs,
-    durationMs,
-    endMs,
-    overlapsDroppedFrames: timingDomain === 'recorder-performance'
-      ? droppedFrames.filter((drop) => startMs < drop.endMs && endMs > drop.startMs).map((drop) => drop.afterFrame)
-      : null,
-  };
+function longTask(source: 'observer' | 'trace', timingDomain: LongTaskTimingDomain, startMs: number, durationMs: number): LongTaskFact {
+  return { source, timingDomain, startMs, durationMs, endMs: startMs + durationMs };
 }
 
 export function readMotionJank(ref: RecRef): { analysis: MotionJankAnalysis; meta: Record<string, unknown> } {
@@ -430,7 +376,7 @@ export function readMotionJank(ref: RecRef): { analysis: MotionJankAnalysis; met
   // completed recording, not one awaiting `--stop` (which only applies to an
   // active composed lifecycle recording) — its retained event/trace records
   // remain readable, so long-task and layout-shift facts stay available;
-  // only frame-derived counts fall back to "incomplete" via cadenceMs===null.
+  // while frame-derived timing remains unavailable without rect timestamps.
   // Mirrors the same exception already made in response.ts's loadResponseTimeline.
   const readablePartial = state === 'partial' && meta.reason === 'no_frames';
   if (state !== 'finalized' && state !== 'orphaned-finalized' && !readablePartial) {

package/src/cdp/motion/mask.ts

@@ -66,8 +66,8 @@ interface Component {
 
 /** Per-component facts computed in single shared passes over the label map. */
 interface ComponentStats {
-  /** Best element attribution by summed pixel overlap across rect records. */
-  attribution: { element: MotionElement; overlap: number } | null;
+  /** Best element attribution by changed-pixel coverage relative to its recorded area. */
+  attribution: { element: MotionElement; overlap: number; area: number } | null;
   /** Pair-ordered centroids of this component's changed pixels, one per active sample. */
   activeCentroids: Array<{ pair: number; cx: number; cy: number }>;
 }
@@ -288,7 +288,7 @@ function computeComponentStats(
     }
   }
 
-  const candidates: Array<Map<string, { element: MotionElement; overlap: number }>> = components.map(() => new Map());
+  const candidates: Array<Map<string, { element: MotionElement; overlap: number; area: number }>> = components.map(() => new Map());
   for (const record of recordsByFile.values()) {
     for (const element of record.elements ?? []) {
       if (![element.x, element.y, element.width, element.height].every((value) => typeof value === 'number' && Number.isFinite(value))) continue;
@@ -299,22 +299,31 @@ function computeComponentStats(
       const x1 = Math.min(width, Math.ceil(transformed.x + transformed.width));
       const y0 = Math.max(0, Math.floor(transformed.y));
       const y1 = Math.min(height, Math.ceil(transformed.y + transformed.height));
+      const area = (x1 - x0) * (y1 - y0);
+      if (area <= 0) continue;
+      const overlaps = new Map<number, number>();
       for (let py = y0; py < y1; py++) {
         const rowBase = py * width;
         for (let px = x0; px < x1; px++) {
           const label = labels[rowBase + px];
-          if (label < 0) continue;
-          const map = candidates[label];
-          const existing = map.get(key);
-          if (existing) existing.overlap++;
-          else map.set(key, { element, overlap: 1 });
+          if (label >= 0) overlaps.set(label, (overlaps.get(label) ?? 0) + 1);
+        }
+      }
+      for (const [label, overlap] of overlaps) {
+        const map = candidates[label];
+        const existing = map.get(key);
+        if (existing) {
+          existing.overlap += overlap;
+          existing.area += area;
+        } else {
+          map.set(key, { element, overlap, area });
         }
       }
     }
   }
 
   return components.map((_, index) => ({
-    attribution: [...candidates[index].values()].sort((a, b) => b.overlap - a.overlap)[0] ?? null,
+    attribution: [...candidates[index].values()].sort((a, b) => b.overlap / b.area - a.overlap / a.area || b.overlap - a.overlap)[0] ?? null,
     activeCentroids: activeCentroids[index],
   }));
 }