@hyperframes/studio 0.6.99 → 0.6.101

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

@@ -0,0 +1,91 @@
+import { describe, expect, it } from "vitest";
+import { buildExpandedElements } from "./useExpandedTimelineElements";
+import type { TimelineElement } from "../store/playerStore";
+import type { ClipManifestClip } from "../lib/playbackTypes";
+
+const clip = (over: Partial<ClipManifestClip>): ClipManifestClip => ({
+  id: "x",
+  label: "x",
+  start: 0,
+  duration: 1,
+  track: 0,
+  kind: "element",
+  tagName: "div",
+  compositionId: null,
+  parentCompositionId: null,
+  compositionSrc: null,
+  assetUrl: null,
+  ...over,
+});
+
+const el = (over: Partial<TimelineElement>): TimelineElement =>
+  ({ id: "x", start: 0, duration: 1, track: 0, tag: "div", ...over }) as TimelineElement;
+
+describe("buildExpandedElements", () => {
+  it("rebases a 1-level child onto its sub-comp host (start + sourceFile)", () => {
+    // host s3 at absolute 16 → stats-panel.html; children live in that file.
+    const elements = [el({ id: "s3", start: 16, duration: 7, compositionSrc: "stats.html" })];
+    const manifest = [
+      clip({ id: "s3", start: 16, duration: 7, compositionSrc: "stats.html" }),
+      clip({ id: "stat-1", start: 16.5, duration: 5 }),
+      clip({ id: "stat-2", start: 16.9, duration: 5 }),
+    ];
+    const parentMap = new Map([
+      ["stat-1", "s3"],
+      ["stat-2", "s3"],
+    ]);
+
+    const out = buildExpandedElements(elements, manifest, parentMap, "s3", "s3");
+    const child = out.find((e) => e.domId === "stat-1")!;
+    expect(child.expandedParentStart).toBe(16);
+    expect(child.sourceFile).toBe("stats.html");
+  });
+
+  it("rebases a 2-level child onto its NESTED host, not the top-level scene", () => {
+    // top host A@10 (a.html) embeds host B@12 (b.html); child C lives in b.html.
+    // Edits must rebase onto B (12 / b.html), not A (10 / a.html).
+    const elements = [el({ id: "A", start: 10, duration: 8, compositionSrc: "a.html" })];
+    const manifest = [
+      clip({ id: "A", start: 10, duration: 8, compositionSrc: "a.html" }),
+      clip({ id: "B", start: 12, duration: 4, compositionSrc: "b.html" }),
+      clip({ id: "C", start: 13, duration: 2 }),
+      clip({ id: "C2", start: 14, duration: 1 }),
+    ];
+    const parentMap = new Map([
+      ["B", "A"],
+      ["C", "B"],
+      ["C2", "B"],
+    ]);
+
+    // Expanding C's siblings: topLevel A, immediate parent B.
+    const out = buildExpandedElements(elements, manifest, parentMap, "A", "B");
+    const child = out.find((e) => e.domId === "C")!;
+    expect(child.expandedParentStart).toBe(12); // B's start, not A's 10
+    expect(child.sourceFile).toBe("b.html"); // B's file, not a.html
+  });
+
+  it("rebases a 3-level child onto its deepest host, not intermediate or top", () => {
+    // A@10 (a.html) → B@12 (b.html) → C@13 (c.html); leaf D lives in c.html.
+    // Edits must rebase onto C (13 / c.html), not B (12 / b.html) or A (10 / a.html).
+    const elements = [el({ id: "A", start: 10, duration: 8, compositionSrc: "a.html" })];
+    const manifest = [
+      clip({ id: "A", start: 10, duration: 8, compositionSrc: "a.html" }),
+      clip({ id: "B", start: 12, duration: 5, compositionSrc: "b.html" }),
+      clip({ id: "C", start: 13, duration: 3, compositionSrc: "c.html" }),
+      clip({ id: "D", start: 13.5, duration: 1 }),
+      clip({ id: "D2", start: 14, duration: 1 }),
+    ];
+    const parentMap = new Map([
+      ["B", "A"],
+      ["C", "B"],
+      ["D", "C"],
+      ["D2", "C"],
+    ]);
+
+    // Expanding D's siblings: topLevel A, immediate parent C.
+    const out = buildExpandedElements(elements, manifest, parentMap, "A", "C");
+    const child = out.find((e) => e.domId === "D")!;
+    expect(child.expandedParentStart).toBe(13); // C's start, not B's 12 or A's 10
+    expect(child.sourceFile).toBe("c.html"); // C's file, not b.html or a.html
+  });
+});

