@hyperframes/studio 0.8.114 → 0.8.115

package/src/hooks/useGsapKeyframeOps.sdkUsage.test.tsx

@@ -0,0 +1,114 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useGsapKeyframeOps } from "./useGsapKeyframeOps";
+import type { CutoverResult } from "../utils/sdkCutover";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { trackStudioEvent } from "../utils/studioTelemetry";
+
+const sdkWrite = vi.hoisted(() => vi.fn<(...args: unknown[]) => Promise<CutoverResult>>());
+vi.mock("../utils/sdkCutover", async (original) => ({
+  ...(await original<typeof import("../utils/sdkCutover")>()),
+  sdkGsapKeyframePersist: sdkWrite,
+  sdkGsapConvertToKeyframesPersist: sdkWrite,
+  sdkGsapRemoveAllKeyframesPersist: sdkWrite,
+}));
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+type Params = Parameters<typeof useGsapKeyframeOps>[0];
+let root: Root;
+function mount() {
+  let api: ReturnType<typeof useGsapKeyframeOps> | undefined;
+  const legacy = vi.fn(async () => undefined);
+  function Probe() {
+    api = useGsapKeyframeOps({
+      activeCompPath: "index.html",
+      commitMutation: legacy,
+      commitMutationSafely: legacy,
+      trackGsapSaveFailure: vi.fn(),
+      sdkSession: {} as NonNullable<Params["sdkSession"]>,
+      sdkDeps: {
+        editHistory: { recordEdit: vi.fn(async () => undefined) },
+        writeProjectFile: vi.fn(async () => undefined),
+        reloadPreview: vi.fn(),
+      },
+    });
+    return null;
+  }
+  root = createRoot(document.createElement("div"));
+  act(() => root.render(<Probe />));
+  if (!api) throw new Error("hook did not mount");
+  return { api, legacy };
+}
+const selection = { id: "private-target", sourceFile: "private.html" } as DomEditSelection;
+beforeEach(() => {
+  vi.clearAllMocks();
+  sdkWrite.mockResolvedValue({
+    status: "committed",
+    version: "v2",
+    before: "before",
+    after: "after",
+  });
+});
+afterEach(() => act(() => root.unmount()));
+describe("SDK keyframe usage", () => {
+  it.each(["add", "convert", "remove_all", "reset"] as const)(
+    "counts a changed committed %s operation once",
+    async (action) => {
+      const { api, legacy } = mount();
+      await act(async () => {
+        if (action === "add")
+          await api.addKeyframeBatch(selection, "private-animation", 50, { x: 12, y: 4 });
+        else if (action === "convert") await api.convertToKeyframes(selection, "private-animation");
+        else await api.removeAllKeyframes(selection, "private-animation", action);
+      });
+      expect(legacy).not.toHaveBeenCalled();
+      expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("keyframe", { action });
+    },
+  );
+  it("preserves property metadata on a single-property SDK add", async () => {
+    const { api } = mount();
+    await act(async () => api.addKeyframe(selection, "private-animation", 50, "x", 12));
+    expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("keyframe", {
+      action: "add",
+      property: "x",
+    });
+  });
+  it("does not count unchanged SDK source", async () => {
+    sdkWrite.mockResolvedValue({
+      status: "committed",
+      version: "v2",
+      before: "same",
+      after: "same",
+    });
+    const { api } = mount();
+    await api.addKeyframeBatch(selection, "private-animation", 50, { x: 12 });
+    expect(await api.removeAllKeyframes(selection, "private-animation")).toBe(false);
+    expect(trackStudioEvent).not.toHaveBeenCalled();
+  });
+  it("honors intermediate-write suppression in SDK paths", async () => {
+    const { api } = mount();
+    await api.convertToKeyframes(selection, "private-animation", undefined, undefined, {
+      keyframeTelemetry: false,
+    });
+    await api.addKeyframeBatch(
+      selection,
+      "private-animation",
+      50,
+      { x: 12 },
+      { keyframeTelemetry: false },
+    );
+    await api.removeAllKeyframes(selection, "private-animation", "remove_all", false);
+    expect(trackStudioEvent).not.toHaveBeenCalled();
+  });
+  it("does not fall back or count after a failed SDK write", async () => {
+    sdkWrite.mockResolvedValue({ status: "failed", error: new Error("refused") });
+    const { api, legacy } = mount();
+    await expect(
+      api.addKeyframeBatch(selection, "private-animation", 50, { x: 12 }),
+    ).rejects.toThrow("refused");
+    expect(legacy).not.toHaveBeenCalled();
+    expect(trackStudioEvent).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/useGsapKeyframeOps.ts

@@ -1,3 +1,4 @@
+import { trackKeyframeUsage } from "../utils/keyframeUsage";
 // fallow-ignore-file code-duplication
 // Add/remove operation-family transaction shapes stay parallel until SDK graduation.
 import { useCallback } from "react";
@@ -139,10 +140,14 @@ export function useGsapKeyframeOps({
                 coalesceKey: `gsap:${animationId}:kf:${percentage}`,
               },
             );
-            if (cutoverCommittedOrThrow(handled)) return;
+            if (cutoverCommittedOrThrow(handled)) {
+              if (handled.before !== handled.after) trackKeyframeUsage("add", property);
+              return;
+            }
           }
           await commitMutation(selection, mutation, {
             label: `Add keyframe at ${percentage}%`,
+            keyframeProperty: property,
             softReload: true,
           });
         },
@@ -172,7 +177,11 @@ export function useGsapKeyframeOps({
           sdkDeps,
           toSdkPersistOptions(`Add keyframe at ${percentage}%`, commitOverrides),
         );
-        if (cutoverCommittedOrThrow(handled)) return;
+        if (cutoverCommittedOrThrow(handled)) {
+          if (handled.before !== handled.after && commitOverrides?.keyframeTelemetry !== false)
+            trackKeyframeUsage("add");
+          return;
+        }
       }
       return commitMutation(
         selection,
@@ -319,7 +328,11 @@ export function useGsapKeyframeOps({
           sdkDeps,
           toSdkPersistOptions("Convert to keyframes", commitOverrides),
         );
-        if (cutoverCommittedOrThrow(handled)) return;
+        if (cutoverCommittedOrThrow(handled)) {
+          if (handled.before !== handled.after && commitOverrides.keyframeTelemetry !== false)
+            trackKeyframeUsage("convert");
+          return;
+        }
       }
       return commitMutation(
         selection,
@@ -333,11 +346,19 @@ export function useGsapKeyframeOps({
   );
 
   const removeAllKeyframes = useCallback(
-    async (selection: DomEditSelection, animationId: string) => {
+    async (
+      selection: DomEditSelection,
+      animationId: string,
+      action: "remove_all" | "reset" = "remove_all",
+      telemetry = true,
+    ): Promise<boolean> => {
       const targetPath = selection.sourceFile || activeCompPath || "index.html";
       // A class/descendant selector can resolve a live element whose selection
       // deliberately has no id. The cache is still keyed by that DOM id.
-      const cacheElementId = selection.id || selection.element?.id;
+      const clearCache = () => {
+        const cacheElementId = selection.id || selection.element?.id;
+        if (cacheElementId) clearKeyframeCacheForElement(targetPath, cacheElementId);
+      };
       if (sdkSession && sdkDeps) {
         const handled = await sdkGsapRemoveAllKeyframesPersist(
           targetPath,
@@ -347,26 +368,31 @@ export function useGsapKeyframeOps({
           { label: "Remove all keyframes" },
         );
         if (cutoverCommittedOrThrow(handled)) {
-          if (cacheElementId) clearKeyframeCacheForElement(targetPath, cacheElementId);
-          return;
+          clearCache();
+          const changed = handled.before !== handled.after;
+          if (changed && telemetry) trackKeyframeUsage(action);
+          return changed;
         }
       }
+      let changed = false;
       await commitMutationSafely(
         selection,
         { type: "remove-all-keyframes", animationId },
         {
           label: "Remove all keyframes",
+          keyframeAction: action,
+          keyframeTelemetry: telemetry,
           softReload: true,
           // The committed result is the single success boundary: clearing
           // before it makes failed saves lie, while waiting for the reload leaves
           // stale diamonds visible during the source round-trip.
           onResult: (result) => {
-            if (result.changed !== false && cacheElementId) {
-              clearKeyframeCacheForElement(targetPath, cacheElementId);
-            }
+            changed = result.ok && result.changed === true;
+            if (changed) clearCache();
           },
         },
       );
+      return changed;
     },
     [commitMutationSafely, activeCompPath, sdkSession, sdkDeps],
   );

package/src/hooks/useGsapScriptCommits.test.tsx

@@ -590,6 +590,63 @@ describe("runCommit — instantPatch wiring", () => {
     vi.unstubAllGlobals();
   });
 
+  it.each([
+    ["add-keyframe", "add"],
+    ["add-with-keyframes", "add"],
+    ["convert-to-keyframes", "convert"],
+    ["remove-all-keyframes", "remove_all"],
+  ])("counts %s only after a changed durable write", async (type, action) => {
+    mockFetchResult();
+    const deps = renderCommitHook();
+    await deps.api.commitMutation(
+      selection,
+      { type, properties: { text: "private-content" } },
+      { label: "Edit" },
+    );
+    expect(trackStudioEvent.mock.calls.filter(([event]) => event === "keyframe")).toEqual([
+      ["keyframe", { action }],
+    ]);
+  });
+
+  it("counts reset with its explicit action and suppresses intermediate writes", async () => {
+    mockFetchResult();
+    const deps = renderCommitHook();
+    await deps.api.commitMutation(
+      selection,
+      { type: "convert-to-keyframes" },
+      { label: "Convert", keyframeTelemetry: false },
+    );
+    await deps.api.commitMutation(
+      selection,
+      { type: "remove-all-keyframes" },
+      { label: "Reset", keyframeAction: "reset" },
+    );
+    expect(trackStudioEvent.mock.calls.filter(([event]) => event === "keyframe")).toEqual([
+      ["keyframe", { action: "reset" }],
+    ]);
+  });
+
+  it("does not count a successful unchanged keyframe write", async () => {
+    mockFetchResult({ changed: false });
+    const deps = renderCommitHook();
+    await deps.api.commitMutation(selection, { type: "add-keyframe" }, { label: "Add" });
+    expect(trackStudioEvent.mock.calls.filter(([event]) => event === "keyframe")).toEqual([]);
+  });
+
+  it("does not count a failed write that skipReload suppresses", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => ({ ok: false, status: 500 })),
+    );
+    const deps = renderCommitHook();
+    await deps.api.commitMutation(
+      selection,
+      { type: "add-keyframe" },
+      { label: "Add", skipReload: true },
+    );
+    expect(trackStudioEvent.mock.calls.filter(([event]) => event === "keyframe")).toEqual([]);
+  });
+
   const NESTED_SCRIPT = 'window.__timelines["root"] = tl;';
   const SUB = `<template><div data-composition-id="sub"><div id="nwid" style="left: 40px"></div></div></template>`;
 

package/src/hooks/useGsapScriptCommits.ts

@@ -11,6 +11,7 @@ import {
 } from "../utils/gsapSoftReload";
 import type { SoftReloadResult } from "../utils/gsapSoftReload";
 import { trackStudioEvent } from "../utils/studioTelemetry";
+import { trackKeyframeCommit } from "../utils/keyframeUsage";
 import { serializeStudioFileMutation } from "../utils/studioFileMutationCoordinator";
 import { trackedStudioEdit } from "../utils/studioPendingEdits";
 import {
@@ -391,6 +392,7 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
       mutateGsapScript(pid, targetPath, mutation),
     );
     if (!result) return;
+    trackKeyframeCommit([mutation], result, options);
     options.onResult?.(result);
     await finalizeSuccessfulMutation(pid, compositionPath, selection, mutation, targetPath, result, options);
   }, [showToast, finalizeSuccessfulMutation]);
@@ -404,6 +406,7 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
       mutateGsapScriptBatch(pid, targetPath, mutations),
     );
     if (!result) return;
+    trackKeyframeCommit(mutations, result, options, calls.map((call) => call.options));
     options.onResult?.(result);
     // Each call brings its own fast-path patch; the batch wrote them all, so the
     // preview sync applies them all rather than just the last call's.

package/src/hooks/useGsapSelectionHandlers.test.tsx

@@ -42,7 +42,7 @@ function makeParams(overrides: Partial<Params> = {}): Params {
     moveKeyframe: vi.fn().mockResolvedValue(true),
     resizeKeyframedTween: vi.fn().mockResolvedValue(true),
     convertToKeyframes: resolved(),
-    removeAllKeyframes: resolved(),
+    removeAllKeyframes: vi.fn().mockResolvedValue(true),
     handleDomManualEditsReset: vi.fn(),
     selectedGsapAnimations: [],
     showToast: vi.fn(),

package/src/hooks/useGsapSelectionHandlers.ts

@@ -109,9 +109,16 @@ export function useGsapSelectionHandlers({
     duration?: number,
     commitOverrides?: Partial<CommitMutationOptions>,
   ) => Promise<void>;
-  removeAllKeyframes: (sel: DomEditSelection, animId: string) => Promise<void>;
+  removeAllKeyframes: (
+    sel: DomEditSelection,
+    animId: string,
+    action?: "remove_all" | "reset",
+    telemetry?: boolean,
+  ) => Promise<boolean>;
 
-  handleDomManualEditsReset: (sel: DomEditSelection) => Promise<void>;
+  handleDomManualEditsReset: (
+    sel: DomEditSelection,
+  ) => Promise<void | import("./domEditCommitTypes").DomEditPersistOutcome>;
   selectedGsapAnimations: GsapAnimation[];
   showToast: (message: string, tone?: "error" | "info") => void;
 }) {
@@ -323,7 +330,6 @@ export function useGsapSelectionHandlers({
     ) => {
       const sel = resolveWriteSelection(selectionOverride);
       if (!sel) return;
-      trackStudioEvent("keyframe", { action: "add", property });
       addKeyframe(sel, animId, percentage, property, value);
     },
     [resolveWriteSelection, addKeyframe],
@@ -441,31 +447,31 @@ export function useGsapSelectionHandlers({
   );
 
   const handleGsapRemoveAllKeyframes = useCallback(
-    (animId: string, selectionOverride?: DomEditSelection | null) => {
+    (animId: string, selectionOverride?: DomEditSelection | null, telemetry = true) => {
       const selection = resolveWriteSelection(selectionOverride);
       if (!selection) return Promise.resolve(false);
-      return observeGsapMutation(
-        removeAllKeyframes(selection, animId),
-        selection,
-        "remove-all-keyframes",
-        "Remove all keyframes",
-      );
+      return removeAllKeyframes(selection, animId, "remove_all", telemetry).catch((error) => {
+        trackGsapHandlerFailure(error, selection, "remove-all-keyframes", "Remove all keyframes");
+        return false;
+      });
     },
-    [resolveWriteSelection, observeGsapMutation, removeAllKeyframes],
+    [resolveWriteSelection, trackGsapHandlerFailure, removeAllKeyframes],
   );
 
   const handleResetSelectedElementKeyframes = useCallback((): boolean => {
     if (!domEditSelection) return false;
     const withKeyframes = selectedGsapAnimations.find((a) => a.keyframes);
     if (!withKeyframes) return false;
-    observeGsapMutation(
-      removeAllKeyframes(domEditSelection, withKeyframes.id),
-      domEditSelection,
-      "remove-all-keyframes",
-      "Remove all keyframes",
-    );
+    void removeAllKeyframes(domEditSelection, withKeyframes.id, "reset").catch((error) => {
+      trackGsapHandlerFailure(
+        error,
+        domEditSelection,
+        "remove-all-keyframes",
+        "Remove all keyframes",
+      );
+    });
     return true;
-  }, [domEditSelection, observeGsapMutation, removeAllKeyframes, selectedGsapAnimations]);
+  }, [domEditSelection, trackGsapHandlerFailure, removeAllKeyframes, selectedGsapAnimations]);
 
   return {
     handleGsapUpdateProperty,

package/src/hooks/useGsapTweenCache.ts

@@ -290,17 +290,15 @@ export function usePopulateKeyframeCacheForFile(
   const domClipChildrenKey = usePlayerStore((s) =>
     s.domClipChildren.map((c) => `${c.id}<${c.hostId}`).join("|"),
   );
-  const lastFetchKeyRef = useRef("");
+  const loadedRef = useRef<{ dataKey: string; files: Set<string> }>({
+    dataKey: "",
+    files: new Set(),
+  });
 
   const runtimeScanDoneRef = useRef("");
-  const astFetchDoneRef = useRef("");
 
   useEffect(() => {
-    const fetchKey = `kf-cache:${projectId}:${sourceFile}:${version}:${elementCount}:${domClipChildrenKey}:${compositionSrcKey}`;
-    if (fetchKey === lastFetchKeyRef.current) return;
-    lastFetchKeyRef.current = fetchKey;
-    runtimeScanDoneRef.current = "";
-    astFetchDoneRef.current = "";
+    const dataKey = `kf-cache:${projectId}:${version}:${elementCount}:${domClipChildrenKey}:${compositionSrcKey}`;
     if (!projectId) return;
 
     // The active file first: it owns the selection, and each file clears only
@@ -309,13 +307,21 @@ export function usePopulateKeyframeCacheForFile(
     const files = Array.from(
       new Set([sourceFile, ...(compositionSrcKey ? compositionSrcKey.split("|") : [])]),
     );
-    const doc = iframeRef?.current?.contentDocument;
+    const sameData = loadedRef.current.dataKey === dataKey;
+    const stale = sameData ? files.filter((sf) => !loadedRef.current.files.has(sf)) : files;
+    const covered = sameData ? new Set([...loadedRef.current.files, ...files]) : new Set(files);
+    loadedRef.current = { dataKey, files: covered };
     // Everything the previous scan cached for a file this one no longer covers
     // (the composition just switched away from) has no owner left to clear it.
-    pruneKeyframeCacheToFiles(files);
-    Promise.all(files.map((sf) => populateKeyframeCacheFromAst(projectId, sf, doc))).then(() => {
-      astFetchDoneRef.current = fetchKey;
-    });
+    if (!sameData) pruneKeyframeCacheToFiles(files);
+    if (stale.length === 0) return;
+    runtimeScanDoneRef.current = "";
+    const doc = iframeRef?.current?.contentDocument;
+    for (const sf of stale) {
+      void populateKeyframeCacheFromAst(projectId, sf, doc).then((loaded) => {
+        if (!loaded && loadedRef.current.dataKey === dataKey) loadedRef.current.files.delete(sf);
+      });
+    }
     // elementCount is in the deps because new timeline elements (e.g. after a
     // sub-composition expand) need their keyframe cache populated immediately;
     // without it the effect won't re-run when elements appear/disappear.

package/src/hooks/usePopulateKeyframeCacheForFile.test.tsx

@@ -8,8 +8,8 @@ import { usePlayerStore } from "../player/store/playerStore";
 
 Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
 
-function HookHost() {
-  usePopulateKeyframeCacheForFile("demo", "index.html", 1);
+function HookHost({ sourceFile = "index.html", version = 1 }) {
+  usePopulateKeyframeCacheForFile("demo", sourceFile, version);
   return null;
 }
 
@@ -67,4 +67,78 @@ describe("usePopulateKeyframeCacheForFile", () => {
     expect(urls.some((u) => u.endsWith("/index.html"))).toBe(true);
     expect(urls.some((u) => u.includes("keyframe-lab.html"))).toBe(true);
   });
+
+  it("keeps every covered file when the selection switches between them, and refetches all on new data", async () => {
+    // Every click on a clip from another file flips `sourceFile`; a flip must not
+    // re-read every composition file, or a multi-select pays files x clicks fetches.
+    const urls: string[] = [];
+    vi.stubGlobal(
+      "fetch",
+      vi.fn((input: RequestInfo | URL) => {
+        urls.push(String(input));
+        return Promise.resolve({ ok: true, json: () => Promise.resolve({ animations: [] }) });
+      }),
+    );
+    const render = async (props: { sourceFile: string; version: number }) => {
+      await act(async () => {
+        if (!root) {
+          container = document.createElement("div");
+          document.body.appendChild(container);
+          root = createRoot(container);
+        }
+        root.render(<HookHost {...props} />);
+      });
+      await act(async () => {
+        await Promise.resolve();
+      });
+    };
+
+    await render({ sourceFile: "index.html", version: 1 });
+    const loaded = urls.length;
+    await render({ sourceFile: "compositions/keyframe-lab.html", version: 1 });
+    expect(urls.length).toBe(loaded);
+    await render({ sourceFile: "index.html", version: 1 });
+    expect(urls.length).toBe(loaded);
+
+    await render({ sourceFile: "index.html", version: 2 });
+    expect(urls.length).toBe(loaded * 2);
+  });
+
+  it("asks again for a covered file whose first read failed", async () => {
+    const urls: string[] = [];
+    vi.stubGlobal(
+      "fetch",
+      vi.fn((input: RequestInfo | URL) => {
+        const url = String(input);
+        urls.push(url);
+        const failed =
+          url.includes("keyframe-lab.html") && urls.filter((u) => u === url).length === 1;
+        return Promise.resolve({
+          ok: !failed,
+          json: () => Promise.resolve({ animations: [] }),
+        });
+      }),
+    );
+    const render = async (sourceFile: string) => {
+      await act(async () => {
+        if (!root) {
+          container = document.createElement("div");
+          document.body.appendChild(container);
+          root = createRoot(container);
+        }
+        root.render(<HookHost sourceFile={sourceFile} />);
+      });
+      await act(async () => {
+        await Promise.resolve();
+      });
+    };
+
+    await render("index.html");
+    const labReads = () => urls.filter((u) => u.includes("keyframe-lab.html")).length;
+    expect(labReads()).toBe(1);
+    await render("compositions/keyframe-lab.html");
+    expect(labReads()).toBe(2);
+    await render("index.html");
+    expect(labReads()).toBe(2);
+  });
 });

package/src/hooks/usePreviewInteraction.test.ts

@@ -299,3 +299,24 @@ describe("a refused move's toast", () => {
     ]);
   });
 });
+
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+import { trackStudioEvent } from "../utils/studioTelemetry";
+it("counts additive preview selection only after resolving a hit", async () => {
+  vi.mocked(trackStudioEvent).mockClear();
+  const selection = makeSelection("Card", document.createElement("div"));
+  const applyDomSelection = vi.fn();
+  const { canvas, cleanup } = renderHarness({
+    previewIframe: createPreviewIframe(vi.fn()),
+    resolveDomSelectionFromPreviewPoint: vi.fn(async () => selection),
+    applyDomSelection,
+  });
+  await dispatchMouseDown(canvas, { shiftKey: true });
+  expect(applyDomSelection).toHaveBeenCalledWith(selection, { additive: true });
+  expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("feature_used", {
+    feature: "multi_select",
+    surface: "preview",
+    method: "button",
+  });
+  cleanup();
+});

package/src/hooks/usePreviewInteraction.ts

@@ -1,3 +1,4 @@
+import { trackPreviewFeatureUsed } from "../utils/previewFeatureUsage";
 import { useCallback, useRef } from "react";
 import { liveTime, usePlayerStore } from "../player";
 import { pauseStudioPreviewPlayback } from "../utils/studioPreviewHelpers";
@@ -169,6 +170,7 @@ export function usePreviewInteraction({
         e.preventDefault();
         e.stopPropagation();
         applyDomSelection(nextSelection, { additive: true });
+        trackPreviewFeatureUsed("multi_select", "button");
         return;
       }
 

package/src/hooks/useRenderClipContent.test.ts

@@ -6,6 +6,7 @@ import { afterEach, describe, expect, it } from "vitest";
 import { CompositionThumbnail, VideoThumbnail } from "../player";
 import { AudioWaveform } from "../player/components/AudioWaveform";
 import { AudibleVideoClipContent } from "../player/components/AudibleVideoClipContent";
+import { TextClipContent } from "../player/components/TextClipContent";
 import { ClipPeakMarks } from "../player/components/ClipPeakMarks";
 
 function unwrapPeakMarks(node: ReactNode): ReactNode {
@@ -280,6 +281,23 @@ describe("useRenderClipContent", () => {
     expect(isValidElement(content) && content.type).toBe(AudibleVideoClipContent);
   });
 
+  it("gives a layer spanning the whole film its own frame, whatever its id", () => {
+    usePlayerStore.setState({ thumbnailMode: "adaptive" });
+    for (const id of ["waves", "background-glyphs"]) {
+      const content = renderClipContent({ id, tag: "div", start: 0, duration: 12, track: 0 }, null);
+      expect(isValidElement(content) && content.type).toBe(CompositionThumbnail);
+    }
+  });
+
+  it("draws a text layer's own words instead of capturing them", () => {
+    usePlayerStore.setState({ thumbnailMode: "adaptive" });
+    const content = renderClipContent(
+      { id: "title", tag: "h1", start: 0, duration: 12, track: 0, text: { value: "Ship it" } },
+      null,
+    );
+    expect(isValidElement(content) && content.type).toBe(TextClipContent);
+  });
+
   it("passes empty labels to thumbnail content so TimelineClip owns clip names", () => {
     usePlayerStore.setState({ thumbnailMode: "adaptive" });
 

package/src/hooks/useRenderClipContent.ts

@@ -12,6 +12,7 @@ import type { TimelineClipRenderContext } from "../player/components/TimelineTyp
 import { audioPillFlags } from "../player/components/audioClipLink";
 import { AudioWaveform, rendersWaveform } from "../player/components/AudioWaveform";
 import { ImageThumbnail } from "../player/components/ImageThumbnail";
+import { TextClipContent } from "../player/components/TextClipContent";
 import { AudibleVideoClipContent } from "../player/components/AudibleVideoClipContent";
 import { ClipPeakMarks } from "../player/components/ClipPeakMarks";
 import { clipPeaksUrl, clipSourceWindow } from "../player/components/clipPeakMap";
@@ -184,6 +185,8 @@ export function useRenderClipContent({
         return renderAudioClip(el, pid, sessionEpoch, style.label, context, elements);
       }
 
+      if (el.text) return createElement(TextClipContent, { text: el.text });
+
       // When drilled into a composition, render all inner elements via
       // CompositionThumbnail at their start time — most accurate visual.
       if (activePreviewUrl && el.duration > 0) {
@@ -207,11 +210,7 @@ export function useRenderClipContent({
         });
       }
 
-      const htmlPreviewEligible =
-        el.duration > 0 &&
-        effectiveTimelineDuration > 0 &&
-        el.duration < effectiveTimelineDuration * 0.92 &&
-        !/(backdrop|background|overlay|scrim|mask)/i.test(el.id);
+      const htmlPreviewEligible = el.duration > 0 && effectiveTimelineDuration > 0;
 
       if ((el.tag === "video" || el.tag === "img") && el.src) {
         const mediaSrc = resolveMediaPreviewUrl(el.src, pid, window.location.origin);