@hyperframes/studio 0.7.72 → 0.7.74

package/src/components/editor/propertyPanelColorWheels.tsx

@@ -0,0 +1,334 @@
+import { useRef, type KeyboardEvent as ReactKeyboardEvent } from "react";
+import {
+  getHfColorGradingCapabilities,
+  type HfColorGradingWheelKey,
+  type NormalizedHfColorGradingWheels,
+} from "@hyperframes/core/color-grading";
+import { RotateCcw } from "../../icons/SystemIcons";
+import { clampNumber } from "../../utils/studioHelpers";
+import { GradingNumberField } from "./propertyPanelGradingNumberField";
+import { useInspectorGestureDraft } from "./useInspectorGestureTransaction";
+
+const WHEELS: ReadonlyArray<{ key: HfColorGradingWheelKey; label: string }> = [
+  { key: "shadows", label: "Shadows" },
+  { key: "midtones", label: "Midtones" },
+  { key: "highlights", label: "Highlights" },
+];
+type NormalizedTonalWheel = NormalizedHfColorGradingWheels[HfColorGradingWheelKey];
+
+const WHEEL_CONTROLS = getHfColorGradingCapabilities().wheels.controls;
+const PERCENT_SCALE = 100;
+const HUE_MAX = WHEEL_CONTROLS.hue.maxExclusive - 0.01;
+const RESET_WHEEL: NormalizedTonalWheel = {
+  hue: WHEEL_CONTROLS.hue.identity,
+  amount: WHEEL_CONTROLS.amount.identity,
+  level: WHEEL_CONTROLS.level.identity,
+};
+
+function wrapHue(value: number): number {
+  const { min, maxExclusive } = WHEEL_CONTROLS.hue;
+  const span = maxExclusive - min;
+  return ((((value - min) % span) + span) % span) + min;
+}
+
+function formatNumberInput(value: number, decimals: number): string {
+  return String(Number(value.toFixed(decimals)));
+}
+
+const formatIntegerInput = (value: number) => formatNumberInput(value, 0);
+
+function wheelFromPointer(
+  wheel: NormalizedTonalWheel,
+  clientX: number,
+  clientY: number,
+  rect: DOMRect,
+): NormalizedTonalWheel {
+  const radius = Math.max(1, Math.min(rect.width, rect.height) / 2);
+  const x = (clientX - (rect.left + rect.width / 2)) / radius;
+  const y = (rect.top + rect.height / 2 - clientY) / radius;
+  return {
+    ...wheel,
+    hue: wrapHue((Math.atan2(y, x) * 180) / Math.PI),
+    amount: clampNumber(Math.hypot(x, y), WHEEL_CONTROLS.amount.min, WHEEL_CONTROLS.amount.max),
+  };
+}
+
+function updateWheel(
+  value: NormalizedHfColorGradingWheels,
+  key: HfColorGradingWheelKey,
+  wheel: NormalizedTonalWheel,
+): NormalizedHfColorGradingWheels {
+  return { ...value, [key]: wheel };
+}
+
+function wheelFromKey(
+  wheel: NormalizedTonalWheel,
+  key: string,
+  large: boolean,
+): NormalizedTonalWheel | null {
+  const hueStep = large ? 10 : 1;
+  const amountStep = large ? 0.1 : 0.01;
+  switch (key) {
+    case "ArrowLeft":
+      return { ...wheel, hue: wrapHue(wheel.hue - hueStep) };
+    case "ArrowRight":
+      return { ...wheel, hue: wrapHue(wheel.hue + hueStep) };
+    case "ArrowDown":
+      return {
+        ...wheel,
+        amount: clampNumber(
+          wheel.amount - amountStep,
+          WHEEL_CONTROLS.amount.min,
+          WHEEL_CONTROLS.amount.max,
+        ),
+      };
+    case "ArrowUp":
+      return {
+        ...wheel,
+        amount: clampNumber(
+          wheel.amount + amountStep,
+          WHEEL_CONTROLS.amount.min,
+          WHEEL_CONTROLS.amount.max,
+        ),
+      };
+    case "Home":
+      return { ...wheel, amount: WHEEL_CONTROLS.amount.min };
+    case "End":
+      return { ...wheel, amount: WHEEL_CONTROLS.amount.max };
+    default:
+      return null;
+  }
+}
+
+function TonalWheel({
+  label,
+  wheel,
+  disabled,
+  onBegin,
+  onPreview,
+  onSettle,
+  onCancel,
+  onReset,
+}: {
+  label: string;
+  wheel: NormalizedTonalWheel;
+  disabled?: boolean;
+  onBegin: () => void;
+  onPreview: (wheel: NormalizedTonalWheel) => void;
+  onSettle: () => void;
+  onCancel: () => void;
+  onReset: () => void;
+}) {
+  const pointerIdRef = useRef<number | null>(null);
+  const hueRadians = (wheel.hue * Math.PI) / 180;
+  const thumbLeft = 50 + Math.cos(hueRadians) * wheel.amount * 46;
+  const thumbTop = 50 - Math.sin(hueRadians) * wheel.amount * 46;
+
+  const previewPointer = (target: HTMLDivElement, clientX: number, clientY: number) => {
+    onPreview(wheelFromPointer(wheel, clientX, clientY, target.getBoundingClientRect()));
+  };
+  const handleKeyDown = (event: ReactKeyboardEvent<HTMLDivElement>) => {
+    if (disabled) return;
+    if (event.key === "Escape") {
+      event.preventDefault();
+      onCancel();
+      return;
+    }
+    const next = wheelFromKey(wheel, event.key, event.shiftKey);
+    if (!next) return;
+    event.preventDefault();
+    onBegin();
+    onPreview(next);
+  };
+
+  return (
+    <div data-color-wheel={label.toLowerCase()} className="min-w-[88px] flex-1 space-y-1.5">
+      <div className="flex items-center justify-between gap-1">
+        <span className="truncate text-[10px] font-medium text-panel-text-2">{label}</span>
+        <button
+          type="button"
+          aria-label={`Reset ${label}`}
+          title={`Reset ${label}`}
+          disabled={disabled}
+          onClick={onReset}
+          className="text-panel-text-4 hover:text-panel-text-1 disabled:opacity-40"
+        >
+          <RotateCcw size={10} />
+        </button>
+      </div>
+      <div
+        role="slider"
+        tabIndex={disabled ? -1 : 0}
+        aria-label={`${label} color`}
+        aria-valuemin={WHEEL_CONTROLS.amount.min * PERCENT_SCALE}
+        aria-valuemax={WHEEL_CONTROLS.amount.max * PERCENT_SCALE}
+        aria-valuenow={Math.round(wheel.amount * PERCENT_SCALE)}
+        aria-valuetext={`${Math.round(wheel.hue)} degrees, ${Math.round(
+          wheel.amount * PERCENT_SCALE,
+        )} percent`}
+        aria-disabled={disabled}
+        data-color-wheel-surface="true"
+        onDoubleClick={onReset}
+        onPointerDown={(event) => {
+          if (disabled) return;
+          event.preventDefault();
+          onBegin();
+          pointerIdRef.current = event.pointerId;
+          event.currentTarget.setPointerCapture(event.pointerId);
+          previewPointer(event.currentTarget, event.clientX, event.clientY);
+        }}
+        onPointerMove={(event) => {
+          if (disabled || pointerIdRef.current !== event.pointerId) return;
+          previewPointer(event.currentTarget, event.clientX, event.clientY);
+        }}
+        onPointerUp={(event) => {
+          if (pointerIdRef.current !== event.pointerId) return;
+          previewPointer(event.currentTarget, event.clientX, event.clientY);
+          pointerIdRef.current = null;
+          if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+            event.currentTarget.releasePointerCapture(event.pointerId);
+          }
+          onSettle();
+        }}
+        onPointerCancel={(event) => {
+          if (pointerIdRef.current !== event.pointerId) return;
+          pointerIdRef.current = null;
+          onCancel();
+        }}
+        onKeyDown={handleKeyDown}
+        onKeyUp={(event) => {
+          if (
+            ["ArrowLeft", "ArrowRight", "ArrowDown", "ArrowUp", "Home", "End"].includes(event.key)
+          ) {
+            onSettle();
+          }
+        }}
+        onBlur={onSettle}
+        className="relative mx-auto aspect-square w-full max-w-[112px] touch-none rounded-full border border-panel-border-input outline-none focus:ring-1 focus:ring-panel-accent disabled:opacity-40"
+        style={{
+          background:
+            "radial-gradient(circle, rgb(128 128 128) 0%, transparent 72%), conic-gradient(from 90deg, #f33, #f3f, #33f, #3ff, #3f3, #ff3, #f33)",
+        }}
+      >
+        <span
+          data-color-wheel-thumb="true"
+          className="pointer-events-none absolute h-2.5 w-2.5 -translate-x-1/2 -translate-y-1/2 rounded-full border border-white bg-transparent shadow-[0_0_0_1px_rgba(0,0,0,0.8)]"
+          style={{ left: `${thumbLeft}%`, top: `${thumbTop}%` }}
+        />
+      </div>
+      <input
+        type="range"
+        aria-label={`${label} level`}
+        min={WHEEL_CONTROLS.level.min}
+        max={WHEEL_CONTROLS.level.max}
+        step={0.01}
+        value={wheel.level}
+        disabled={disabled}
+        onPointerDown={onBegin}
+        onChange={(event) => onPreview({ ...wheel, level: Number(event.target.value) })}
+        onPointerUp={onSettle}
+        onPointerCancel={onCancel}
+        onKeyDown={(event) => {
+          if (event.key === "Escape") {
+            event.preventDefault();
+            onCancel();
+          } else {
+            onBegin();
+          }
+        }}
+        onKeyUp={onSettle}
+        onBlur={onSettle}
+        className="h-3 w-full accent-panel-accent"
+      />
+      <div className="grid grid-cols-3 gap-1">
+        <GradingNumberField
+          label="Hue"
+          value={wheel.hue}
+          min={WHEEL_CONTROLS.hue.min}
+          max={HUE_MAX}
+          disabled={disabled}
+          formatValue={formatIntegerInput}
+          labelTextClassName="block text-[8px] uppercase text-panel-text-5"
+          onBegin={onBegin}
+          onPreview={(hue) => onPreview({ ...wheel, hue: wrapHue(hue) })}
+          onSettle={onSettle}
+          onCancel={onCancel}
+        />
+        <GradingNumberField
+          label="Amount"
+          value={wheel.amount * PERCENT_SCALE}
+          min={WHEEL_CONTROLS.amount.min * PERCENT_SCALE}
+          max={WHEEL_CONTROLS.amount.max * PERCENT_SCALE}
+          disabled={disabled}
+          formatValue={formatIntegerInput}
+          labelTextClassName="block text-[8px] uppercase text-panel-text-5"
+          onBegin={onBegin}
+          onPreview={(amount) => onPreview({ ...wheel, amount: amount / PERCENT_SCALE })}
+          onSettle={onSettle}
+          onCancel={onCancel}
+        />
+        <GradingNumberField
+          label="Level"
+          value={wheel.level * PERCENT_SCALE}
+          min={WHEEL_CONTROLS.level.min * PERCENT_SCALE}
+          max={WHEEL_CONTROLS.level.max * PERCENT_SCALE}
+          disabled={disabled}
+          formatValue={formatIntegerInput}
+          labelTextClassName="block text-[8px] uppercase text-panel-text-5"
+          onBegin={onBegin}
+          onPreview={(level) => onPreview({ ...wheel, level: level / PERCENT_SCALE })}
+          onSettle={onSettle}
+          onCancel={onCancel}
+        />
+      </div>
+    </div>
+  );
+}
+
+export function ColorWheels({
+  value,
+  disabled,
+  onPreview,
+  onCommit,
+}: {
+  value: NormalizedHfColorGradingWheels;
+  disabled?: boolean;
+  onPreview: (value: NormalizedHfColorGradingWheels) => void;
+  onCommit: (value: NormalizedHfColorGradingWheels) => void;
+}) {
+  const { draft, setDraft, transaction } = useInspectorGestureDraft({
+    sourceValue: value,
+    onPreview,
+    onCommit,
+  });
+
+  const previewWheel = (key: HfColorGradingWheelKey, wheel: NormalizedTonalWheel) =>
+    transaction.preview(updateWheel(draft, key, wheel));
+  const resetWheel = (key: HfColorGradingWheelKey) => {
+    transaction.cancel();
+    const next = updateWheel(draft, key, RESET_WHEEL);
+    setDraft(next);
+    onCommit(next);
+  };
+
+  return (
+    <div
+      data-color-wheels="true"
+      className="grid grid-cols-[repeat(auto-fit,minmax(88px,1fr))] gap-2"
+    >
+      {WHEELS.map(({ key, label }) => (
+        <TonalWheel
+          key={key}
+          label={label}
+          wheel={draft[key]}
+          disabled={disabled}
+          onBegin={transaction.begin}
+          onPreview={(wheel) => previewWheel(key, wheel)}
+          onSettle={transaction.settle}
+          onCancel={transaction.cancel}
+          onReset={() => resetWheel(key)}
+        />
+      ))}
+    </div>
+  );
+}