package/src/player/hooks/useExpandedTimelineElements.ts

@@ -0,0 +1,153 @@
+import { useMemo } from "react";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import type { ClipManifestClip } from "../lib/playbackTypes";
+import { createTimelineElementFromManifestClip } from "../lib/timelineDOM";
+
+function findTopLevelAncestor(id: string, parentMap: Map<string, string>): string | null {
+  let current = parentMap.get(id);
+  if (!current) return null;
+  const visited = new Set<string>();
+  visited.add(id);
+  while (parentMap.has(current)) {
+    if (visited.has(current)) return current;
+    visited.add(current);
+    current = parentMap.get(current)!;
+  }
+  return current;
+}
+
+function extractDomId(key: string): string {
+  const hashIdx = key.lastIndexOf("#");
+  return hashIdx >= 0 ? key.slice(hashIdx + 1) : key;
+}
+
+function resolveRawId(
+  selectedId: string | null,
+  manifest: ClipManifestClip[],
+  parentMap: Map<string, string>,
+): string | null {
+  if (!selectedId) return null;
+  const rawId = extractDomId(selectedId);
+  if (parentMap.has(rawId)) return rawId;
+  if (parentMap.has(selectedId)) return selectedId;
+  const clip = manifest.find((c) => c.label === selectedId || c.label === rawId);
+  if (clip?.id && parentMap.has(clip.id)) return clip.id;
+  return null;
+}
+
+function filterToTopLevel(
+  elements: TimelineElement[],
+  parentMap: Map<string, string>,
+): TimelineElement[] {
+  if (parentMap.size === 0) return elements;
+  return elements.filter((el) => !parentMap.has(el.domId ?? el.id));
+}
+
+function clampChildToParent(
+  child: ClipManifestClip,
+  parentStart: number,
+  parentEnd: number,
+): { start: number; duration: number } | null {
+  const childEnd = child.start + child.duration;
+  if (child.start >= parentEnd || childEnd <= parentStart) return null;
+  const clampedStart = Math.max(child.start, parentStart);
+  const clampedDuration = Math.min(childEnd, parentEnd) - clampedStart;
+  return clampedDuration > 0 ? { start: clampedStart, duration: clampedDuration } : null;
+}
+
+interface DisplayBounds {
+  start: number;
+  end: number;
+  track: number;
+}
+
+// `display` bounds come from the top-level scene clip (where the expanded row is
+// drawn). `editBasis` comes from the child's immediate sub-comp host: its absolute
+// start anchors local-time edits and its compositionSrc is the file edits write to.
+// They differ only for sub-comp-inside-sub-comp nesting.
+function buildChildElements(
+  siblings: ClipManifestClip[],
+  display: DisplayBounds,
+  editBasis: { start: number; sourceFile: string | undefined },
+): TimelineElement[] {
+  const result: TimelineElement[] = [];
+  for (const child of siblings) {
+    const clamped = clampChildToParent(child, display.start, display.end);
+    if (!clamped) continue;
+    const base = createTimelineElementFromManifestClip({
+      clip: child,
+      fallbackIndex: result.length,
+    });
+    result.push({
+      ...base,
+      start: clamped.start,
+      duration: clamped.duration,
+      track: display.track + result.length,
+      expandedParentStart: editBasis.start,
+      domId: child.id ?? undefined,
+      selector: child.id ? `#${child.id}` : undefined,
+      sourceFile: editBasis.sourceFile,
+      timingSource: "authored" as const,
+    });
+  }
+  return result;
+}
+
+// Exported for tests.
+export function buildExpandedElements(
+  elements: TimelineElement[],
+  manifest: ClipManifestClip[],
+  parentMap: Map<string, string>,
+  topLevelId: string,
+  siblingParentId: string,
+): TimelineElement[] {
+  const topLevelElement = elements.find((el) => el.id === topLevelId || el.domId === topLevelId);
+  if (!topLevelElement) return filterToTopLevel(elements, parentMap);
+
+  const siblings = manifest.filter((c) => c.id != null && parentMap.get(c.id) === siblingParentId);
+  if (siblings.length === 0) return filterToTopLevel(elements, parentMap);
+
+  // The sub-comp host the children actually live in: top-level host for 1-level
+  // nesting, a nested host for deeper nesting. Its start/file anchor edits.
+  const parentHost = manifest.find((c) => c.id === siblingParentId);
+  const editBasis = {
+    start: parentHost?.start ?? topLevelElement.start,
+    sourceFile: parentHost?.compositionSrc ?? topLevelElement.compositionSrc ?? undefined,
+  };
+
+  const parentKey = topLevelElement.key ?? topLevelElement.id;
+  const expanded = buildChildElements(
+    siblings,
+    {
+      start: topLevelElement.start,
+      end: topLevelElement.start + topLevelElement.duration,
+      track: topLevelElement.track,
+    },
+    editBasis,
+  );
+  if (expanded.length === 0) return filterToTopLevel(elements, parentMap);
+
+  return elements
+    .filter((el) => (el.key ?? el.id) === parentKey || !parentMap.has(el.domId ?? el.id))
+    .flatMap((el) => ((el.key ?? el.id) === parentKey ? expanded : [el]));
+}
+
+export function useExpandedTimelineElements(): TimelineElement[] {
+  const elements = usePlayerStore((s) => s.elements);
+  const clipManifest = usePlayerStore((s) => s.clipManifest);
+  const clipParentMap = usePlayerStore((s) => s.clipParentMap);
+  const selectedElementId = usePlayerStore((s) => s.selectedElementId);
+
+  return useMemo(() => {
+    if (!clipManifest || clipManifest.length === 0 || clipParentMap.size === 0) {
+      return elements;
+    }
+
+    const rawId = resolveRawId(selectedElementId, clipManifest, clipParentMap);
+    if (!rawId) return filterToTopLevel(elements, clipParentMap);
+
+    const immediateParent = clipParentMap.get(rawId)!;
+    const topLevel = findTopLevelAncestor(rawId, clipParentMap) ?? immediateParent;
+    return buildExpandedElements(elements, clipManifest, clipParentMap, topLevel, immediateParent);
+  }, [elements, clipManifest, clipParentMap, selectedElementId]);
+}

