@hyperframes/studio 0.8.114 → 0.8.115

package/src/player/components/timelineCallbacks.ts

@@ -137,6 +137,7 @@ export interface TimelineEditCallbacks {
   onRazorSplit?: (element: TimelineElement, splitTime: number) => Promise<void> | void;
   onRazorSplitAll?: (splitTime: number) => Promise<void> | void;
   onFreezeFrame?: (element: TimelineElement, time: number) => Promise<void> | void;
+  clipMenuTools?: boolean;
   onNotice?: (message: string, tone?: "error" | "info") => void;
   onDeleteKeyframe?: (elementId: string, keyframe: TimelineKeyframeTarget) => void;
   onDeleteAllKeyframes?: (element: TimelineElement, animationId?: string) => void;

package/src/player/components/timelineClipDragGestureLifecycle.ts

@@ -195,7 +195,7 @@ export function mountTimelineClipDragGestureLifecycle({
       event.clientX - blocked.originClientX,
       event.clientY - blocked.originClientY,
     );
-    const threshold = blocked.intent === "move" ? 4 : 2;
+    const threshold = blocked.intent === "move" || blocked.intent === "edit-many" ? 4 : 2;
     if (!blocked.started && distance < threshold) return;
     if (!blocked.started) {
       blocked.started = true;

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

@@ -0,0 +1,94 @@
+// @vitest-environment happy-dom
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { PointerEvent as ReactPointerEvent } from "react";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { createClipGestureHandlers, type ClipGestureDeps } from "./timelineClipGestureHandlers";
+import { MAX_HAND_EDIT_CLIPS } from "./timelineEditing";
+
+afterEach(() => usePlayerStore.getState().reset());
+
+const clips: TimelineElement[] = Array.from({ length: 6 }, (_, i) => ({
+  id: `clip-${i}`,
+  domId: `clip-${i}`,
+  tag: "div",
+  start: i,
+  duration: 1,
+  track: i,
+}));
+const capabilities = { canMove: true, canTrimStart: true, canTrimEnd: true, readOnly: false };
+
+function grabFirstClip(count: number, gesture: "move" | "resize", locked: number[] = []) {
+  const store = usePlayerStore.getState();
+  store.setElements(
+    clips.map((clip, i) => (locked.includes(i) ? { ...clip, timelineLocked: true } : clip)),
+  );
+  store.setSelectedElementIds(new Set(clips.slice(0, count).map((c) => c.id)));
+  const setDraggedClip = vi.fn();
+  const setResizingClip = vi.fn();
+  const blockedClipRef = { current: null as { intent: string } | null };
+  const deps = {
+    pps: 100,
+    onMoveElement: vi.fn(),
+    onResizeElement: vi.fn(),
+    blockedClipRef,
+    suppressClickRef: { current: false },
+    scrollRef: { current: null },
+    setShowPopover: vi.fn(),
+    setRangeSelection: vi.fn(),
+    setResizingClip,
+    setDraggedClip,
+    setSelectedElementId: vi.fn(),
+  } as unknown as ClipGestureDeps;
+  const handlers = createClipGestureHandlers(clips[0], clips[0].id, clips[0], capabilities, deps);
+  const event = {
+    button: 0,
+    clientX: 50,
+    clientY: 5,
+    pointerId: 1,
+    stopPropagation: vi.fn(),
+    currentTarget: { getBoundingClientRect: () => ({ left: 0, width: 100 }) },
+  } as unknown as ReactPointerEvent;
+  if (gesture === "move") handlers.onPointerDown(event);
+  else handlers.onResizeStart("end", event);
+  return { setDraggedClip, setResizingClip, blockedClipRef };
+}
+
+describe("hand-editing a multi-selection", () => {
+  it("moves up to the limit by hand", () => {
+    const { setDraggedClip, blockedClipRef } = grabFirstClip(MAX_HAND_EDIT_CLIPS, "move");
+    expect(setDraggedClip).toHaveBeenCalledOnce();
+    expect(blockedClipRef.current).toBeNull();
+  });
+
+  it("refuses to start a drag above the limit and asks for the toast", () => {
+    const { setDraggedClip, blockedClipRef } = grabFirstClip(MAX_HAND_EDIT_CLIPS + 1, "move");
+    expect(setDraggedClip).not.toHaveBeenCalled();
+    expect(blockedClipRef.current?.intent).toBe("edit-many");
+  });
+
+  it("resizes up to the limit by hand", () => {
+    const { setResizingClip, blockedClipRef } = grabFirstClip(MAX_HAND_EDIT_CLIPS, "resize");
+    expect(setResizingClip).toHaveBeenCalledOnce();
+    expect(blockedClipRef.current).toBeNull();
+  });
+
+  it("refuses to start a resize above the limit and asks for the toast", () => {
+    const { setResizingClip, blockedClipRef } = grabFirstClip(MAX_HAND_EDIT_CLIPS + 1, "resize");
+    expect(setResizingClip).not.toHaveBeenCalled();
+    expect(blockedClipRef.current?.intent).toBe("edit-many");
+  });
+
+  it("counts the clips a move would change: locked ones in the selection stay put", () => {
+    const allowed = grabFirstClip(MAX_HAND_EDIT_CLIPS + 2, "move", [3, 4]);
+    expect(allowed.setDraggedClip).toHaveBeenCalledOnce();
+    const refused = grabFirstClip(MAX_HAND_EDIT_CLIPS + 2, "move", [4]);
+    expect(refused.setDraggedClip).not.toHaveBeenCalled();
+  });
+
+  it("counts the clips a trim would change: a locked member leaves a trim of the grabbed clip alone", () => {
+    const allowed = grabFirstClip(MAX_HAND_EDIT_CLIPS + 1, "resize", [3]);
+    expect(allowed.setResizingClip).toHaveBeenCalledOnce();
+    expect(allowed.blockedClipRef.current).toBeNull();
+  });
+});

package/src/player/components/timelineClipGestureHandlers.ts

@@ -8,7 +8,11 @@ import {
 import type { TimelineEditCapabilities } from "./timelineEditCapabilities";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
 import { CLIP_HANDLE_W } from "./timelineLayout";
-import { selectClipWithLinks, toggleClipWithLinks } from "./timelineLinkSelection";
+import {
+  exceedsHandEditLimit,
+  selectClipWithLinks,
+  toggleClipWithLinks,
+} from "./timelineLinkSelection";
 import { SPLIT_BOUNDARY_EPSILON_S } from "../../utils/timelineElementSplit";
 
 export interface ClipGestureDeps {
@@ -73,6 +77,7 @@ function isIntentBlocked(
  */
 function resolvePointerDownAction(
   e: ReactPointerEvent,
+  grabbed: TimelineElement,
   capabilities: TimelineEditCapabilities,
   onResizeElement: ClipGestureDeps["onResizeElement"],
   onMoveElement: ClipGestureDeps["onMoveElement"],
@@ -93,6 +98,8 @@ function resolvePointerDownAction(
   }
 
   if (!onMoveElement || !capabilities.canMove) return { kind: "ignore" };
+  if (exceedsHandEditLimit(grabbed, e.altKey, null))
+    return { kind: "block", intent: "edit-many", rect };
   return { kind: "move", rect };
 }
 
@@ -129,6 +136,17 @@ export function createClipGestureHandlers(
   const onResizeStart = (edge: "start" | "end", e: ReactPointerEvent): void => {
     if (!canStartResize(edge, e, capabilities, onResizeElement)) return;
     e.stopPropagation();
+    if (exceedsHandEditLimit(el, e.altKey, edge)) {
+      blockedClipRef.current = {
+        pointerId: e.pointerId,
+        element: el,
+        intent: "edit-many",
+        originClientX: e.clientX,
+        originClientY: e.clientY,
+        started: false,
+      };
+      return;
+    }
     blockedClipRef.current = null;
     setShowPopover(false);
     setRangeSelection(null);
@@ -147,7 +165,7 @@ export function createClipGestureHandlers(
   };
 
   const onPointerDown = (e: ReactPointerEvent): void => {
-    const action = resolvePointerDownAction(e, capabilities, onResizeElement, onMoveElement);
+    const action = resolvePointerDownAction(e, el, capabilities, onResizeElement, onMoveElement);
     if (action.kind === "ignore") return;
 
     if (action.kind === "block") {

package/src/player/components/timelineEditing.ts

@@ -248,7 +248,9 @@ export interface TimelinePromptElement {
   track: number;
 }
 
-export type BlockedTimelineEditIntent = "move" | "resize-start" | "resize-end";
+export type BlockedTimelineEditIntent = "move" | "edit-many" | "resize-start" | "resize-end";
+
+export const MAX_HAND_EDIT_CLIPS = 3;
 
 export interface TimelineRangeSelection {
   start: number;

package/src/player/components/timelineLinkSelection.ts

@@ -1,5 +1,13 @@
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
-import { expandToLinkedMembers, linkedMembersOf } from "./audioClipLink";
+import {
+  dropMisalignedTrimPartners,
+  expandToLinkedMembers,
+  linkedGestureKeys,
+  linkedMembersOf,
+} from "./audioClipLink";
+import { buildTimelineGroupResizeMembers } from "./timelineGroupEditing";
+import { resolveGroupMovers } from "./timelineMultiDragPreview";
+import { MAX_HAND_EDIT_CLIPS } from "./timelineEditing";
 import { isLinkedSelectionOn } from "../../utils/linkedClipPreferences";
 
 /**
@@ -39,3 +47,29 @@ export function toggleClipWithLinks(key: string, altKey: boolean): TimelineEleme
   const primary = usePlayerStore.getState().selectedElementId;
   return state.elements.find((el) => (el.key ?? el.id) === primary) ?? null;
 }
+
+/** Whether a hand drag on `grabbed` (trimming `edge`, or null to move) would change more clips than allowed. */
+export function exceedsHandEditLimit(
+  grabbed: TimelineElement,
+  altKey: boolean,
+  edge: "start" | "end" | null,
+): boolean {
+  const { selectedElementIds, elements } = usePlayerStore.getState();
+  const grabbedKey = grabbed.key ?? grabbed.id;
+  const keys = linkedGestureKeys(
+    selectedElementIds,
+    grabbed,
+    elements,
+    altKey,
+    isLinkedSelectionOn(),
+  );
+  const changed = edge
+    ? buildTimelineGroupResizeMembers(
+        elements,
+        dropMisalignedTrimPartners(keys, grabbed, elements, edge),
+        grabbedKey,
+        edge,
+      )
+    : resolveGroupMovers(elements, keys, grabbedKey);
+  return (changed?.length ?? 1) > MAX_HAND_EDIT_CLIPS;
+}

package/src/player/components/useTimelineClipDrag.keyboard.test.tsx

@@ -49,6 +49,7 @@ function mount(order = [0, 1, 2]) {
   const host = document.createElement("div");
   const root = createRoot(host);
   const onMoveElements = vi.fn();
+  const onBlockedEditAttempt = vi.fn();
   const trackOrderRef = { current: order };
   const trackInsertLayoutRef = { current: buildTimelineTrackInsertLayout(order, groups) };
   let state: ReturnType<typeof useTimelineClipDrag>;
@@ -68,6 +69,7 @@ function mount(order = [0, 1, 2]) {
       },
       onMoveElement: vi.fn(),
       onMoveElements,
+      onBlockedEditAttempt,
       setShowPopover: () => {},
       setRangeSelectionRef: { current: null },
     });
@@ -83,6 +85,7 @@ function mount(order = [0, 1, 2]) {
     key,
     clip,
     onMoveElements,
+    onBlockedEditAttempt,
     root,
     elements,
     changeOrder(next: number[]) {
@@ -161,3 +164,14 @@ it("leaves Space on a nested fade slider to the slider", () => {
   expect(event.defaultPrevented).toBe(false);
   act(() => view.root.unmount());
 });
+
+it("does not pick up a clip held in a selection above the hand-move limit", () => {
+  const view = mount();
+  usePlayerStore.getState().setSelection(["top", "hero", "tail", "bottom"], "hero");
+  view.key(" ");
+  expect(view.drag).toBeNull();
+  expect(view.onBlockedEditAttempt).toHaveBeenCalledWith(
+    expect.objectContaining({ id: "hero" }),
+    "edit-many",
+  );
+});

package/src/player/components/useTimelineClipDrag.ts

@@ -29,6 +29,7 @@ import type {
 } from "./timelineClipDragTypes";
 import { getTimelineElementIndexes } from "../lib/timelineElementIndexes";
 import { dropMisalignedTrimPartners, linkedGestureKeys } from "./audioClipLink";
+import { exceedsHandEditLimit } from "./timelineLinkSelection";
 import { isLinkedSelectionOn } from "../../utils/linkedClipPreferences";
 import { useTimelineClipCapabilities } from "./timelineReadOnly";
 import { timelineClipFocusId } from "./timelineNavigationIdentity";
@@ -158,11 +159,8 @@ export function useTimelineClipDrag({
   const elementsRef = useRef(elements);
   elementsRef.current = elements;
 
-  // Perf (frozen-per-gesture): the snap-target set and the audio-track set are
-  // fixed for the duration of one drag/resize (the store is not re-authored mid
-  // gesture), so build each ONCE and reuse it across every pointermove and every
-  // auto-scroll frame. Both caches are cleared at gesture teardown
-  // (stopClipDragAutoScroll), so the next gesture rebuilds against fresh state.
+  // The snap-target and audio-track sets are fixed for one drag/resize (the store is not
+  // re-authored mid gesture): built once, reused per pointermove, cleared at teardown.
   const snapTargetsCacheRef = useRef<Map<string, TimelineSnapTarget[]>>(new Map());
   const dragAudioTracksRef = useRef<ReadonlySet<number> | null>(null);
 
@@ -272,8 +270,7 @@ export function useTimelineClipDrag({
   const blockedClipRef = useRef<BlockedClipState | null>(null);
   const suppressClickRef = useRef(false);
 
-  // Active multi-select group-resize session, created lazily on first movement.
-  // It owns a projection only; canonical store timing changes at commit.
+  // Group-resize session, created on first movement; a projection only, committed at the end.
   const groupResizeRef = useRef<TimelineGroupResizeSession | null>(null);
 
   const onMoveElementRef = useRef(onMoveElement);
@@ -541,6 +538,8 @@ export function useTimelineClipDrag({
       if (!element || !getClipCapabilities(element).canMove) return;
       event.preventDefault();
       event.stopImmediatePropagation();
+      if (exceedsHandEditLimit(element, false, null))
+        return void onBlockedEditAttemptRef.current?.(element, "edit-many");
       setShowPopover(false);
       setRangeSelectionRef.current?.(null);
       const row = keyboardPickupInsertRow(

package/src/player/hooks/timelinePlayerSync.test.ts

@@ -31,4 +31,10 @@ describe("timelineElementsChanged", () => {
     expect(timelineElementsChanged([grouped], [clip])).toBe(true);
     expect(timelineElementsChanged([grouped], [{ ...grouped }])).toBe(false);
   });
+
+  it("sees a change to a text row's words, but not an identical re-read", () => {
+    const row = { id: "t", tag: "h1", start: 0, duration: 2, track: 0, text: { value: "Old" } };
+    expect(timelineElementsChanged([row], [{ ...row, text: { value: "Old" } }])).toBe(false);
+    expect(timelineElementsChanged([row], [{ ...row, text: { value: "New" } }])).toBe(true);
+  });
 });

package/src/player/hooks/timelinePlayerSync.ts

@@ -1,4 +1,5 @@
 import type { TimelineElement } from "../store/playerStore";
+import { sameTimelineText } from "../lib/timelineText";
 
 const RENDERED_FIELDS: readonly (keyof TimelineElement)[] = [
   "id",
@@ -28,6 +29,10 @@ export function timelineElementsChanged(
   if (next.length !== previous.length) return true;
   return next.some((element, index) => {
     const prior = previous[index];
-    return !prior || RENDERED_FIELDS.some((key) => element[key] !== prior[key]);
+    return (
+      !prior ||
+      RENDERED_FIELDS.some((key) => element[key] !== prior[key]) ||
+      !sameTimelineText(element.text, prior.text)
+    );
   });
 }

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

@@ -1,5 +1,13 @@
+// @vitest-environment happy-dom
 import { describe, expect, it } from "vitest";
-import { isVideoAudible } from "./timelineElementHelpers";
+import type { TimelineElement } from "../store/playerStore";
+import {
+  applyMediaMetadataFromElement,
+  getTimelineElementSelector,
+  isVideoAudible,
+  resolveMediaElement,
+} from "./timelineElementHelpers";
+import { readTimelineText, sameTimelineText } from "./timelineText";
 
 describe("isVideoAudible — the compiler's data-has-audio rule", () => {
   it("explicit data-has-audio wins", () => {
@@ -14,3 +22,81 @@ describe("isVideoAudible — the compiler's data-has-audio rule", () => {
     expect(isVideoAudible({ tag: "img", hasAudioAttr: null, muted: false })).toBe(false);
   });
 });
+
+describe("preview nodes built in another realm", () => {
+  // The Studio preview's body carries the editor window's prototypes, so its
+  // nodes fail `instanceof` against their own window's HTMLElement.
+  function foreignNode(html: string): Element {
+    const holder = document.createElement("div");
+    holder.innerHTML = html;
+    const node = holder.firstElementChild!;
+    document.body.appendChild(node);
+    Object.setPrototypeOf(node, Object.create(Element.prototype));
+    expect(node instanceof HTMLElement).toBe(false);
+    return node;
+  }
+
+  it("gives a row with an id its id selector", () => {
+    const el = foreignNode(`<div id="layer-00" class="clip layer"></div>`);
+    expect(getTimelineElementSelector(el)).toBe("#layer-00");
+  });
+
+  it("reads media metadata off a foreign <video>", () => {
+    const el = foreignNode(`<video src="a.mp4" data-source-duration="12"></video>`);
+    expect(resolveMediaElement(el)).toBe(el);
+    const entry = { id: "v", tag: "div", start: 0, duration: 4, track: 0 } as TimelineElement;
+    applyMediaMetadataFromElement(entry, el);
+    expect(entry.sourceDuration).toBe(12);
+  });
+});
+
+describe("readTimelineText", () => {
+  function layer(html: string): Element {
+    document.body.innerHTML = html;
+    return document.body.firstElementChild!;
+  }
+
+  it("reads a text layer's words, collapsed to one line, with its font and colour", () => {
+    const text = readTimelineText(
+      layer(`<h1 style="font-family: Georgia; font-weight: 700; color: rgb(255, 0, 0)">
+        Ship <span>it</span>
+      </h1>`),
+    );
+    expect(text).toMatchObject({ value: "Ship it", fontWeight: "700", color: "rgb(255, 0, 0)" });
+    expect(text?.fontFamily).toContain("Georgia");
+  });
+
+  it("leaves a layer that holds anything but text, or no words, to its picture", () => {
+    expect(
+      readTimelineText(layer(`<div><div>Title</div><div><i></i></div></div>`)),
+    ).toBeUndefined();
+    expect(readTimelineText(layer(`<div class="glyph"></div>`))).toBeUndefined();
+    expect(readTimelineText(layer(`<section>Words</section>`))).toBeUndefined();
+  });
+
+  it("keeps a layer that paints an image as a picture, and carries a flat background colour", () => {
+    expect(
+      readTimelineText(
+        layer(`<div style="background-image: linear-gradient(red, blue)">L01</div>`),
+      ),
+    ).toBeUndefined();
+    expect(
+      readTimelineText(layer(`<div style="background-color: rgb(230, 57, 70)">Go</div>`)),
+    ).toMatchObject({
+      value: "Go",
+      background: "rgb(230, 57, 70)",
+    });
+    expect(readTimelineText(layer(`<div>Go</div>`))?.background).toBeUndefined();
+    expect(
+      readTimelineText(layer(`<div style="background-color: rgba(255, 255, 255, 0.01)">Go</div>`))
+        ?.background,
+    ).toBeUndefined();
+  });
+
+  it("tells a text change apart from an identical re-read", () => {
+    const text = { value: "Old", color: "rgb(0, 0, 0)" };
+    expect(sameTimelineText(text, { ...text })).toBe(true);
+    expect(sameTimelineText(text, { ...text, value: "New" })).toBe(false);
+    expect(sameTimelineText(text, undefined)).toBe(false);
+  });
+});

package/src/player/lib/timelineElementHelpers.ts

@@ -8,11 +8,13 @@
  */
 
 import type { TimelineElement } from "../store/playerStore";
+import { readTimelineText } from "./timelineText";
 import type { ClipManifestClip } from "./playbackTypes";
 import { isFinitePositive } from "./playbackAdapter";
 import { getSourceScopedSelectorIndex } from "../../utils/sourceScopedSelectorIndex";
 import { HF_AUDIO_GROUP_TAG } from "@hyperframes/core/audio-groups";
 import { readElementFades } from "@hyperframes/core/audio-fade";
+import { isHtmlElement, isImageElement, isMediaElement } from "@hyperframes/core/runtime/dom-realm";
 import { elementVolume } from "./storedVolume";
 import {
   type AttrReader,
@@ -143,11 +145,6 @@ export function furthestClipEndFromSource(source: string): number {
 // DOM element type guards
 // ---------------------------------------------------------------------------
 
-function isHtmlElement(el: Element): el is HTMLElement {
-  const HtmlElementCtor = el.ownerDocument.defaultView?.HTMLElement ?? globalThis.HTMLElement;
-  return typeof HtmlElementCtor !== "undefined" && el instanceof HtmlElementCtor;
-}
-
 function isCompositionHost(el: Element): boolean {
   return (
     el.hasAttribute("data-composition-id") ||
@@ -157,16 +154,11 @@ function isCompositionHost(el: Element): boolean {
 }
 
 export function resolveMediaElement(el: Element): HTMLMediaElement | HTMLImageElement | null {
-  const win = el.ownerDocument.defaultView ?? window;
-  const MediaElementCtor = win.HTMLMediaElement ?? globalThis.HTMLMediaElement;
-  const ImageElementCtor = win.HTMLImageElement ?? globalThis.HTMLImageElement;
-  if (el instanceof MediaElementCtor || el instanceof ImageElementCtor) return el;
+  if (isMediaElement(el) || isImageElement(el)) return el;
   // A composition's media belongs to its own timeline, not the clip's: its length would cap a trim.
   if (isCompositionHost(el)) return null;
   const candidate = el.querySelector("video, audio, img");
-  return candidate instanceof MediaElementCtor || candidate instanceof ImageElementCtor
-    ? candidate
-    : null;
+  return isMediaElement(candidate) || isImageElement(candidate) ? candidate : null;
 }
 
 /** The in-point as playback reads it, and the attribute holding it; empty when neither is authored. */
@@ -255,6 +247,7 @@ function applyFadeMetadataFromElement(entry: TimelineElement, el: Element): void
 }
 
 export function applyMediaMetadataFromElement(entry: TimelineElement, el: Element): void {
+  setOptional(entry, "text", readTimelineText(el));
   applyPlaybackMetadataFromElement(entry, el);
   applyAudioMetadataFromElement(entry, el);
   applyFadeMetadataFromElement(entry, el);
@@ -266,9 +259,7 @@ export function applyMediaMetadataFromElement(entry: TimelineElement, el: Elemen
   const src = mediaEl.getAttribute("src");
   if (src) entry.src = src;
 
-  const win = mediaEl.ownerDocument.defaultView ?? window;
-  const MediaElementCtor = win.HTMLMediaElement ?? globalThis.HTMLMediaElement;
-  if (typeof MediaElementCtor === "undefined" || !(mediaEl instanceof MediaElementCtor)) return;
+  if (!isMediaElement(mediaEl)) return;
 
   const sourceDurationAttr =
     el.getAttribute("data-source-duration") ?? mediaEl.getAttribute("data-source-duration");

package/src/player/lib/timelineText.ts

@@ -0,0 +1,40 @@
+import { isHtmlElement } from "@hyperframes/core/runtime/dom-realm";
+import { parseCssColor } from "../../components/editor/colorValue";
+import type { TimelineText } from "../store/timelineElement";
+import {
+  getCuratedComputedStyles,
+  isEditableTextLeaf,
+  isTextBearingTag,
+} from "../../components/editor/domEditingDom";
+
+/** A layer that paints only text and a flat colour (a text tag whose children are all text leaves,
+ *  no background image): its words and look. Anything painted beyond that keeps its picture. */
+export function readTimelineText(el: Element): TimelineText | undefined {
+  if (!isHtmlElement(el) || !isTextBearingTag(el.localName)) return undefined;
+  const children = Array.from(el.children);
+  if (!children.every((child) => isHtmlElement(child) && isEditableTextLeaf(child)))
+    return undefined;
+  const value = el.textContent?.replace(/\s+/g, " ").trim();
+  if (!value) return undefined;
+  const style = getCuratedComputedStyles(el);
+  if ((style["background-image"] ?? "none") !== "none") return undefined;
+  const background = style["background-color"];
+  return {
+    value,
+    fontFamily: style["font-family"],
+    fontWeight: style["font-weight"],
+    color: style.color,
+    background: background && parseCssColor(background)?.alpha === 1 ? background : undefined,
+  };
+}
+
+export function sameTimelineText(a?: TimelineText, b?: TimelineText): boolean {
+  if (!a || !b) return a === b;
+  return (
+    a.value === b.value &&
+    a.fontFamily === b.fontFamily &&
+    a.fontWeight === b.fontWeight &&
+    a.color === b.color &&
+    a.background === b.background
+  );
+}

package/src/player/store/timelineElement.ts

@@ -95,6 +95,17 @@ export interface TimelineElement {
   authoredStartIsMasterTime?: boolean;
   /** Legacy marker for an inline sub-composition child; current rows never set it. */
   expandedHostKey?: string;
+  /** A text layer's words and look, which its row draws live instead of a captured picture. */
+  text?: TimelineText;
+}
+
+export interface TimelineText {
+  value: string;
+  fontFamily?: string;
+  fontWeight?: string;
+  color?: string;
+  /** The layer's own opaque background colour, when it paints one. */
+  background?: string;
 }
 
 type RowClock = Pick<
@@ -156,6 +167,7 @@ export type TimelineElementPatch = Partial<
     | "audioGroupHidden"
     | "audioGroupFxChain"
     | "audioGroupAutomation"
+    | "text"
   >
 >;
 

package/src/styles/theme.css

@@ -146,6 +146,9 @@
     transparent 100%
   );
   --timeline-thumbnail-label-shadow: 0 1px 2px rgba(0, 0, 0, 0.9);
+  /* A text clip's strip behind its live words: dark for light text, light for dark text. */
+  --timeline-text-clip-dark-bg: #1c2028;
+  --timeline-text-clip-light-bg: #e9e6df;
   --timeline-waveform-bar-rgb: 245, 237, 255;
   --timeline-waveform-muted-rgb: 236, 238, 242;
   --timeline-waveform-baseline-rgb: 226, 216, 238;

package/src/utils/keyframeUsage.ts

@@ -0,0 +1,79 @@
+import type { CommitMutationOptions, MutationResult } from "../hooks/gsapScriptCommitTypes";
+import { trackStudioEvent } from "./studioTelemetry";
+
+export type KeyframeUsageAction = "add" | "convert" | "remove_all" | "reset";
+
+export function keyframeUsageActions(
+  mutations: ReadonlyArray<Record<string, unknown>>,
+  semanticActions?: ReadonlyArray<KeyframeUsageAction | undefined>,
+): Set<KeyframeUsageAction> {
+  const actions = new Set<KeyframeUsageAction>();
+  for (const [index, mutation] of mutations.entries()) {
+    const semanticAction = semanticActions?.[index];
+    if (semanticAction) {
+      actions.add(semanticAction);
+      continue;
+    }
+    switch (mutation.type) {
+      case "add-keyframe":
+      case "add-with-keyframes":
+        actions.add("add");
+        break;
+      case "convert-to-keyframes":
+        actions.add("convert");
+        break;
+      case "remove-all-keyframes":
+        actions.add("remove_all");
+        break;
+    }
+  }
+  return actions;
+}
+
+export function trackKeyframeUsage(action: KeyframeUsageAction, property?: string): void {
+  trackStudioEvent("keyframe", property === undefined ? { action } : { action, property });
+}
+
+export function primaryKeyframeAction(
+  actions: ReadonlySet<KeyframeUsageAction>,
+): KeyframeUsageAction | undefined {
+  return (["add", "convert", "remove_all", "reset"] as const).find((action) => actions.has(action));
+}
+
+export function changedMutationIndices(
+  result: MutationResult,
+  count: number,
+  options?: ReadonlyArray<Pick<CommitMutationOptions, "keyframeTelemetry">>,
+): number[] {
+  if (!result.ok || result.changed !== true) return [];
+  const changes = count === 1 ? [true] : result.mutationChanges;
+  if (
+    !Array.isArray(changes) ||
+    changes.length !== count ||
+    changes.some((value) => typeof value !== "boolean")
+  )
+    return [];
+  return changes.flatMap((changed, index) =>
+    changed && options?.[index]?.keyframeTelemetry !== false ? [index] : [],
+  );
+}
+
+export function trackKeyframeCommit(
+  mutations: ReadonlyArray<Record<string, unknown>>,
+  result: MutationResult,
+  options: CommitMutationOptions,
+  memberOptions?: ReadonlyArray<CommitMutationOptions>,
+): void {
+  if (!result.ok || result.changed !== true || options.keyframeTelemetry === false) return;
+  const indices = changedMutationIndices(result, mutations.length, memberOptions);
+  const actions = keyframeUsageActions(
+    indices.map((index) => mutations[index]!),
+    indices.map(
+      (index) =>
+        memberOptions?.[index]?.keyframeAction ??
+        (mutations.length === 1 ? options.keyframeAction : undefined),
+    ),
+  );
+  const action = primaryKeyframeAction(actions);
+  if (action) trackKeyframeUsage(action, action === "add" ? options.keyframeProperty : undefined);
+}