package/src/components/editor/propertyPanelFlatColorGradingAccessory.tsx

@@ -0,0 +1,109 @@
+import { useEffect, useRef } from "react";
+import { isHfColorGradingActive } from "@hyperframes/core/color-grading";
+import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
+import { Compare, RotateCcw } from "../../icons/SystemIcons";
+import type { ColorGradingControllerState } from "./useColorGradingController";
+
+const STATUS_DOT_CLASS: Record<ColorGradingControllerState["runtimeStatus"]["state"], string> = {
+  active: "bg-emerald-400",
+  pending: "bg-amber-300",
+  unavailable: "bg-red-400",
+  missing: "bg-panel-text-5",
+  inactive: "bg-panel-text-5",
+};
+
+export function FlatColorGradingAccessory({
+  state,
+}: {
+  state: Pick<
+    ColorGradingControllerState,
+    "grading" | "compareEnabled" | "runtimeStatus" | "commitCompare" | "resetGrading"
+  >;
+}) {
+  const track = useTrackDesignInput();
+  const { grading, compareEnabled, runtimeStatus, commitCompare, resetGrading } = state;
+  const gradingActive = isHfColorGradingActive(grading);
+  const releaseRef = useRef<(() => void) | null>(null);
+  useEffect(
+    () => () => {
+      releaseRef.current?.();
+      releaseRef.current = null;
+    },
+    [],
+  );
+
+  return (
+    <span className="flex items-center gap-2.5">
+      <button
+        type="button"
+        aria-pressed={compareEnabled}
+        aria-label="Hold to show original"
+        disabled={!gradingActive}
+        onPointerDown={(e) => {
+          if (!gradingActive) return;
+          e.preventDefault();
+          e.stopPropagation();
+          track("button", "Compare original");
+          commitCompare(true);
+          const release = () => {
+            commitCompare(false);
+            window.removeEventListener("pointerup", release);
+            window.removeEventListener("pointercancel", release);
+            window.removeEventListener("blur", release);
+            releaseRef.current = null;
+          };
+          releaseRef.current = release;
+          window.addEventListener("pointerup", release);
+          window.addEventListener("pointercancel", release);
+          window.addEventListener("blur", release);
+        }}
+        onBlur={() => {
+          if (compareEnabled) commitCompare(false);
+        }}
+        onKeyDown={(e) => {
+          if (!gradingActive || (e.key !== " " && e.key !== "Enter")) return;
+          e.preventDefault();
+          if (!compareEnabled) {
+            track("button", "Compare original");
+            commitCompare(true);
+          }
+        }}
+        onKeyUp={(e) => {
+          if (!gradingActive || (e.key !== " " && e.key !== "Enter")) return;
+          e.preventDefault();
+          commitCompare(false);
+        }}
+        title="Hold to show original"
+        className="flex-shrink-0 text-panel-text-3 hover:text-panel-text-1 disabled:cursor-not-allowed disabled:opacity-40"
+      >
+        <Compare size={12} />
+      </button>
+      <span className="flex min-w-0 items-center gap-1" title={runtimeStatus.message}>
+        <span
+          data-flat-grade-status-dot="true"
+          title={runtimeStatus.message}
+          className={`h-[5px] w-[5px] flex-shrink-0 rounded-full ${STATUS_DOT_CLASS[runtimeStatus.state]}`}
+        />
+        <span
+          data-flat-grade-status-message="true"
+          className="max-w-[84px] truncate text-[9px] text-panel-text-4"
+        >
+          {runtimeStatus.message}
+        </span>
+      </span>
+      <button
+        type="button"
+        data-flat-grade-reset="true"
+        title="Reset color grading"
+        onClick={(e) => {
+          e.stopPropagation();
+          track("button", "Reset color grading");
+          resetGrading();
+        }}
+        className="flex-shrink-0 text-panel-text-3 hover:text-panel-text-1"
+      >
+        <RotateCcw size={12} />
+      </button>
+    </span>
+  );
+}