package/src/player/hooks/useTimelineSyncCallbacks.ts

@@ -66,6 +66,8 @@ export function useTimelineSyncCallbacks({
         return;
       }
 
+      usePlayerStore.getState().setClipManifest(data.clips);
+
       // Show root-level clips: no parentCompositionId, OR parent is a "phantom wrapper"
       const clipCompositionIds = new Set(data.clips.map((c) => c.compositionId).filter(Boolean));
       const filtered = data.clips.filter(
@@ -77,6 +79,26 @@ export function useTimelineSyncCallbacks({
       } catch {
         iframeDoc = null;
       }
+
+      try {
+        const iframeWin = iframeRef.current?.contentWindow as
+          | (Window & { __clipTree?: import("@hyperframes/core/runtime/clipTree").ClipTree })
+          | null;
+        const clipTree = iframeWin?.__clipTree;
+        if (clipTree) {
+          const parentMap = new Map<string, string>();
+          const walk = (nodes: typeof clipTree.roots) => {
+            for (const node of nodes) {
+              if (node.id && node.parentId) parentMap.set(node.id, node.parentId);
+              if (node.children.length > 0) walk(node.children);
+            }
+          };
+          walk(clipTree.roots);
+          usePlayerStore.getState().setClipParentMap(parentMap);
+        }
+      } catch {
+        // cross-origin or __clipTree not available — parentMap stays empty
+      }
       const usedHostEls = new Set<Element>();
       const els: TimelineElement[] = filtered.map((clip, index) => {
         const hostEl = iframeDoc

package/src/player/store/playerStore.ts

@@ -1,6 +1,7 @@
 import { create } from "zustand";
 import type { MusicBeatAnalysis } from "@hyperframes/core/beats";
 import type { BeatEditState } from "../../utils/beatEditing";
+import type { ClipManifestClip } from "../lib/playbackTypes";
 import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/studioUiPreferences";
 
 /** Minimal keyframe cache types — mirrors GsapKeyframesData without pulling in Node-only gsap-parser. */
@@ -50,6 +51,13 @@ export interface TimelineElement {
   timelineLocked?: boolean;
   /** Value of data-timeline-role attribute — used to identify music vs. voiceover. */
   timelineRole?: string;
+  /**
+   * Set by useExpandedTimelineElements on an inline-expanded sub-composition
+   * child: the absolute master-timeline start of the sub-comp host the child
+   * lives in. Presence marks the element as expanded; edits subtract it to get
+   * the child's local (sourceFile-relative) time. Works at any nesting depth.
+   */
+  expandedParentStart?: number;
 }
 
 export type ZoomMode = "fit" | "manual";
@@ -138,21 +146,22 @@ interface PlayerState {
   /** Undo/redo stacks for beat edits (in-memory, session-only). */
   beatUndo: BeatHistoryEntry[];
   beatRedo: BeatHistoryEntry[];
-  /** Apply a beat edit and record it for undo. */
   commitBeatEdits: (next: BeatEditState | null, label: string) => void;
-  /** Undo/redo the most recent beat edit; returns its label or null if none. */
   undoBeatEdits: () => string | null;
   redoBeatEdits: () => string | null;
-  /** Clear beat edit history (e.g. when the music track changes). */
   resetBeatHistory: () => void;
-  /** Callback that persists current beats to disk; registered by the analysis hook. */
   beatPersist: (() => void) | null;
   setBeatPersist: (fn: (() => void) | null) => void;
+
+  clipManifest: ClipManifestClip[] | null;
+  setClipManifest: (clips: ClipManifestClip[] | null) => void;
+  clipParentMap: Map<string, string>;
+  setClipParentMap: (map: Map<string, string>) => void;
 }
 
 interface BeatHistoryEntry {
-  restore: BeatEditState | null; // state to restore when this entry is applied
-  at: number; // original edit timestamp (for global undo ordering)
+  restore: BeatEditState | null;
+  at: number;
   label: string;
 }
 
@@ -271,6 +280,11 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
     return entry.label;
   },
 
+  clipManifest: null,
+  setClipManifest: (clips) => set({ clipManifest: clips }),
+  clipParentMap: new Map(),
+  setClipParentMap: (map) => set({ clipParentMap: map }),
+
   setIsPlaying: (playing) => {
     if (get().isPlaying === playing) return;
     set({ isPlaying: playing });
@@ -338,12 +352,12 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
       selectedKeyframes: new Set(),
       selectedElementIds: new Set(),
       keyframeCache: new Map(),
-      // Beat state is project-specific — clear it so a project switch can't
-      // apply the previous project's beats/undo/persist to the new one.
       beatAnalysis: null,
       beatEdits: null,
       beatUndo: [],
       beatRedo: [],
       beatPersist: null,
+      clipManifest: null,
+      clipParentMap: new Map(),
     }),
 }));

