@hyperframes/studio 0.8.77 → 0.8.79

package/src/index.ts

@@ -162,6 +162,7 @@ export type { StudioPendingEditsDrainResult } from "./utils/studioPendingEdits";
 export type {
   CanEditTimelineElement,
   TimelineEditPermission,
+  TimelineEditOutcome,
 } from "./hooks/timelineEditPermission";
 export { useEditHistoryActions } from "./hooks/useEditHistoryActions";
 export type {
@@ -183,3 +184,10 @@ export type { TimelinePaneProps } from "./components/nle/TimelinePane";
 export { TimelineEditProvider } from "./contexts/TimelineEditContext";
 export type { TimelineEditCallbacks } from "./player/components/timelineCallbacks";
 export type { BlockedTimelineEditIntent } from "./player/components/timelineEditing";
+
+export {
+  playSeamTransitionLoop,
+  type SeamTransitionFrameSource,
+  type SeamTransitionLoopHandle,
+  type SeamTransitionLoopOptions,
+} from "@hyperframes/shader-transitions";

package/src/player/components/Player.test.ts

@@ -127,6 +127,11 @@ describe("preview errors", () => {
     root = null;
   });
 
+  it("puts the preview on the player's once-a-second paused heartbeat", async () => {
+    const { player } = await mountPlayer();
+    expect(player.hasAttribute("low-power-idle")).toBe(true);
+  });
+
   it("attaches lifecycle listeners before navigating the player", async () => {
     await mountPlayer();
     const srcIndex = lifecycleLog.indexOf("src");

package/src/player/components/Player.tsx

@@ -317,6 +317,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
 
         player.setAttribute("shader-capture-scale", "1");
         player.setAttribute("shader-loading", "player");
+        player.setAttribute("low-power-idle", "");
         player.setAttribute("width", String(portrait ? 1080 : 1920));
         player.setAttribute("height", String(portrait ? 1920 : 1080));
         player.style.width = "100%";

package/src/player/components/VideoThumbnail.test.tsx

@@ -86,6 +86,19 @@ describe("VideoThumbnail", () => {
     expect(host.querySelectorAll("img").length).toBeGreaterThan(0);
   });
 
+  it("spreads the frames across every tile so the strip reaches the clip's end", async () => {
+    const urls = Array.from({ length: 8 }, (_, index) => `blob:${index}`);
+    vi.mocked(decodeVideoThumbnail).mockResolvedValue({
+      value: { kind: "filmstrip", urls, aspect: 16 / 9 },
+      weight: 256,
+    });
+
+    await render(500);
+
+    const tiles = [...host.querySelectorAll("img")].map((img) => img.getAttribute("src"));
+    expect(tiles).toEqual(["blob:0", "blob:2", "blob:4", "blob:5", "blob:7"]);
+  });
+
   it("issues a single decode job for a narrow clip", async () => {
     vi.mocked(decodeVideoThumbnail).mockResolvedValue({
       value: { kind: "image", url: "blob:poster", aspect: 16 / 9 },

package/src/player/components/VideoThumbnail.tsx

@@ -146,7 +146,7 @@ export const VideoThumbnail = memo(function VideoThumbnail({
       {urls.length > 0 && (
         <div className="absolute inset-0 flex">
           {Array.from({ length: frameCount }, (_, index) => {
-            const src = urls[index % urls.length];
+            const src = urls[Math.round((index * (urls.length - 1)) / Math.max(1, frameCount - 1))];
             return (
               <div
                 key={index}

package/src/player/components/timelineCallbacks.ts

@@ -1,5 +1,6 @@
 // fallow-ignore-file code-duplication
 // fallow-ignore-file dead-code
+import type { TimelineEditOutcome } from "../../hooks/timelineEditPermission";
 import type { TimelineElement } from "../store/playerStore";
 import type { TimelineMoveOperation } from "../../hooks/timelineMoveAdapter";
 import type { BlockedTimelineEditIntent } from "./timelineEditing";
@@ -89,7 +90,7 @@ export interface TimelineEditCallbacks {
     attr: string,
     value: string | null,
     label: string,
-  ) => Promise<void>;
+  ) => Promise<TimelineEditOutcome | void>;
   /** C1's ungrouped-track FX pointer: "Group these clips" — write
    *  `data-audio-group` on every one of them, atomically. Same shape B6's
    *  carve auto-grouping uses. */
@@ -110,7 +111,7 @@ export interface TimelineEditCallbacks {
     attr: string,
     value: string | null,
     label: string,
-  ) => Promise<void>;
+  ) => Promise<TimelineEditOutcome | void>;
   onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
   onSplitElement?: (element: TimelineElement, splitTime: number) => Promise<void> | void;
   onRazorSplit?: (element: TimelineElement, splitTime: number) => Promise<void> | void;

package/src/player/hooks/useTimelinePlayer.hiddenPause.test.ts

@@ -0,0 +1,75 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore } from "../store/playerStore";
+import {
+  attachIframeWindow,
+  makeAdapterWindow,
+  renderTimelinePlayerHarness,
+  resetPlayerStore,
+} from "./timelinePlayerTestHarness";
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  document.body.innerHTML = "";
+  resetPlayerStore();
+});
+
+describe("useTimelinePlayer tab hidden while playing", () => {
+  it("pauses on the adapter's time, like any other pause", () => {
+    const { api, root } = renderTimelinePlayerHarness();
+    const { adapter, win } = makeAdapterWindow();
+    attachIframeWindow(api, win);
+    act(() => api.play());
+    adapter.seek(6);
+
+    vi.spyOn(document, "hidden", "get").mockReturnValue(true);
+    act(() => void document.dispatchEvent(new Event("visibilitychange")));
+
+    expect(usePlayerStore.getState().isPlaying).toBe(false);
+    expect(usePlayerStore.getState().currentTime).toBe(6);
+    act(() => root.unmount());
+  });
+
+  it("stops a reverse shuttle for good", async () => {
+    const { api, root } = renderTimelinePlayerHarness();
+    const { adapter, win } = makeAdapterWindow();
+    attachIframeWindow(api, win);
+    adapter.seek(20);
+    act(() => void window.dispatchEvent(new KeyboardEvent("keydown", { code: "KeyJ", key: "j" })));
+    await act(() => new Promise((r) => setTimeout(r, 100)));
+    expect(usePlayerStore.getState().isPlaying).toBe(true);
+
+    vi.spyOn(document, "hidden", "get").mockReturnValue(true);
+    act(() => void document.dispatchEvent(new Event("visibilitychange")));
+    const stoppedAt = adapter.getTime();
+    await act(() => new Promise((r) => setTimeout(r, 200)));
+
+    expect(usePlayerStore.getState().isPlaying).toBe(false);
+    expect(adapter.getTime()).toBe(stoppedAt);
+    expect(usePlayerStore.getState().currentTime).toBe(stoppedAt);
+    act(() => root.unmount());
+  });
+
+  it("does not carry the shuttle speed past the pause", () => {
+    const { api, root } = renderTimelinePlayerHarness();
+    attachIframeWindow(api, makeAdapterWindow().win);
+    const pressL = () =>
+      act(
+        () => void window.dispatchEvent(new KeyboardEvent("keydown", { code: "KeyL", key: "l" })),
+      );
+    pressL();
+    pressL();
+    expect(usePlayerStore.getState().playbackRate).toBe(2);
+
+    vi.spyOn(document, "hidden", "get").mockReturnValue(true);
+    act(() => void document.dispatchEvent(new Event("visibilitychange")));
+    pressL();
+
+    expect(usePlayerStore.getState().playbackRate).toBe(1);
+    act(() => root.unmount());
+  });
+});

package/src/player/hooks/useTimelinePlayer.play.test.ts

@@ -95,6 +95,42 @@ it.each([30, 0])(
   },
 );
 
+it("settles a load whose runtime learns its duration after its only readiness post", async () => {
+  const { api, root } = renderTimelinePlayerHarness();
+  let duration = 0;
+  const { adapter, win } = makeAdapterWindow();
+  adapter.getDuration = () => duration;
+  act(() => {
+    api.iframeRef.current = makeFakeIframe(win);
+    api.onIframeLoad();
+  });
+  postFromRuntime(win, { type: "state" });
+  expect(adapter.pause).not.toHaveBeenCalled();
+
+  // No further post comes: a paused low-power preview checks in only once a second.
+  duration = 30;
+  await act(() => new Promise((resolve) => requestAnimationFrame(() => resolve(undefined))));
+  expect(adapter.pause).toHaveBeenCalled();
+  act(() => root.unmount());
+});
+
+it.each(["unmounts", "resets"])("stops retrying a pending load once the player %s", async (how) => {
+  const { api, root } = renderTimelinePlayerHarness();
+  const { adapter, win } = makeAdapterWindow();
+  let lookups = 0;
+  adapter.getDuration = () => (lookups++, 0);
+  act(() => {
+    api.iframeRef.current = makeFakeIframe(win);
+    api.onIframeLoad();
+  });
+  postFromRuntime(win, { type: "state" });
+  act(() => (how === "resets" ? api.resetPlayer() : root.unmount()));
+  const atStop = lookups;
+  await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+  expect(lookups).toBe(atStop);
+  if (how === "resets") act(() => root.unmount());
+});
+
 it("does not let the blank page's load step enable Play for the preview that replaces it", async () => {
   const { api, root } = renderTimelinePlayerHarness();
   // The iframe's first load is about:blank, before the runtime exists; its load step waits for runtime messages.

package/src/player/hooks/useTimelinePlayer.ts

@@ -362,21 +362,25 @@ export function useTimelinePlayer({
       seek,
     });
 
-  const { processTimelineMessageRef, enrichMissingCompositionsRef, onIframeLoad } =
-    useTimelineSyncCallbacks({
-      iframeRef,
-      probeIntervalRef,
-      pendingSeekRef,
-      isRefreshingRef,
-      getAdapter,
-      syncTimelineElements,
-      setDuration,
-      setCurrentTime,
-      requestTimelineReady,
-      setIsPlaying,
-      attachIframeShortcutListeners,
-      applyPreviewAudioState,
-    });
+  const {
+    processTimelineMessageRef,
+    enrichMissingCompositionsRef,
+    onIframeLoad,
+    cancelPendingLoad,
+  } = useTimelineSyncCallbacks({
+    iframeRef,
+    probeIntervalRef,
+    pendingSeekRef,
+    isRefreshingRef,
+    getAdapter,
+    syncTimelineElements,
+    setDuration,
+    setCurrentTime,
+    requestTimelineReady,
+    setIsPlaying,
+    attachIframeShortcutListeners,
+    applyPreviewAudioState,
+  });
 
   // Full-reload edits load behind a hidden shadow iframe (useShadowPreviewReload.ts).
   const {
@@ -452,8 +456,8 @@ export function useTimelinePlayer({
     applyPreviewVariablesToUrl(url);
     beginShadowReload(url.toString());
   }, [saveSeekPosition, getAdapter, beginShadowReload]);
-  const getAdapterRef = useRef(getAdapter);
-  getAdapterRef.current = getAdapter;
+  const pauseRef = useRef(pause);
+  pauseRef.current = pause;
 
   useMountEffect(() => {
     const handleWindowKeyDown = (e: KeyboardEvent) => playbackKeyDownRef.current(e);
@@ -469,14 +473,7 @@ export function useTimelinePlayer({
     });
 
     const handleVisibilityChange = () => {
-      if (document.hidden && usePlayerStore.getState().isPlaying) {
-        const adapter = getAdapterRef.current?.();
-        if (adapter) {
-          adapter.pause();
-          setIsPlaying(false);
-          stopRAFLoop();
-        }
-      }
+      if (document.hidden && usePlayerStore.getState().isPlaying) pauseRef.current();
     };
 
     window.addEventListener("keydown", handleWindowKeyDown, true);
@@ -494,16 +491,16 @@ export function useTimelinePlayer({
       stopReverseLoop();
       stopScrubPreviewAudio();
       releaseStaticSeekCache(staticSeekAdapterRef, staticSeekWarnedRef);
-      if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
+      cancelPendingLoad();
     };
   });
 
   const resetPlayer = useCallback(() => {
     stopRAFLoop();
     stopReverseLoop();
-    if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
+    cancelPendingLoad();
     usePlayerStore.getState().reset();
-  }, [stopRAFLoop, stopReverseLoop]);
+  }, [stopRAFLoop, stopReverseLoop, cancelPendingLoad]);
 
   useEffect(() => {
     return usePlayerStore.subscribe((state, prev) => {

package/src/player/hooks/useTimelineSyncCallbacks.ts

@@ -244,7 +244,7 @@ export function useTimelineSyncCallbacks({
       adapter.pause();
       const startTime = seekAdapterToRestorePoint(adapter, pendingSeekRef);
       const commit = () => {
-        // Keep non-React listeners such as the capture link and time display in sync
+        // Keep non-React listeners such as the time display in sync
         // with the initial adapter seek on iframe load.
         liveTime.notify(startTime);
         syncAdapterDuration(adapter, setDuration);
@@ -309,28 +309,36 @@ export function useTimelineSyncCallbacks({
       // Listen for those instead of polling.
       const iframe = iframeRef.current;
       let settled = false;
+      let retryFrame = 0;
+      const stopWaiting = () => {
+        window.removeEventListener("message", onMessage);
+        cancelAnimationFrame(retryFrame);
+      };
 
       const trySettle = () => {
         if (settled) return;
         if (initializeAdapter(context)) {
           settled = true;
-          window.removeEventListener("message", onMessage);
+          stopWaiting();
           if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
+          return;
         }
+        cancelAnimationFrame(retryFrame);
+        retryFrame = requestAnimationFrame(trySettle);
       };
 
       const onMessage = (e: MessageEvent) => {
         if (isPreviewReadinessMessage(e, iframe)) trySettle();
       };
       window.addEventListener("message", onMessage);
-      stopWaitingRef.current = () => window.removeEventListener("message", onMessage);
+      stopWaitingRef.current = stopWaiting;
 
       // Safety net: if no message arrives within 5s, try one last time then give up.
       probeIntervalRef.current = setTimeout(() => {
         if (!settled) {
           trySettle();
         }
-        window.removeEventListener("message", onMessage);
+        stopWaiting();
         if (!settled) onLoadGiveUp?.(context);
         revealIframe(iframeRef.current);
       }, 5000) as unknown as ReturnType<typeof setInterval>;

package/src/player/lib/thumbnailVideoDecoder.test.ts

@@ -5,6 +5,7 @@ import { decodeVideoThumbnail, videoThumbnailTimestamps } from "./thumbnailVideo
 
 const dispose = vi.fn();
 const canvasesAtTimestamps = vi.fn();
+const getKeyPacket = vi.fn(async (_time: number) => null as { timestamp: number } | null);
 const input = {
   getPrimaryVideoTrack: vi.fn(),
   dispose,
@@ -22,10 +23,25 @@ vi.mock("mediabunny", () => ({
   CanvasSink: class {
     canvasesAtTimestamps = canvasesAtTimestamps;
   },
+  EncodedPacketSink: class {
+    getKeyPacket = getKeyPacket;
+  },
 }));
 
+function recordDecodes(decoded: number[][]): void {
+  canvasesAtTimestamps.mockImplementation(async function* (timestamps: AsyncIterable<number>) {
+    const run: number[] = [];
+    decoded.push(run);
+    for await (const time of timestamps) {
+      run.push(time);
+      yield { canvas: document.createElement("canvas") };
+    }
+  });
+}
+
 beforeEach(() => {
   vi.clearAllMocks();
+  getKeyPacket.mockImplementation(async () => null);
   vi.spyOn(URL, "createObjectURL").mockReturnValueOnce("blob:one").mockReturnValueOnce("blob:two");
   vi.spyOn(URL, "revokeObjectURL").mockImplementation(() => {});
   HTMLCanvasElement.prototype.toBlob = function toBlob(callback) {
@@ -52,17 +68,14 @@ describe("videoThumbnailTimestamps", () => {
 
 describe("decodeVideoThumbnail", () => {
   it("extracts sparse frames, returns object URLs, and disposes once", async () => {
-    const canvas = document.createElement("canvas");
-    canvasesAtTimestamps.mockImplementation(async function* (timestamps: number[]) {
-      expect(timestamps).toEqual([2, 8]);
-      yield { canvas, timestamp: 2, duration: 1 };
-      yield { canvas, timestamp: 8, duration: 1 };
-    });
+    const decoded: number[][] = [];
+    recordDecodes(decoded);
     const result = await decodeVideoThumbnail(
       { source: "/clip.mp4", sourceStart: 2, sourceRangeDuration: 6, frameCount: 2 },
       new AbortController().signal,
     );
 
+    expect(decoded).toEqual([[2, 8]]);
     expect(result.value).toEqual({
       kind: "filmstrip",
       urls: ["blob:one", "blob:two"],
@@ -74,6 +87,89 @@ describe("decodeVideoThumbnail", () => {
     expect(dispose).toHaveBeenCalledTimes(1);
   });
 
+  it("decodes each strip frame at its keyframe unless that keyframe is before the clip's range", async () => {
+    getKeyPacket.mockImplementation(async (time) => ({ timestamp: Math.floor(time / 4) * 4 }));
+    const decoded: number[][] = [];
+    recordDecodes(decoded);
+    await decodeVideoThumbnail(
+      { source: "/clip.mp4", sourceStart: 2, sourceRangeDuration: 8, frameCount: 3 },
+      new AbortController().signal,
+    );
+    expect(decoded).toEqual([[2, 4, 8]]);
+  });
+
+  it("keeps a slot's own time when its keyframe is more than half a slot earlier", async () => {
+    getKeyPacket.mockImplementation(async () => ({ timestamp: 0 }));
+    const decoded: number[][] = [];
+    recordDecodes(decoded);
+    await decodeVideoThumbnail(
+      { source: "/clip.mp4", sourceStart: 0, sourceRangeDuration: 10, frameCount: 3 },
+      new AbortController().signal,
+    );
+    await decodeVideoThumbnail(
+      { source: "/clip.mp4", sourceStart: 0, sourceRangeDuration: 10, frameCount: 1 },
+      new AbortController().signal,
+    );
+    expect(decoded).toEqual([[0, 5, 10], [5]]);
+  });
+
+  it("looks up each keyframe just before decoding it", async () => {
+    const events: string[] = [];
+    getKeyPacket.mockImplementation(async (time) => {
+      events.push(`key ${time}`);
+      return { timestamp: time };
+    });
+    canvasesAtTimestamps.mockImplementation(async function* (timestamps: AsyncIterable<number>) {
+      for await (const time of timestamps) {
+        events.push(`frame ${time}`);
+        yield { canvas: document.createElement("canvas") };
+      }
+    });
+    await decodeVideoThumbnail(
+      { source: "/clip.mp4", sourceStart: 0, sourceRangeDuration: 10, frameCount: 3 },
+      new AbortController().signal,
+    );
+    expect(events).toEqual(["key 0", "frame 0", "key 5", "frame 5", "key 10", "frame 10"]);
+  });
+
+  it("ends the decode times without throwing when cancelled during a keyframe lookup", async () => {
+    const controller = new AbortController();
+    getKeyPacket.mockImplementation(async () => (controller.abort(), null));
+    const decoded: number[] = [];
+    let timesEnded = false;
+    canvasesAtTimestamps.mockImplementation(async function* (timestamps: AsyncIterable<number>) {
+      for await (const time of timestamps) {
+        decoded.push(time);
+        yield { canvas: document.createElement("canvas") };
+      }
+      timesEnded = true;
+    });
+    await expect(
+      decodeVideoThumbnail(
+        { source: "/clip.mp4", sourceStart: 0, sourceRangeDuration: 10, frameCount: 3 },
+        controller.signal,
+      ),
+    ).rejects.toThrow("Aborted");
+    expect(getKeyPacket).toHaveBeenCalledTimes(1);
+    expect(decoded).toEqual([]);
+    expect(timesEnded).toBe(true);
+  });
+
+  it("spreads a trimmed strip across its range when the file reports no duration", async () => {
+    input.getPrimaryVideoTrack.mockResolvedValue({
+      getDisplayWidth: vi.fn(async () => 1080),
+      getDisplayHeight: vi.fn(async () => 1920),
+      getDurationFromMetadata: vi.fn(async () => null),
+    });
+    const decoded: number[][] = [];
+    recordDecodes(decoded);
+    await decodeVideoThumbnail(
+      { source: "/clip.mp4", sourceStart: 5, sourceRangeDuration: 5, frameCount: 3 },
+      new AbortController().signal,
+    );
+    expect(decoded).toEqual([[5, 7.5, 10]]);
+  });
+
   it("releases input and degrades when the source has no video track", async () => {
     input.getPrimaryVideoTrack.mockResolvedValue(null);
     await expect(

package/src/player/lib/thumbnailVideoDecoder.ts

@@ -44,7 +44,7 @@ interface DecodedResources {
 
 interface ThumbnailCanvasSink {
   canvasesAtTimestamps(
-    timestamps: number[],
+    timestamps: AsyncIterable<number>,
   ): AsyncIterable<{ canvas: HTMLCanvasElement | OffscreenCanvas } | null>;
 }
 
@@ -77,7 +77,7 @@ function targetDimensions(
 
 async function decodeFrames(
   sink: ThumbnailCanvasSink,
-  timestamps: number[],
+  timestamps: AsyncIterable<number>,
   signal: AbortSignal,
   resources: DecodedResources,
 ): Promise<void> {
@@ -89,6 +89,7 @@ async function decodeFrames(
     throwIfAborted(signal);
     resources.urls.push(URL.createObjectURL(blob));
   }
+  throwIfAborted(signal);
 }
 
 function loadedResult(
@@ -138,8 +139,12 @@ export async function decodeVideoThumbnail(
     }
     const metadataDuration = await track.getDurationFromMetadata({ skipLiveWait: true });
     throwIfAborted(signal);
-    const sourceDuration = Math.max(0, metadataDuration ?? request.sourceRangeDuration ?? 0);
-    const sourceStart = Math.min(Math.max(0, request.sourceStart ?? 0), sourceDuration);
+    const requestedStart = Math.max(0, request.sourceStart ?? 0);
+    const sourceDuration = Math.max(
+      0,
+      metadataDuration ?? requestedStart + (request.sourceRangeDuration ?? 0),
+    );
+    const sourceStart = Math.min(requestedStart, sourceDuration);
     const requestedDuration =
       request.sourceRangeDuration ?? Math.max(0, sourceDuration - sourceStart);
     const duration = Math.min(
@@ -151,6 +156,16 @@ export async function decodeVideoThumbnail(
       duration,
       Math.min(request.frameCount, budgets.richPreviewFrameCount),
     );
+    const keys = new mediabunny.EncodedPacketSink(track);
+    const maxKeyframeLead = duration / Math.max(2, timestamps.length - 1) / 2;
+    async function* decodeTimesAtNearbyKeyframes() {
+      for (const time of timestamps) {
+        const key = await keys.getKeyPacket(time, { metadataOnly: true });
+        if (signal.aborted) return;
+        const near = key && key.timestamp >= sourceStart && time - key.timestamp <= maxKeyframeLead;
+        yield near ? key.timestamp : time;
+      }
+    }
     const aspect = displayWidth / displayHeight;
     const target = targetDimensions(aspect, budgets);
     const sink = new mediabunny.CanvasSink(track, {
@@ -159,7 +174,7 @@ export async function decodeVideoThumbnail(
       fit: request.fit ?? "cover",
       poolSize: 1,
     });
-    await decodeFrames(sink, timestamps, signal, resources);
+    await decodeFrames(sink, decodeTimesAtNearbyKeyframes(), signal, resources);
     return loadedResult(resources, aspect, target.width, target.height);
   } catch (error) {
     releaseDecodedResources(resources);

package/src/telemetry/client.test.ts

@@ -30,6 +30,7 @@ describe("studio client shouldTrack", () => {
     setDev(false);
     setNoTelemetry(undefined);
     localStorage.clear();
+    delete window.__HF_CLI_TELEMETRY_DISABLED;
     vi.unstubAllGlobals();
   });
 
@@ -89,3 +90,28 @@ describe("studio client shouldTrack", () => {
     expect(shouldTrack()).toBe(false);
   });
 });
+
+it("suppresses actual render events in a CLI-opted-out Studio while the enabled control sends", async () => {
+  vi.useFakeTimers();
+  vi.resetModules();
+  setDev(false);
+  setNoTelemetry(undefined);
+  localStorage.clear();
+  const send = vi.fn().mockResolvedValue(new Response());
+  vi.stubGlobal("fetch", send);
+  try {
+    const { trackEvent } = await import("./client");
+    window.__HF_CLI_TELEMETRY_DISABLED = true;
+    trackEvent("render_complete", { duration: 1 });
+    await vi.advanceTimersByTimeAsync(1100);
+    expect(send).not.toHaveBeenCalled();
+    window.__HF_CLI_TELEMETRY_DISABLED = false;
+    trackEvent("render_complete", { duration: 1 });
+    await vi.advanceTimersByTimeAsync(1100);
+    expect(send).toHaveBeenCalledOnce();
+  } finally {
+    delete window.__HF_CLI_TELEMETRY_DISABLED;
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+  }
+});

package/src/telemetry/policy.test.ts

@@ -15,6 +15,7 @@ describe("browserTelemetryAllowed", () => {
 
   beforeEach(async () => {
     localStorage.clear();
+    delete window.__HF_CLI_TELEMETRY_DISABLED;
     vi.resetModules();
     // vitest sets import.meta.env.DEV; the policy suppresses under it, so the
     // baseline has to be an explicitly production-like env.
@@ -28,6 +29,15 @@ describe("browserTelemetryAllowed", () => {
     vi.unstubAllEnvs();
   });
 
+  it("refuses a CLI opt-out even when browser storage permits telemetry", () => {
+    expect(browserTelemetryAllowed()).toBe(true);
+    window.__HF_CLI_TELEMETRY_DISABLED = true;
+    expect(browserTelemetryAllowed()).toBe(false);
+    expect(localStorage.getItem(DOCUMENTED_OPT_OUT)).toBeNull();
+    window.__HF_CLI_TELEMETRY_DISABLED = false;
+    expect(browserTelemetryAllowed()).toBe(true);
+  });
+
   it("allows telemetry with no control set", () => {
     expect(browserTelemetryAllowed()).toBe(true);
   });

package/src/telemetry/policy.ts

@@ -92,10 +92,17 @@ export function browserTelemetryAllowed(): boolean {
   }
 }
 
+declare global {
+  interface Window {
+    __HF_CLI_TELEMETRY_DISABLED?: boolean;
+  }
+}
+
 function allowed(): boolean {
   return (
     isApiKeyConfigured() &&
     !isBuildTimeOptOut() &&
+    !(typeof window !== "undefined" && window.__HF_CLI_TELEMETRY_DISABLED === true) &&
     !isViteDevMode() &&
     !isOptedOut() &&
     !isLegacyOptedOut() &&