perf(studio-server): coordinate cancelable thumbnail generation (#2720)

* perf(studio): schedule adaptive timeline thumbnails

* perf(studio): bound thumbnail decoding resources

* perf(studio): virtualize timeline thumbnail media

* perf(studio): prioritize timeline thumbnail work

* perf(studio-server): coordinate cancelable thumbnail generation

---------

Co-authored-by: Codex <codex@local>

packages/studio-server/src/helpers/thumbnailOutput.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { thumbnailDeviceScaleFactor } from "./thumbnailOutput";
+
+describe("thumbnailDeviceScaleFactor", () => {
+  it("preserves source-density captures and bounds landscape and portrait previews", () => {
+    expect(
+      thumbnailDeviceScaleFactor({
+        width: 1920,
+        height: 1080,
+        outputWidth: 1920,
+        outputHeight: 1080,
+      }),
+    ).toBe(1);
+    expect(
+      thumbnailDeviceScaleFactor({
+        width: 1920,
+        height: 1080,
+        outputWidth: 240,
+        outputHeight: 135,
+      }),
+    ).toBe(0.125);
+    expect(
+      thumbnailDeviceScaleFactor({
+        width: 1080,
+        height: 1920,
+        outputWidth: 76,
+        outputHeight: 135,
+      }),
+    ).toBeCloseTo(76 / 1080);
+  });
+
+  it("rejects invalid dimensions instead of silently changing layout", () => {
+    expect(() =>
+      thumbnailDeviceScaleFactor({ width: 0, height: 1080, outputWidth: 240, outputHeight: 135 }),
+    ).toThrow(RangeError);
+  });
+});

packages/studio-server/src/helpers/thumbnailOutput.ts

@@ -0,0 +1,20 @@
+export interface ThumbnailOutputDimensions {
+  width: number;
+  height: number;
+  outputWidth: number;
+  outputHeight: number;
+}
+
+/** Sole adapter rule for capturing authored layout at bounded physical dimensions. */
+export function thumbnailDeviceScaleFactor({
+  width,
+  height,
+  outputWidth,
+  outputHeight,
+}: ThumbnailOutputDimensions): number {
+  const dimensions = [width, height, outputWidth, outputHeight];
+  if (dimensions.some((value) => !Number.isFinite(value) || value <= 0)) {
+    throw new RangeError("Thumbnail dimensions must be positive finite numbers");
+  }
+  return Math.min(1, outputWidth / width, outputHeight / height);
+}