package/src/telemetry/events.test.ts

@@ -7,7 +7,12 @@ vi.mock("./client", () => ({
   trackEvent: (...args: unknown[]) => trackEvent(...args),
 }));
 
-const { trackStudioSessionStart, trackStudioRenderStart } = await import("./events");
+const {
+  trackStudioSessionStart,
+  trackStudioRenderStart,
+  trackStudioRazorSplit,
+  trackStudioExpandedClipEdit,
+} = await import("./events");
 
 describe("studio telemetry events", () => {
   beforeEach(() => {
@@ -54,4 +59,14 @@ describe("studio telemetry events", () => {
       composition: undefined,
     });
   });
+
+  it("trackStudioRazorSplit emits 'studio_razor_split' with mode and count", () => {
+    trackStudioRazorSplit({ mode: "all", count: 3 });
+    expect(trackEvent).toHaveBeenCalledWith("studio_razor_split", { mode: "all", count: 3 });
+  });
+
+  it("trackStudioExpandedClipEdit emits 'studio_expanded_clip_edit' with action", () => {
+    trackStudioExpandedClipEdit({ action: "resize" });
+    expect(trackEvent).toHaveBeenCalledWith("studio_expanded_clip_edit", { action: "resize" });
+  });
 });

package/src/telemetry/events.ts

