@hyperframes/studio 0.8.114 → 0.8.116

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/hooks/useTimelinePlayer.ts

@@ -36,6 +36,7 @@ import { hasTimelinePerformanceFixtureLease } from "../lib/timelinePerformanceFi
 import { applyCachedSourceDurations, probeMissingSourceDurations } from "../lib/mediaProbe";
 import { shouldResumeForwardPlaybackAfterSeek, shouldStopAfterSeek } from "../lib/playbackSeek";
 import { applyPreviewVariablesToUrl } from "../../hooks/previewVariablesStore";
+import { isStudioManualEditGestureLiveIn } from "../../components/editor/manualEditsDom";
 import { createPreviewMessageHandler } from "./previewMessageRouter";
 import { timelineElementsChanged } from "./timelinePlayerSync";
 import { safeContentDocument } from "./timelineSyncHydration";
@@ -486,7 +487,10 @@ export function useTimelinePlayer({
     // A newer edit, or anything replacing the live preview (a reload, a composition switch), wins.
     const isCurrent = () => gen === refreshGenRef.current && slot === previewGeneration();
     const swap = sceneSwapFor(iframe);
-    if (!swap || isRefreshingRef.current) return reloadWholeFilm(url.toString());
+    const swapWouldReplaceGestureNode =
+      !!iframe.contentDocument && isStudioManualEditGestureLiveIn(iframe.contentDocument);
+    if (!swap || isRefreshingRef.current || swapWouldReplaceGestureNode)
+      return reloadWholeFilm(url.toString());
     swap(url.toString(), isCurrent, cancel.signal).catch((error: unknown) => {
       if (!isCurrent()) return;
       logReload("scene-swap-refused", { reason: String(error) });

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

@@ -219,6 +219,22 @@ describe("ThumbnailScheduler", () => {
     expect(scheduler.getDiagnostics()).toMatchObject({ queued: 0, active: 0, leases: 0 });
   });
 
+  it("frees an aborted job's slot at once, even when its loader ignores the abort", async () => {
+    const scheduler = new ThumbnailScheduler(
+      resolveTimelineViewportBudgets({ concurrentVideoDecodes: 1 }),
+    );
+    const stuck = deferred<ThumbnailLoadedResult>();
+    const lease = scheduler.acquire(
+      request("stuck", () => stuck.promise, "visible", { kind: "video" }),
+      vi.fn(),
+    );
+    lease.release();
+    const nextLoad = vi.fn(async () => result("next"));
+    scheduler.acquire(request("next", nextLoad, "visible", { kind: "video" }), vi.fn());
+    await flush();
+    expect(nextLoad).toHaveBeenCalledTimes(1);
+  });
+
   it("disposes a late result exactly once after its final lease releases", async () => {
     const scheduler = new ThumbnailScheduler();
     const pending = deferred<ThumbnailLoadedResult>();

package/src/player/lib/thumbnailScheduler.ts

@@ -310,6 +310,15 @@ export class ThumbnailScheduler {
     entry.controller = controller;
     this.activeByBucket[bucket]++;
     this.activeByKind[entry.request.kind]++;
+    let slotFree = false;
+    const freeSlot = () => {
+      if (slotFree) return;
+      slotFree = true;
+      this.activeByBucket[bucket]--;
+      this.activeByKind[entry.request.kind]--;
+      this.pump();
+    };
+    controller.signal.addEventListener("abort", freeSlot, { once: true });
     this.notify(entry);
 
     const pending = this.loadWithTimeout(entry, controller);
@@ -331,8 +340,7 @@ export class ThumbnailScheduler {
       })
       .finally(() => {
         if (entry.controller === controller) entry.controller = null;
-        this.activeByBucket[bucket]--;
-        this.activeByKind[entry.request.kind]--;
+        freeSlot();
         this.pump();
       });
   }

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/sceneSwap.ts

@@ -1,3 +1,4 @@
+import { studioApiFetch } from "../utils/studioApiFetch";
 type SwapWindow = Window & {
   __hfSwapScenes?: (html: string, signal?: AbortSignal) => Promise<void>;
 };
@@ -72,7 +73,7 @@ export function sceneSwapFor(
     );
     cancel?.addEventListener("abort", () => deadline.abort(cancel.reason), { once: true });
     const swapping = (async () => {
-      const response = await fetch(url, { signal: deadline.signal });
+      const response = await studioApiFetch(url, { signal: deadline.signal });
       if (!response.ok) throw new Error(`preview request failed with ${response.status}`);
       const html = await response.text();
       if (!isCurrent()) throw new Error("superseded by a newer reload");

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/telemetry/client.ts

@@ -9,6 +9,7 @@ import { browserTelemetryAllowed } from "./policy";
 import { getBrowserSystemMeta } from "./system";
 import { canaryEventProperties } from "./canary";
 import { recordBreadcrumb } from "./breadcrumbs";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 // Write-only PostHog project key, safe to embed in client code.
 const POSTHOG_API_KEY = "phc_zjjbX0PnWxERXrMHhkEJWj9A9BhGVLRReICgsfTMmpx";
@@ -83,7 +84,7 @@ function send(url: string, payload: string): void {
   // Prefer fetch with keepalive (survives page navigation). sendBeacon is a
   // fallback for older runtimes where fetch isn't available.
   try {
-    void fetch(url, {
+    void studioApiFetch(url, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: payload,

package/src/utils/blockInstaller.ts

@@ -12,6 +12,7 @@ import { saveProjectFilesWithHistory } from "./studioFileHistory";
 import { serializeStudioFileMutation } from "./studioFileMutationCoordinator";
 import { extendRootDurationInSource } from "./rootDuration";
 import { deriveTimelineStoreKeyForDomId } from "../player/lib/timelineElementHelpers";
+import { studioApiFetch } from "./studioApiFetch";
 
 function getMaxZIndexFromIframe(iframe: HTMLIFrameElement | null): number {
   try {
@@ -65,7 +66,7 @@ async function installRegistryItem({
   block: RegistryItem;
   compositionFile: string;
 } | null> {
-  const response = await fetch(buildProjectApiPath(projectId, `/registry/install`), {
+  const response = await studioApiFetch(buildProjectApiPath(projectId, `/registry/install`), {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({ blockName }),

package/src/utils/elementGsap.test.ts

@@ -0,0 +1,9 @@
+// @vitest-environment happy-dom
+import { expect, it } from "vitest";
+import { elementTargets } from "./elementGsap";
+
+it("keeps only the targets GSAP styles: not a plain object, not an XML-namespace element", () => {
+  const box = document.createElement("div");
+  const item = document.createElementNS("urn:x", "item");
+  expect(elementTargets({ targets: () => [{}, item, box, null] })).toEqual([box]);
+});

package/src/utils/elementGsap.ts

@@ -43,3 +43,10 @@ export function readElementGsapNumber(element: HTMLElement, prop: string): numbe
   const value = Number(gsapOf(element)?.getProperty?.(element, prop));
   return Number.isFinite(value) ? value : null;
 }
+
+/** The targets CSSPlugin styles: not plain objects (the runtime's filler) or XML-namespace elements. */
+export function elementTargets(tween: { targets?: () => unknown[] }): Element[] {
+  return (tween.targets?.() ?? []).filter((t): t is Element =>
+    Boolean((t as HTMLElement | null)?.style && (t as Node).nodeType),
+  );
+}

package/src/utils/gsapSoftReload.ts

@@ -209,7 +209,6 @@ export interface SoftReloadOptions {
   currentTimeOverride?: number;
   /** After-write file HTML — the primary source for the authored opacity and transform restore. */
   authoredHtml?: string;
-  reparse?: Element[];
   /** Other composition files a reset element is written in, by path; null when one could not be read. */
   nestedFiles?: Map<string, string> | null;
 }
@@ -274,7 +273,7 @@ export function applySoftReload(
   scriptText: string,
   options: SoftReloadOptions = {},
 ): SoftReloadResult {
-  const { onAsyncFailure, currentTimeOverride, authoredHtml, reparse = [] } = options;
+  const { onAsyncFailure, currentTimeOverride, authoredHtml } = options;
   if (!iframe || !scriptText) return "cannot-soft-reload";
 
   const win = iframe.contentWindow as IframeWindow | null;
@@ -347,7 +346,7 @@ export function applySoftReload(
   // fallow-ignore-next-line complexity
   const doReload = () => {
     const timelines = win.__timelines;
-    const targets = collectResetTargets(win, doc, targetKeys, reparse);
+    const targets = collectResetTargets(win, doc, targetKeys);
 
     // Kill ONLY the target composition's timeline(s) — leaving every other
     // composition's timeline (and its children on the global timeline) intact.