package/src/components/editor/propertyPanelFlatColorGradingSection.test.tsx

@@ -7,7 +7,10 @@ import {
   FlatColorGradingAccessory,
   FlatColorGradingSection,
 } from "./propertyPanelFlatColorGradingSection";
-import { normalizeHfColorGrading } from "@hyperframes/core/color-grading";
+import {
+  normalizeHfColorGrading,
+  type NormalizedHfColorGrading,
+} from "@hyperframes/core/color-grading";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -229,6 +232,7 @@ function neutralPropsBase() {
       height: 90,
     },
     onRequestPresetPreviews: vi.fn(),
+    captureGradedFrame: vi.fn(async () => null),
   };
 }
 
@@ -241,6 +245,35 @@ describe("FlatColorGradingSection — Preset + LUT", () => {
       ...base,
       intensity: 0.4,
       adjust: { ...base.adjust, contrast: 0.3 },
+      wheels: {
+        ...base.wheels,
+        shadows: { hue: 210, amount: 0.12, level: 0.04 },
+      },
+      curves: {
+        ...base.curves,
+        master: [
+          [0, 0],
+          [0.5, 0.58],
+          [1, 1],
+        ] as const,
+      },
+      hueCurves: {
+        ...base.hueCurves,
+        hueVsSaturation: [
+          [0, 0],
+          [120, 0.1],
+          [240, 0],
+        ] as const,
+      },
+      secondaries:
+        normalizeHfColorGrading({
+          secondaries: [
+            {
+              key: { hue: { center: 30, range: 15 } },
+              correction: { saturation: 0.08 },
+            },
+          ],
+        })?.secondaries ?? [],
       details: { ...base.details, vignette: 0.2 },
       effects: { ...base.effects, pixelate: 0.5 },
       palette: ["#112233", "#ffffff"],
@@ -277,11 +310,109 @@ describe("FlatColorGradingSection — Preset + LUT", () => {
       palette: ["#112233", "#ffffff"],
       lut: { src: "assets/luts/custom.cube", intensity: 0.6 },
     });
+    expect(onCommitColorGrading.mock.calls[0][0].wheels.shadows.amount).toBe(0);
+    expect(onCommitColorGrading.mock.calls[0][0].curves.master).toEqual([
+      [0, 0],
+      [1, 1],
+    ]);
+    expect(onCommitColorGrading.mock.calls[0][0].hueCurves.hueVsSaturation).toEqual([]);
+    expect(onCommitColorGrading.mock.calls[0][0].secondaries).toEqual([]);
     expect(onCommitColorGrading.mock.calls[0][0].adjust.contrast).not.toBe(0.3);
     expect(onCommitColorGrading.mock.calls[0][0].details.vignette).not.toBe(0.2);
     act(() => root.unmount());
   });
 