@@ -48,6 +48,21 @@ function getBrowserDoctorSummary(): string {
   }
 }
 
+export function trackStudioRazorSplit(props: { mode: "single" | "all"; count: number }): void {
+  trackEvent("studio_razor_split", {
+    mode: props.mode,
+    count: props.count,
+  });
+}
+
+// Adoption signal for the inline timeline-expansion surface: edits applied to a
+// sub-composition child clip while its parent scene is expanded.
+export function trackStudioExpandedClipEdit(props: {
+  action: "move" | "resize" | "delete" | "split";
+}): void {
+  trackEvent("studio_expanded_clip_edit", { action: props.action });
+}
+
 export function trackStudioFeedback(props: { rating: number; comment?: string }): void {
   trackEvent("survey sent", {
     $survey_id: "studio_experience",

package/src/utils/blockCategories.ts

@@ -1,11 +1,10 @@
 import {
   type BlockCategory,
-  type BlockCategoryMeta,
   BLOCK_CATEGORIES,
   resolveBlockCategory,
 } from "@hyperframes/core/registry";
 
-export type { BlockCategory, BlockCategoryMeta };
+export type { BlockCategory };
 export { BLOCK_CATEGORIES, resolveBlockCategory };
 
 const COLOR_MAP: Record<BlockCategory, { bg: string; text: string; dot: string }> = {
@@ -17,6 +16,7 @@ const COLOR_MAP: Record<BlockCategory, { bg: string; text: string; dot: string }
   captions: { bg: "bg-cyan-500/15", text: "text-cyan-400", dot: "bg-cyan-400" },
   effects: { bg: "bg-rose-500/15", text: "text-rose-400", dot: "bg-rose-400" },
   "text-effects": { bg: "bg-violet-500/15", text: "text-violet-400", dot: "bg-violet-400" },
+  "code-animation": { bg: "bg-emerald-500/15", text: "text-emerald-400", dot: "bg-emerald-400" },
 };
 
 export function getCategoryColors(category: BlockCategory) {

package/src/utils/sdkShadow.test.ts

@@ -0,0 +1,246 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import {
+  patchOpsToSdkEditOps,
+  runShadowDelete,
+  runShadowTiming,
+  runShadowGsapTween,
+  SdkShadowMismatch,
+} from "./sdkShadow";
+import type { PatchOperation } from "./sourcePatcher";
+import { openComposition } from "@hyperframes/sdk";
+
+// Capture sdk_shadow_dispatch telemetry for the non-PatchOperation runners.
+const trackedEvents: Array<{ event: string; props: Record<string, unknown> }> = [];
+vi.mock("./studioTelemetry", () => ({
+  trackStudioEvent: (event: string, props: Record<string, unknown>) =>
+    trackedEvents.push({ event, props }),
+}));
+beforeEach(() => {
+  trackedEvents.length = 0;
+});
+const lastShadow = () =>
+  trackedEvents.filter((e) => e.event === "sdk_shadow_dispatch").at(-1)?.props;
+
+const BASE_HTML = /* html */ `<!DOCTYPE html>
+<html><body>
+  <div data-hf-id="hf-box" style="color: red; width: 100px;" data-name="box">Hello</div>
+</body></html>`;
+
+describe("patchOpsToSdkEditOps", () => {
+  it("maps inline-style ops to a single setStyle EditOp", () => {
+    const ops: PatchOperation[] = [
+      { type: "inline-style", property: "color", value: "#00f" },
+      { type: "inline-style", property: "opacity", value: "0.5" },
+    ];
+    const result = patchOpsToSdkEditOps("hf-box", ops);
+    expect(result).toHaveLength(1);
+    expect(result[0]).toEqual({
+      type: "setStyle",
+      target: "hf-box",
+      styles: { color: "#00f", opacity: "0.5" },
+    });
+  });
+
+  it("maps text-content op to setText EditOp", () => {
+    const ops: PatchOperation[] = [{ type: "text-content", property: "text", value: "World" }];
+    const result = patchOpsToSdkEditOps("hf-box", ops);
+    expect(result).toHaveLength(1);
+    expect(result[0]).toEqual({ type: "setText", target: "hf-box", value: "World" });
+  });
+
+  it("maps attribute op to setAttribute with data- prefix", () => {
+    const ops: PatchOperation[] = [{ type: "attribute", property: "name", value: "hero" }];
+    const result = patchOpsToSdkEditOps("hf-box", ops);
+    expect(result).toHaveLength(1);
+    expect(result[0]).toEqual({
+      type: "setAttribute",
+      target: "hf-box",
+      name: "data-name",
+      value: "hero",
+    });
+  });
+
+  it("maps html-attribute op to setAttribute without prefix", () => {
+    const ops: PatchOperation[] = [
+      { type: "html-attribute", property: "contenteditable", value: "true" },
+    ];
+    const result = patchOpsToSdkEditOps("hf-box", ops);
+    expect(result).toHaveLength(1);
+    expect(result[0]).toEqual({
+      type: "setAttribute",
+      target: "hf-box",
+      name: "contenteditable",
+      value: "true",
+    });
+  });
+
+  it("handles null value for attribute removal", () => {
+    const ops: PatchOperation[] = [{ type: "html-attribute", property: "hidden", value: null }];
+    const result = patchOpsToSdkEditOps("hf-box", ops);
+    expect(result[0]).toEqual({
+      type: "setAttribute",
+      target: "hf-box",
+      name: "hidden",
+      value: null,
+    });
+  });
+
+  it("returns empty array for unknown op types", () => {
+    const ops = [{ type: "unknown-op", property: "x", value: "y" }] as unknown as PatchOperation[];
+    expect(patchOpsToSdkEditOps("hf-box", ops)).toHaveLength(0);
+  });
+});
+
+describe("sdkShadowDispatch (integration)", () => {
+  it("applies ops and returns no mismatches when SDK matches expected values", async () => {
+    const { sdkShadowDispatch } = await import("./sdkShadow");
+    const session = await openComposition(BASE_HTML);
+
+    const ops: PatchOperation[] = [{ type: "inline-style", property: "color", value: "#00f" }];
+    const result = sdkShadowDispatch(session, "hf-box", ops);
+
+    expect(result.dispatched).toBe(true);
+    expect(result.mismatches).toHaveLength(0);
+    expect(session.getElement("hf-box")?.inlineStyles.color).toBe("#00f");
+  });
+
+  it("returns dispatched:false when hfId not found in session", async () => {
+    const { sdkShadowDispatch } = await import("./sdkShadow");
+    const session = await openComposition(BASE_HTML);
+
+    const ops: PatchOperation[] = [{ type: "inline-style", property: "color", value: "#00f" }];
+    const result = sdkShadowDispatch(session, "hf-missing", ops);
+
+    expect(result.dispatched).toBe(false);
+    expect(result.mismatches).toHaveLength(1);
+    expect(result.mismatches[0]).toMatchObject<SdkShadowMismatch>({
+      kind: "element_not_found",
+      hfId: "hf-missing",
+    });
+  });
+
+  it("applies text op and reads back via session.getElement", async () => {
+    const { sdkShadowDispatch } = await import("./sdkShadow");
+    const session = await openComposition(BASE_HTML);
+
+    const ops: PatchOperation[] = [{ type: "text-content", property: "text", value: "Updated" }];
+    sdkShadowDispatch(session, "hf-box", ops);
+
+    expect(session.getElement("hf-box")?.text).toBe("Updated");
+  });
+
+  it("applies attribute op and reads back via session.getElement", async () => {
+    const { sdkShadowDispatch } = await import("./sdkShadow");
+    const session = await openComposition(BASE_HTML);
+
+    const ops: PatchOperation[] = [{ type: "attribute", property: "name", value: "hero" }];
+    sdkShadowDispatch(session, "hf-box", ops);
+
+    expect(session.getElement("hf-box")?.attributes["data-name"]).toBe("hero");
+  });
+
+  it("returns dispatch_error when dispatch throws — does not propagate", async () => {
+    const { sdkShadowDispatch } = await import("./sdkShadow");
+    const session = await openComposition(BASE_HTML);
+    // Poison dispatch so it throws on any call
+    session.dispatch = () => {
+      throw new Error("sdk internal error");
+    };
+
+    const ops: PatchOperation[] = [{ type: "inline-style", property: "color", value: "red" }];
+    let result: ReturnType<typeof sdkShadowDispatch> | undefined;
+    expect(() => {
+      result = sdkShadowDispatch(session, "hf-box", ops);
+    }).not.toThrow();
+
+    expect(result!.dispatched).toBe(false);
+    expect(result!.mismatches).toHaveLength(1);
+    expect(result!.mismatches[0]).toMatchObject<SdkShadowMismatch>({
+      kind: "dispatch_error",
+      hfId: "hf-box",
+      error: expect.stringContaining("sdk internal error"),
+    });
+  });
+});
+
+const TIMING_HTML = /* html */ `<!DOCTYPE html>
+<html><body>
+  <div data-hf-id="hf-clip" data-start="0" data-duration="1" data-track="0">clip</div>
+</body></html>`;
+
+const GSAP_HTML = `<div data-hf-id="hf-stage" data-hf-root style="width:1280px;height:720px">
+  <div data-hf-id="hf-box" style="opacity:0"></div>
+  <script>var tl = gsap.timeline({ paused: true });
+tl.to("[data-hf-id=\\"hf-box\\"]", { opacity: 1, duration: 0.5 }, 0.2);
+window.__timelines["t"] = tl;</script>
+</div>`;
+
+const NO_TIMELINE_HTML = `<div data-hf-id="hf-stage" data-hf-root>
+  <div data-hf-id="hf-box"></div>
+  <script>gsap.defaults({ ease: "power1.out" });
+window.__timelines = {};</script>
+</div>`;
+
+describe("runShadowDelete", () => {
+  it("removes the element from the SDK session and reports parity", async () => {
+    const session = await openComposition(BASE_HTML);
+    runShadowDelete(session, "hf-box");
+    expect(session.getElement("hf-box")).toBeNull();
+    expect(lastShadow()).toMatchObject({ op: "delete", dispatched: true, mismatchCount: 0 });
+  });
+
+  it("reports no_hf_id when selection has no hf-id", async () => {
+    const session = await openComposition(BASE_HTML);
+    runShadowDelete(session, null);
+    expect(lastShadow()).toMatchObject({ op: "delete", dispatched: false, reason: "no_hf_id" });
+  });
+
+  it("reports cannot_dispatch when the element is not addressable", async () => {
+    const session = await openComposition(BASE_HTML);
+    runShadowDelete(session, "hf-missing");
+    expect(lastShadow()).toMatchObject({
+      op: "delete",
+      dispatched: false,
+      reason: "cannot_dispatch",
+    });
+  });
+});
+
+describe("runShadowTiming", () => {
+  it("applies timing and reports parity against the snapshot", async () => {
+    const session = await openComposition(TIMING_HTML);
+    runShadowTiming(session, "hf-clip", { start: 2, duration: 3, trackIndex: 1 });
+    const el = session.getElement("hf-clip");
+    expect(el?.start).toBe(2);
+    expect(el?.duration).toBe(3);
+    expect(el?.trackIndex).toBe(1);
+    expect(lastShadow()).toMatchObject({ op: "timing", dispatched: true, mismatchCount: 0 });
+  });
+});
+
+describe("runShadowGsapTween", () => {
+  it("dispatches add against a real timeline and reports success", async () => {
+    const session = await openComposition(GSAP_HTML);
+    runShadowGsapTween(session, {
+      kind: "add",
+      target: "hf-box",
+      tween: { method: "to", properties: { x: 100 }, duration: 0.5 },
+    });
+    expect(lastShadow()).toMatchObject({ op: "gsap", dispatched: true, mismatchCount: 0 });
+  });
+
+  it("reports cannot_dispatch (E_NO_GSAP_TIMELINE) when the script has no timeline", async () => {
+    const session = await openComposition(NO_TIMELINE_HTML);
+    runShadowGsapTween(session, {
+      kind: "add",
+      target: "hf-box",
+      tween: { method: "to", properties: { x: 100 } },
+    });
+    expect(lastShadow()).toMatchObject({
+      op: "gsap",
+      dispatched: false,
+      reason: "cannot_dispatch",
+      code: "E_NO_GSAP_TIMELINE",
+    });
+  });
+});