docs(studio): keep the filmstrip files at or under main's comment share

The comment ratchet allows no file a higher share of comment lines than on
main; the added explanations move to the PR description.

Author: miguel-heygen

packages/studio/src/hooks/useMusicBeatAnalysis.ts

@@ -80,7 +80,6 @@ async function loadBeatAnalysis(
 ): Promise<{ analysis: MusicAnalysis; times: number[]; strengths: number[] } | null> {
   let promise = analysisCache.get(musicSrc);
   if (!promise) {
-    // Each long stage of the analysis waits for the timeline to rest, so it never lands mid-zoom.
     promise = analyzeMusicFromUrl(musicSrc, { pause: whenTimelineIdle });
     cacheAnalysis(musicSrc, promise);
   }

packages/studio/src/player/components/AudioWaveform.tsx

@@ -158,16 +158,13 @@ async function decodeWaveformPeaks(url: string, signal: AbortSignal): Promise<nu
 }
 
 /** Bounded waveform subscriber; cache, cancellation and dedupe live in one scheduler. */
-// One screen each side and half a screen above and below; scrollMargin applies it inside the
-// timeline's own scroller too (TypeScript's DOM types lack it).
 const NEAR_SCREEN: IntersectionObserverInit & { scrollMargin: string } = {
   rootMargin: "50% 100%",
   scrollMargin: "50% 100%",
 };
 const nearScreenListeners = new Map<Element, (near: boolean) => void>();
 let nearScreen: IntersectionObserver | null = null;
 
-/** Whether `element` is on or near the screen, kept current by one observer for all waveforms. */
 function useNearScreen(element: Element | null): boolean {
   const [near, setNear] = useState(() => typeof IntersectionObserver === "undefined");
   useEffect(() => {
@@ -247,7 +244,6 @@ export const AudioWaveform = memo(function AudioWaveform({
       span,
     );
   }, [fades, from, muted, peaks, to, trimEndFraction, trimStartFraction]);
-  // A waveform off screen draws when it comes near, not at every zoom that resizes it.
   const near = useNearScreen(root);
   useEffect(() => {
     if (near) draw();

packages/studio/src/player/components/VideoThumbnail.tsx

@@ -83,10 +83,6 @@ function selectThumbnailSnapshot(
 
 type VideoThumbnailRequest = ReturnType<typeof createVideoThumbnailRequest>;
 
-/**
- * The strip to show: the requested width once ready, else the strip already on screen, kept leased
- * while a zoom's new width decodes, else the poster.
- */
 function useVideoThumbnailSnapshot(
   poster: VideoThumbnailRequest | null,
   rich: VideoThumbnailRequest | null,

packages/studio/src/player/components/thumbnailUtils.ts

@@ -11,7 +11,6 @@ export interface ThumbnailStripLayout {
 /** Quantize request identities so a pixel-by-pixel resize does not thrash the cache. */
 export function quantizeThumbnailFrameCount(frameCount: number): number {
   const safeCount = Math.max(1, Number.isFinite(frameCount) ? Math.ceil(frameCount) : 1);
-  // Capped at a power of two too, so the top step still holds every frame of the one below it.
   const cap = 2 ** Math.floor(Math.log2(MAX_VISIBLE_THUMBNAIL_FRAMES));
   return Math.min(cap, 2 ** Math.ceil(Math.log2(safeCount)));
 }

packages/studio/src/player/lib/thumbnailVideoDecoder.ts

@@ -9,12 +9,7 @@ export interface VideoThumbnailDecodeRequest {
   fit?: "contain" | "cover";
 }
 
-/**
- * The times a strip of `frameCount` slices shows: each slice's left edge, so a strip twice as long
- * holds every frame of this one, then the clip's last frame. A poster is the midpoint.
- */
-// Inside the last frame: a time at the very end of a file can decode to nothing.
-const END_FRAME_LEAD_S = 0.001;
+const LAST_FRAME_INSET_S = 0.001;
 
 export function videoThumbnailTimestamps(
   start: number,
@@ -29,10 +24,9 @@ export function videoThumbnailTimestamps(
     { length: count },
     (_, index) => safeStart + (safeDuration * index) / count,
   );
-  return [...edges, safeStart + Math.max(0, safeDuration - END_FRAME_LEAD_S)];
+  return [...edges, safeStart + Math.max(0, safeDuration - LAST_FRAME_INSET_S)];
 }
 
-/** A decoded frame, shared by every strip of its source that would accept it for a time. */
 interface SharedFrame {
   url: string;
   decodedAt: number;
@@ -44,11 +38,9 @@ interface HeldFrame {
   frame: SharedFrame;
 }
 
-/** A strip takes a frame decoded inside its range, at most `lead` before the time it shows. */
 interface FrameWindow {
   sourceStart: number;
   lead: number;
-  /** The clip's last frame, shown as decoded at its own time, never from an earlier keyframe. */
   end: number;
 }
 
@@ -64,7 +56,6 @@ function takeSharedFrame(key: string, time: number, window: FrameWindow): Shared
   return frame;
 }
 
-/** Shares a newly decoded frame, or the same frame another strip decoded meanwhile. */
 function shareFrame(key: string, decodedAt: number, url: string): SharedFrame {
   const frames = sharedFrames.get(key) ?? [];
   const existing = frames.find((shared) => shared.decodedAt === decodedAt);
@@ -102,9 +93,7 @@ async function canvasToBlob(canvas: HTMLCanvasElement | OffscreenCanvas): Promis
 }
 
 interface DecodedResources {
-  /** One frame per slot of the strip; a slot the source could not decode stays empty. */
   urls: (string | undefined)[];
-  /** The shared frames this strip holds, released when the strip is. */
   held: HeldFrame[];
   canvases: Set<HTMLCanvasElement | OffscreenCanvas>;
 }
@@ -115,7 +104,6 @@ interface ThumbnailCanvasSink {
   ): AsyncIterable<{ canvas: HTMLCanvasElement | OffscreenCanvas } | null>;
 }
 
-/** What a strip of a source needs before it can name its frames. */
 interface SourceInfo {
   aspect: number;
   metadataDuration: number | null;
@@ -149,7 +137,6 @@ function targetDimensions(
   };
 }
 
-/** The strip's frame times, clamped to what the file holds, and the frames it accepts for them. */
 function stripTimes(
   request: VideoThumbnailDecodeRequest,
   info: SourceInfo,
@@ -181,7 +168,6 @@ function stripTimes(
   return { window, timestamps };
 }
 
-/** Holds every frame of the strip already decoded; returns the slots still to decode. */
 function takeDecodedFrames(
   { timestamps, window }: ReturnType<typeof stripTimes>,
   keyOf: (time: number) => string,
@@ -240,10 +226,7 @@ function loadedResult(
   };
 }
 
-/**
- * Sparse Mediabunny extraction with one pooled canvas and one cleanup owner. Frames another strip
- * of the source already shows are reused, so a zoom decodes only the frames that are new.
- */
+/** Sparse Mediabunny extraction with one pooled canvas and one cleanup owner. */
 export async function decodeVideoThumbnail(
   request: VideoThumbnailDecodeRequest,
   signal: AbortSignal,