+  it("orders manual controls like the shader pipeline", () => {
+    const { host, root } = renderInto(<FlatColorGradingSection {...neutralPropsBase()} />);
+    const elements = [
+      host.querySelector('[data-flat-grade-adjust="true"]'),
+      host.querySelector('[data-color-wheels="true"]'),
+      host.querySelector('[data-color-curves="true"]'),
+      host.querySelector('[data-flat-grade-secondary="true"]'),
+      host.querySelector('[data-flat-grade-lut-toggle="true"]'),
+    ];
+    expect(elements.every(Boolean)).toBe(true);
+    for (let index = 0; index < elements.length - 1; index += 1) {
+      const current = elements[index];
+      const next = elements[index + 1];
+      if (!current || !next) throw new Error("expected all grading sections");
+      expect(current.compareDocumentPosition(next) & Node.DOCUMENT_POSITION_FOLLOWING).not.toBe(0);
+    }
+    act(() => root.unmount());
+  });
+
+  it("samples the full-strength signal entering the secondary stage", async () => {
+    const base = neutralGrading();
+    const grading = normalizeHfColorGrading({
+      ...base,
+      preset: "warm-polished",
+      intensity: 0.35,
+      adjust: { ...base.adjust, exposure: 0.2 },
+      wheels: {
+        ...base.wheels,
+        shadows: { hue: 210, amount: 0.2, level: 0.05 },
+      },
+      curves: {
+        ...base.curves,
+        master: [
+          [0, 0],
+          [0.5, 0.6],
+          [1, 1],
+        ],
+      },
+      hueCurves: {
+        ...base.hueCurves,
+        hueVsSaturation: [
+          [0, 0],
+          [120, 0.1],
+          [240, 0],
+        ],
+      },
+      secondaries: [{ key: { hue: { center: 30, range: 15 } }, correction: {} }],
+      details: { ...base.details, vignette: 0.4, grain: 0.2 },
+      effects: { ...base.effects, pixelate: 0.5 },
+      lut: { src: "assets/luts/custom.cube", intensity: 0.8 },
+    });
+    if (!grading) throw new Error("expected a secondary grade");
+    const captureGradedFrame = vi.fn(
+      async (_options?: { grading?: NormalizedHfColorGrading }) => null,
+    );
+    const { host, root } = renderInto(
+      <FlatColorGradingSection
+        {...neutralPropsBase()}
+        grading={grading}
+        captureGradedFrame={captureGradedFrame}
+      />,
+    );
+
+    await act(async () => {
+      const sample = Array.from(host.querySelectorAll<HTMLButtonElement>("button")).find((button) =>
+        button.textContent?.includes("Sample color from frame"),
+      );
+      sample?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+      await Promise.resolve();
+    });
+
+    expect(captureGradedFrame).toHaveBeenCalledTimes(1);
+    const options = captureGradedFrame.mock.calls[0]?.[0];
+    const sampledGrading = options?.grading;
+    if (!sampledGrading) throw new Error("expected the sampled grading input");
+    expect(sampledGrading).toMatchObject({
+      preset: null,
+      intensity: 1,
+      adjust: grading.adjust,
+      wheels: grading.wheels,
+      curves: grading.curves,
+      hueCurves: grading.hueCurves,
+      secondaries: [],
+      lut: null,
+    });
+    expect(sampledGrading.details.vignette).toBe(0);
+    expect(sampledGrading.details.grain).toBe(0);
+    expect(sampledGrading.effects.pixelate).toBe(0);
+    act(() => root.unmount());
+  });
+
   it("keeps effect-bearing saved styles out of Grade", () => {
     const { host, root } = renderInto(<FlatColorGradingSection {...neutralPropsBase()} />);
     const presets = host.querySelector('[data-flat-grade-preset-group="presets"]');
@@ -294,7 +425,7 @@ describe("FlatColorGradingSection — Preset + LUT", () => {
     act(() => root.unmount());
   });
 
-  it("shows exact selected-media preview images and requests a fresh batch on mount", () => {
+  it("shows ready selected-media preview images without requesting a duplicate batch", () => {
     const onRequestPresetPreviews = vi.fn();
     const { host, root } = renderInto(
       <FlatColorGradingSection
@@ -302,7 +433,7 @@ describe("FlatColorGradingSection — Preset + LUT", () => {
         onRequestPresetPreviews={onRequestPresetPreviews}
       />,
     );
-    expect(onRequestPresetPreviews).toHaveBeenCalledTimes(1);
+    expect(onRequestPresetPreviews).not.toHaveBeenCalled();
     expect(
       host.querySelector<HTMLImageElement>('[data-flat-grade-preview="bright-pop"]')?.src,
     ).toContain("data:image/png;base64,bright");
@@ -310,6 +441,40 @@ describe("FlatColorGradingSection — Preset + LUT", () => {
     act(() => root.unmount());
   });
 
+  it("requests an idle preview batch once", () => {
+    const onRequestPresetPreviews = vi.fn();
+    const props = neutralPropsBase();
+    const { root } = renderInto(
+      <FlatColorGradingSection
+        {...props}
+        presetPreviews={{ ...props.presetPreviews, status: "idle", images: {} }}
+        onRequestPresetPreviews={onRequestPresetPreviews}
+      />,
+    );
+    expect(onRequestPresetPreviews).toHaveBeenCalledTimes(1);
+    act(() => root.unmount());
+  });
+
+  it("requires an explicit retry after a preview failure", () => {
+    const onRequestPresetPreviews = vi.fn();
+    const props = neutralPropsBase();
+    const { host, root } = renderInto(
+      <FlatColorGradingSection
+        {...props}
+        presetPreviews={{ ...props.presetPreviews, status: "unavailable", images: {} }}
+        onRequestPresetPreviews={onRequestPresetPreviews}
+      />,
+    );
+    expect(onRequestPresetPreviews).not.toHaveBeenCalled();
+    const retry = Array.from(host.querySelectorAll("button")).find(
+      (button) => button.textContent === "Retry look previews",
+    );
+    if (!retry) throw new Error("expected an explicit preview retry");
+    act(() => retry.dispatchEvent(new MouseEvent("click", { bubbles: true })));
+    expect(onRequestPresetPreviews).toHaveBeenCalledTimes(1);
+    act(() => root.unmount());
+  });
+
   it("shows the Custom LUT row collapsed by default, expanding to reveal the strength slider when a LUT is set", () => {
     const grading = { ...neutralGrading(), lut: { src: "assets/luts/warm.cube", intensity: 0.8 } };
     const { host, root } = renderInto(