@hyperframes/studio 0.8.53 → 0.8.55

package/src/hooks/useTimelineEditing.ts

@@ -1,7 +1,9 @@
 // fallow-ignore-file complexity
 import { useCallback, useRef } from "react";
 import type { TimelineElement } from "../player";
+import { usePlayerStore } from "../player";
 import { useRazorSplit } from "./useRazorSplit";
+import { selectSplittableElements } from "../utils/timelineElementSplit";
 import { useTimelineAssetDropOps } from "./useTimelineAssetDropOps";
 import {
   applyTimelineStackingReorder,
@@ -23,6 +25,8 @@ import type { PersistTimelineEditInput } from "./timelineEditingHelpers";
 import { useSetAudioGroupAttribute } from "./timelineAudioGroupVolume";
 import { useSetElementAttribute } from "./timelineElementFxAttribute";
 import { useTimelineDeleteOps } from "./useTimelineDeleteOps";
+import { useTimelineRowElements } from "../player/hooks/useTimelineRowElements";
+import { useTrackPendingTimelineEdit } from "./useTrackPendingTimelineEdit";
 import { useAudioGroupCarveAssignment } from "./timelineAudioGroupCreate";
 import {
   useTimelineElementVisibilityEditing,
@@ -30,11 +34,22 @@ import {
 } from "./timelineTrackVisibility";
 import { useTimelineGroupEditing } from "./useTimelineGroupEditing";
 import { useBlockedTimelineEditToast } from "./useBlockedTimelineEditToast";
+import { useTimelineEditGate } from "./timelineEditPermission";
 import { serializeZLaneGesture } from "../components/nle/zLaneGesture";
 import { cutoverCommittedOrThrow, sdkTimingPersist } from "../utils/sdkCutover";
 import type { TimelineMoveUpdates, UseTimelineEditingOptions } from "./useTimelineEditingTypes";
 import { getStudioSaveErrorMessage } from "../utils/studioSaveDiagnostics";
 
+type GuardedTimelineHandler = (...args: never[]) => Promise<void>;
+type GuardedTimelineResolver = (...args: never[]) => readonly TimelineElement[];
+type GuardedTimelineRefusal = (...args: never[]) => void;
+
+interface GuardedTimelineEntry {
+  resolveTargets: GuardedTimelineResolver;
+  onRefused?: GuardedTimelineRefusal;
+  wrapped: GuardedTimelineHandler;
+}
+
 export function useTimelineEditing({
   projectId,
   activeCompPath,
@@ -53,10 +68,51 @@ export function useTimelineEditing({
   forceReloadSdkSession,
   invalidateGsapCache,
   handleDomZIndexReorderCommitRef,
+  canEdit,
 }: UseTimelineEditingOptions) {
   const projectIdRef = useRef(projectId);
   projectIdRef.current = projectId;
   const editQueueRef = useRef(Promise.resolve());
+  const track = useTrackPendingTimelineEdit();
+  const checkEditable = useTimelineEditGate(canEdit, showToast);
+  const checkEditableRef = useRef(checkEditable);
+  checkEditableRef.current = checkEditable;
+  // Same expanded-row source the hide handlers themselves resolve against
+  // (timelineTrackVisibility.ts) — a virtual sub-comp child's track/key
+  // only exists here, not in the raw store list canEdit would otherwise miss.
+  const timelineRowElements = useTimelineRowElements();
+  const guardedRef = useRef(new WeakMap<GuardedTimelineHandler, GuardedTimelineEntry>());
+  // Refuses (no call, no write, no history entry) when any target is
+  // blocked; otherwise runs fn as before. Cached by fn identity — like
+  // track() — so a fresh closure here doesn't defeat track's own cache.
+  const guard = useCallback(
+    <H extends (...args: never[]) => Promise<void>>(
+      resolveTargets: (...args: Parameters<H>) => readonly TimelineElement[],
+      fn: H,
+      onRefused?: (...args: Parameters<H>) => void,
+    ): H => {
+      const key = fn as unknown as GuardedTimelineHandler;
+      const cached = guardedRef.current.get(key);
+      if (cached) {
+        cached.resolveTargets = resolveTargets as unknown as GuardedTimelineResolver;
+        cached.onRefused = onRefused as unknown as GuardedTimelineRefusal | undefined;
+        return cached.wrapped as H;
+      }
+      const entry = {} as GuardedTimelineEntry;
+      entry.resolveTargets = resolveTargets as unknown as GuardedTimelineResolver;
+      entry.onRefused = onRefused as unknown as GuardedTimelineRefusal | undefined;
+      entry.wrapped = ((...args: Parameters<H>) => {
+        if (!checkEditableRef.current(entry.resolveTargets(...(args as never[])))) {
+          entry.onRefused?.(...(args as never[]));
+          return Promise.resolve();
+        }
+        return fn(...args);
+      }) as H as unknown as GuardedTimelineHandler;
+      guardedRef.current.set(key, entry);
+      return entry.wrapped as H;
+    },
+    [],
+  );
 
   const enqueueEdit = useCallback(
     (
@@ -378,9 +434,10 @@ export function useTimelineEditing({
     previewIframeRef,
     pendingTimelineEditPathRef,
     isRecordingRef,
+    checkEditable,
   });
 
-  const setElementFxAttribute = useSetElementAttribute({
+  const { revertLive: revertElementFxLive, ...setElementFxAttribute } = useSetElementAttribute({
     projectIdRef,
     activeCompPath,
     showToast,
@@ -391,16 +448,18 @@ export function useTimelineEditing({
     isRecordingRef,
   });
 
-  const setAudioGroupAttribute = useSetAudioGroupAttribute({
-    projectIdRef,
-    activeCompPath,
-    showToast,
-    writeProjectFile,
-    recordEdit,
-    previewIframeRef,
-    pendingTimelineEditPathRef,
-    isRecordingRef,
-  });
+  const { revertLive: revertAudioGroupLive, ...setAudioGroupAttribute } = useSetAudioGroupAttribute(
+    {
+      projectIdRef,
+      activeCompPath,
+      showToast,
+      writeProjectFile,
+      recordEdit,
+      previewIframeRef,
+      pendingTimelineEditPathRef,
+      isRecordingRef,
+    },
+  );
 
   const { handleTimelineElementsDelete, handleTimelineElementDelete } = useTimelineDeleteOps({
     projectIdRef,
@@ -429,6 +488,7 @@ export function useTimelineEditing({
       isRecordingRef,
       forceReloadSdkSession,
       observeProjectFileVersion,
+      checkEditable,
     });
 
   const handleBlockedTimelineEdit = useBlockedTimelineEditToast(showToast);
@@ -445,23 +505,87 @@ export function useTimelineEditing({
     forceReloadSdkSession,
   });
 
+  // Every write-handler is tracked here, the one place all hand edits
+  // converge, so undo never races a write; canEdit gates the same point.
+  // Coverage boundary: see the PR body, not every kind resolves an element.
+  const trackedRazorSplit = track(guard((element) => [element], handleRazorSplit));
   return {
-    handleTimelineElementMove,
-    handleTimelineElementResize,
-    handleToggleTrackHidden,
-    handleToggleElementHidden,
-    handleAutoGroupCarveSources,
-    setAudioGroupAttribute,
-    setElementFxAttribute,
-    handleTimelineElementDelete,
-    handleTimelineElementsDelete,
-    handleTimelineElementSplit: handleRazorSplit,
-    handleRazorSplit,
-    handleRazorSplitAll,
-    handleTimelineAssetDrop,
-    handleTimelineFileDrop,
-    handleTimelineCompositionDrop,
+    handleTimelineElementMove: track(guard((element) => [element], handleTimelineElementMove)),
+    handleTimelineElementResize: track(guard((element) => [element], handleTimelineElementResize)),
+    handleToggleTrackHidden: track(
+      guard(
+        (trackIndex) => timelineRowElements.filter((el) => el.track === trackIndex),
+        handleToggleTrackHidden,
+      ),
+    ),
+    handleToggleElementHidden: track(
+      guard((elementKey) => {
+        const keys = new Set(Array.isArray(elementKey) ? elementKey : [elementKey]);
+        return timelineRowElements.filter((el) => keys.has(el.key ?? el.id));
+      }, handleToggleElementHidden),
+    ),
+    handleAutoGroupCarveSources: track(handleAutoGroupCarveSources),
+    setAudioGroupAttribute: {
+      ...setAudioGroupAttribute,
+      // Same two-array member lookup syncStoredGroupAttribute mirrors into
+      // (timelineAudioGroupVolume.ts): a sub-composition's group members have
+      // no flat twin, only a domClipChildren entry, so both are checked.
+      setQuiet: track(
+        guard(
+          (groupId) => {
+            const state = usePlayerStore.getState();
+            const flatMembers = state.elements.filter((el) => el.audioGroup === groupId);
+            const domMembers = state.domClipChildren
+              .filter((child) => child.audioGroup === groupId)
+              .map(
+                (child): TimelineElement => ({
+                  id: child.id,
+                  domId: child.id,
+                  tag: "div",
+                  start: 0,
+                  duration: 0,
+                  track: -1,
+                }),
+              );
+            return [...flatMembers, ...domMembers];
+          },
+          setAudioGroupAttribute.setQuiet,
+          (groupId, attr) => revertAudioGroupLive(groupId, attr),
+        ),
+      ),
+    },
+    setElementFxAttribute: {
+      ...setElementFxAttribute,
+      setQuiet: track(
+        guard(
+          (element) => [element],
+          setElementFxAttribute.setQuiet,
+          (element, attr) => revertElementFxLive(element, attr),
+        ),
+      ),
+    },
+    handleTimelineElementDelete: track(guard((element) => [element], handleTimelineElementDelete)),
+    handleTimelineElementsDelete: track(
+      guard((elements) => elements, handleTimelineElementsDelete),
+    ),
+    handleTimelineElementSplit: trackedRazorSplit,
+    handleRazorSplit: trackedRazorSplit,
+    // Same selection the handler itself splits (useRazorSplit.ts).
+    handleRazorSplitAll: track(
+      guard(
+        (splitTime) => selectSplittableElements(usePlayerStore.getState().elements, splitTime),
+        handleRazorSplitAll,
+      ),
+    ),
+    handleTimelineAssetDrop: track(handleTimelineAssetDrop),
+    handleTimelineFileDrop: track(handleTimelineFileDrop),
+    handleTimelineCompositionDrop: track(handleTimelineCompositionDrop),
     handleBlockedTimelineEdit,
-    ...groupEditing,
+    handleTimelineGroupMove: track(
+      guard((changes) => changes.map((c) => c.element), groupEditing.handleTimelineGroupMove),
+    ),
+    handleTimelineGroupResize: track(
+      guard((changes) => changes.map((c) => c.element), groupEditing.handleTimelineGroupResize),
+    ),
   };
 }

package/src/hooks/useTimelineEditingTypes.ts

@@ -4,6 +4,7 @@ import type { TimelineElement } from "../player";
 import type { TimelineStackingReorderIntent } from "../player/components/timelineEditing";
 import type { EditHistoryKind } from "../utils/editHistory";
 import type { PublishSdkSession } from "../utils/sdkCutover";
+import type { CanEditTimelineElement } from "./timelineEditPermission";
 
 interface RecordEditInput {
   label: string;
@@ -49,6 +50,8 @@ export interface UseTimelineEditingOptions {
   /** Reparse authored animations after a timing rewrite changes their positions. */
   invalidateGsapCache?: () => void;
   handleDomZIndexReorderCommitRef?: MutableRefObject<TimelineZIndexReorderCommit | null>;
+  /** Refuses a hand edit at the persist boundary when set; absent = Studio unchanged. */
+  canEdit?: CanEditTimelineElement;
 }
 
 export type TimelineFileDropHandler = (

package/src/hooks/useTrackPendingTimelineEdit.test.tsx

@@ -0,0 +1,62 @@
+// @vitest-environment happy-dom
+
+import { act, createElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import { flushStudioPendingEdits } from "../utils/studioPendingEdits";
+import { useTrackPendingTimelineEdit } from "./useTrackPendingTimelineEdit";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+let root: Root | null = null;
+afterEach(() => act(() => root?.unmount()));
+
+function mount() {
+  let track!: ReturnType<typeof useTrackPendingTimelineEdit>;
+  function Probe() {
+    track = useTrackPendingTimelineEdit();
+    return null;
+  }
+  root = createRoot(document.createElement("div"));
+  act(() => root!.render(createElement(Probe)));
+  return track;
+}
+
+const deferred = <T,>() => {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((r) => (resolve = r));
+  return { promise, resolve };
+};
+
+describe("useTrackPendingTimelineEdit", () => {
+  it("feeds Studio's shared pending-edit registry, so the app-wide flush waits for it", async () => {
+    const track = mount();
+    const gate = deferred<void>();
+    const order: string[] = [];
+    const tracked = track(() => gate.promise.then(() => order.push("edit-settled")));
+    const call = tracked();
+    const flushPromise = flushStudioPendingEdits().then(() => order.push("flushed"));
+    // Give the flush's own microtasks a turn: if tracking did nothing, it
+    // would already show "flushed" here, before the edit ever settles.
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(order).toEqual([]);
+    gate.resolve();
+    await call;
+    await flushPromise;
+    expect(order).toEqual(["edit-settled", "flushed"]);
+  });
+
+  it("returns the same wrapper for the same handler across calls", () => {
+    const track = mount();
+    const handler = () => Promise.resolve();
+    expect(track(handler)).toBe(track(handler));
+  });
+
+  it("returns a different wrapper for a different handler", () => {
+    const track = mount();
+    const a = () => Promise.resolve();
+    const b = () => Promise.resolve();
+    expect(track(a)).not.toBe(track(b));
+  });
+});

package/src/hooks/useTrackPendingTimelineEdit.ts

@@ -0,0 +1,22 @@
+import { useCallback, useRef } from "react";
+import { trackStudioPendingEdit } from "../utils/studioPendingEdits";
+
+type AsyncFn = (...args: never[]) => Promise<unknown>;
+
+// Tracks a hand-edit handler's write so undo/redo (already draining this
+// registry) waits for it. Same `fn` in, same wrapper out, so memoized deps stay stable.
+export function useTrackPendingTimelineEdit() {
+  const wrappedRef = useRef(new WeakMap<AsyncFn, AsyncFn>());
+  return useCallback(<Args extends unknown[], R>(fn: (...args: Args) => Promise<R>) => {
+    const key = fn as unknown as AsyncFn;
+    const cached = wrappedRef.current.get(key);
+    if (cached) return cached as unknown as (...args: Args) => Promise<R>;
+    const wrapped = (...args: Args): Promise<R> => {
+      const result = fn(...args);
+      trackStudioPendingEdit(result);
+      return result;
+    };
+    wrappedRef.current.set(key, wrapped as unknown as AsyncFn);
+    return wrapped;
+  }, []);
+}

package/src/hostMount.test.tsx

@@ -0,0 +1,222 @@
+// @vitest-environment happy-dom
+
+// Proves the package's public exports, not internal hook paths, are enough
+// for a host to mount hand editing outside EditorShell: an edit writes
+// through the history path, Undo restores it, and a 409 shows the banner.
+import { act, createElement, useRef } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+// Backend/storage mocking only, standing in for a host's own server and
+// persistence — not part of the host's integration code under test.
+import { studioFileContentVersion } from "./utils/studioFileVersion";
+import { createMemoryEditHistoryStorage } from "./utils/editHistoryStorage";
+import {
+  flushStudioPendingEdits,
+  useTimelineEditing,
+  useProjectFileWriter,
+  usePersistentEditHistory,
+  useEditHistoryActions,
+  ExternalFileConflictBanner,
+  StudioFileConflictError,
+  type ExternalFileChangeCoordinatorHandle,
+  type TimelineElement,
+} from "./index";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const ORIGINAL_HTML = '<div id="clip" data-start="0" data-track-index="0"></div>';
+
+let root: Root | null = null;
+afterEach(() => {
+  act(() => root?.unmount());
+  document.body.innerHTML = "";
+  vi.unstubAllGlobals();
+});
+
+/** A minimal disk with etag-guarded PUT, faithful enough to exercise a real
+ *  conflict: a stale If-Match gets a 409 with the current version + content. */
+function stubHostProjectDisk(
+  initial: Record<string, string>,
+  options?: { editElsewhereAfterFirstRead?: boolean },
+) {
+  const content = { ...initial };
+  const readsSeen = new Set<string>();
+  // The real backend's etag is a content hash (useProjectFileWriter derives
+  // If-Match the same way) — an arbitrary counter here would make every
+  // write from a host that hasn't just read the file look stale.
+  const versionOf = (path: string) => studioFileContentVersion(content[path]);
+
+  async function handlePut(path: string, init: RequestInit | undefined) {
+    const ifMatch = new Headers(init?.headers).get("If-Match");
+    const currentVersion = await versionOf(path);
+    if (ifMatch && ifMatch !== currentVersion) {
+      return new Response(JSON.stringify({ currentVersion, currentContent: content[path] }), {
+        status: 409,
+      });
+    }
+    content[path] = String(init?.body ?? "");
+    return new Response(JSON.stringify({ version: await versionOf(path) }), { status: 200 });
+  }
+
+  async function handleGet(path: string) {
+    const served = content[path];
+    // Simulates another writer landing between this read and the caller's
+    // own write: content moves on right after being served once, so the
+    // caller's hash of what it just read no longer matches disk.
+    if (options?.editElsewhereAfterFirstRead && !readsSeen.has(path)) {
+      readsSeen.add(path);
+      content[path] = `${served} <!--edited elsewhere-->`;
+    }
+    return new Response(
+      JSON.stringify({ content: served, version: await studioFileContentVersion(served) }),
+      { status: 200 },
+    );
+  }
+
+  const fetchMock = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+    const match = String(input).match(/\/files\/([^?]+)/);
+    const path = match ? decodeURIComponent(match[1]) : "";
+    return (init?.method ?? "GET") === "PUT" ? handlePut(path, init) : handleGet(path);
+  });
+  vi.stubGlobal("fetch", fetchMock);
+  return { content, fetchMock };
+}
+
+type TimelineEditingHandle = {
+  handleTimelineElementMove: (
+    element: TimelineElement,
+    updates: { start: number; track: number },
+  ) => Promise<void>;
+};
+
+function mountHost(
+  clip: TimelineElement,
+  iframe: HTMLIFrameElement,
+): {
+  timelineEditing: TimelineEditingHandle;
+  undo: () => Promise<void>;
+  bannerHost: HTMLDivElement;
+} {
+  let timelineEditing: TimelineEditingHandle | null = null;
+  let undo: (() => Promise<void>) | null = null;
+  let conflict: ExternalFileChangeCoordinatorHandle = {
+    blocked: null,
+    retry: async () => {},
+    useExternalFile: async () => {},
+    keepStudioFile: async () => {},
+  };
+  const bannerHost = document.createElement("div");
+  document.body.append(bannerHost);
+  const bannerRoot = createRoot(bannerHost);
+  // Created once: a fresh storage object on every render would change
+  // usePersistentEditHistory's effect deps each time and loop forever.
+  const storage = createMemoryEditHistoryStorage();
+
+  function Harness() {
+    const writer = useProjectFileWriter({ projectId: "p1" });
+    const editHistory = usePersistentEditHistory({ projectId: "p1", storage });
+    const historyActions = useEditHistoryActions({
+      editHistory,
+      readOptionalProjectFile: writer.readOptionalProjectFile,
+      readProjectFile: writer.readProjectFile,
+      writeProjectFile: writer.writeProjectFile,
+      showToast: () => {},
+      syncHistoryPreviewAfterApply: async () => {},
+      // The pattern a host's own dom-edit queue would also drain through —
+      // this is the one gate that closes the undo/delete race (#4194).
+      waitForPendingDomEditSaves: async () => {
+        const result = await flushStudioPendingEdits();
+        if (result.status !== "clean") throw result.error;
+      },
+    });
+    undo = historyActions.undo;
+    const commitRef = useRef(null);
+    timelineEditing = useTimelineEditing({
+      projectId: "p1",
+      activeCompPath: "index.html",
+      timelineElements: [clip],
+      showToast: () => {},
+      writeProjectFile: async (path, content, expectedContent) => {
+        try {
+          await writer.writeProjectFile(path, content, expectedContent);
+        } catch (error) {
+          if (error instanceof StudioFileConflictError) {
+            conflict = {
+              ...conflict,
+              blocked: { status: "conflict", generation: 0, error, payload: null },
+            };
+            bannerRoot.render(createElement(ExternalFileConflictBanner, { coordinator: conflict }));
+          }
+          throw error;
+        }
+      },
+      observeProjectFileVersion: writer.observeProjectFileVersion,
+      recordEdit: editHistory.recordEdit,
+      reloadPreview: () => {},
+      previewIframeRef: { current: iframe },
+      pendingTimelineEditPathRef: { current: new Set<string>() },
+      uploadProjectFiles: async () => [],
+      handleDomZIndexReorderCommitRef: commitRef,
+    });
+    return null;
+  }
+
+  root = createRoot(document.createElement("div"));
+  act(() => root!.render(createElement(Harness)));
+  if (!timelineEditing) throw new Error("Expected hook to mount");
+  if (!undo) throw new Error("Expected undo to be exposed");
+  return { timelineEditing, undo, bannerHost };
+}
+
+describe("public export surface: a host mounting hand editing outside EditorShell", () => {
+  it("writes a move through the history path and undo restores it", async () => {
+    const disk = stubHostProjectDisk({ "index.html": ORIGINAL_HTML });
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    iframe.contentDocument!.body.innerHTML = ORIGINAL_HTML;
+    const clip: TimelineElement = {
+      id: "clip",
+      domId: "clip",
+      tag: "div",
+      start: 0,
+      duration: 2,
+      track: 0,
+    };
+
+    const { timelineEditing, undo } = mountHost(clip, iframe);
+    await act(async () => {
+      await timelineEditing.handleTimelineElementMove(clip, { start: 5, track: 0 });
+    });
+    expect(disk.content["index.html"]).toContain('data-start="5"');
+
+    await act(async () => {
+      await undo();
+    });
+    expect(disk.content["index.html"]).toContain('data-start="0"');
+  });
+
+  it("surfaces the conflict banner on a 409", async () => {
+    stubHostProjectDisk({ "index.html": ORIGINAL_HTML }, { editElsewhereAfterFirstRead: true });
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    iframe.contentDocument!.body.innerHTML = ORIGINAL_HTML;
+    const clip: TimelineElement = {
+      id: "clip",
+      domId: "clip",
+      tag: "div",
+      start: 0,
+      duration: 2,
+      track: 0,
+    };
+
+    const { timelineEditing, bannerHost } = mountHost(clip, iframe);
+
+    await act(async () => {
+      await expect(
+        timelineEditing.handleTimelineElementMove(clip, { start: 5, track: 0 }),
+      ).rejects.toBeInstanceOf(StudioFileConflictError);
+    });
+
+    expect(bannerHost.textContent).toContain("changed outside Studio");
+  });
+});

package/src/index.ts

@@ -1,10 +1,12 @@
 // UI primitives
 export { Button, buttonBase, buttonSizes, buttonVariants } from "./components/ui/Button";
 export type { ButtonSize, ButtonVariant, PreviewState } from "./components/ui/Button";
+export { HyperframesLogo } from "./components/StudioHeader";
 export { IconButton } from "./components/ui/IconButton";
 export { Tab, TabPanel, Tabs, TabsList } from "./components/ui/Tabs";
+export { HyperframesLoader } from "./components/ui/HyperframesLoader";
+export type { HyperframesLoaderProps } from "./components/ui/HyperframesLoader";
 export { Tooltip } from "./components/ui/Tooltip";
-export { HyperframesLogo } from "./components/StudioHeader";
 export { cn } from "./components/ui/cn";
 export {
   ContextMenu,
@@ -49,7 +51,7 @@ export {
   liveTime,
   formatTime,
 } from "./player";
-export type { TimelineElement } from "./player";
+export type { TimelineElement, TimelineTimeRange } from "./player";
 
 // Host overlays: draw over the preview in composition coordinates (see EditorShellProps.gestureOverlay)
 export { usePreviewCompositionRect } from "./components/editor/usePreviewCompositionRect";
@@ -97,3 +99,39 @@ export type { PickedElement } from "./hooks/useElementPicker";
 export { resolveSourceFile, applyPatch } from "./utils/sourcePatcher";
 export type { PatchOperation } from "./utils/sourcePatcher";
 export { parseStyleString, mergeStyleIntoTag, findElementBlock } from "./utils/htmlEditor";
+
+// Timeline editing: Studio's own hand-edit path, undo/redo, the
+// etag-guarded writer and the conflict banner, for a host mounting the
+// timeline outside EditorShell.
+export { usePersistentEditHistory } from "./hooks/usePersistentEditHistory";
+export type { UsePersistentEditHistoryOptions } from "./hooks/usePersistentEditHistory";
+export { useTimelineEditing } from "./hooks/useTimelineEditing";
+export type { UseTimelineEditingOptions } from "./hooks/useTimelineEditingTypes";
+// A host's own waitForPendingDomEditSaves must also call this, or undo/redo
+// can race a write still in flight (see useTrackPendingTimelineEdit.ts).
+export { flushStudioPendingEdits } from "./utils/studioPendingEdits";
+export type { StudioPendingEditsDrainResult } from "./utils/studioPendingEdits";
+export type {
+  CanEditTimelineElement,
+  TimelineEditPermission,
+} from "./hooks/timelineEditPermission";
+export { useEditHistoryActions } from "./hooks/useEditHistoryActions";
+export type {
+  EditHistoryHandle,
+  UseEditHistoryActionsOptions,
+} from "./hooks/useEditHistoryActions";
+export { useProjectFileWriter } from "./hooks/useProjectFileWriter";
+export type { UseProjectFileWriterOptions } from "./hooks/useProjectFileWriter";
+// A host's writeProjectFile throws this on a 409; catch it to know when
+// to show ExternalFileConflictBanner.
+export { StudioFileConflictError } from "./utils/studioSaveDiagnostics";
+export { ExternalFileConflictBanner } from "./components/ExternalFileConflictBanner";
+export type {
+  ExternalFileChangeCoordinatorHandle,
+  ExternalFileChangeBlockedState,
+} from "./hooks/useExternalFileChangeCoordinator";
+export { TimelinePane } from "./components/nle/TimelinePane";
+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";