@hyperframes/studio 0.6.110 → 0.6.111

package/src/contexts/ViewModeContext.tsx

@@ -0,0 +1,98 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from "react";
+
+/**
+ * Top-level Studio view mode.
+ *
+ * `timeline` is the existing NLE/preview stage. `storyboard` replaces that stage
+ * with the storyboard contact sheet. The mode is mirrored to the `?view=` query
+ * param so it survives reloads and — importantly — so an agent can deep-link the
+ * user straight into the storyboard by navigating the tab to `?view=storyboard`.
+ */
+export type StudioViewMode = "timeline" | "storyboard";
+
+const VIEW_QUERY_PARAM = "view";
+
+function readViewModeFromUrl(): StudioViewMode {
+  if (typeof window === "undefined") return "timeline";
+  return new URLSearchParams(window.location.search).get(VIEW_QUERY_PARAM) === "storyboard"
+    ? "storyboard"
+    : "timeline";
+}
+
+function writeViewModeToUrl(mode: StudioViewMode): void {
+  if (typeof window === "undefined") return;
+  const url = new URL(window.location.href);
+  if (mode === "storyboard") {
+    url.searchParams.set(VIEW_QUERY_PARAM, "storyboard");
+  } else {
+    url.searchParams.delete(VIEW_QUERY_PARAM);
+  }
+  window.history.replaceState(window.history.state, "", url);
+}
+
+export interface ViewModeValue {
+  viewMode: StudioViewMode;
+  setViewMode: (mode: StudioViewMode) => void;
+}
+
+/**
+ * Owns the view-mode state. When `enabled` is false (storyboard flag off) the
+ * mode is pinned to `timeline` and the URL is left untouched, so the feature is
+ * fully inert until the flag is on.
+ */
+export function useViewModeState(enabled: boolean): ViewModeValue {
+  const [viewMode, setMode] = useState<StudioViewMode>(() =>
+    enabled ? readViewModeFromUrl() : "timeline",
+  );
+
+  // Reflect genuine browser back/forward between history entries with a different
+  // `?view=`. Note: our own writes use `replaceState` (below), which does NOT fire
+  // `popstate`, so this listener never sees them — `setViewMode` updates state directly.
+  // An agent deep-links by doing a full navigation to `?view=storyboard` (picked up by
+  // the mount-time read); a scripted `pushState`/`replaceState` to `?view=` would not be
+  // reflected here, by design.
+  useEffect(() => {
+    if (!enabled) return;
+    const onPopState = () => setMode(readViewModeFromUrl());
+    window.addEventListener("popstate", onPopState);
+    return () => window.removeEventListener("popstate", onPopState);
+  }, [enabled]);
+
+  const setViewMode = useCallback(
+    (mode: StudioViewMode) => {
+      if (!enabled) return;
+      setMode(mode);
+      writeViewModeToUrl(mode);
+    },
+    [enabled],
+  );
+
+  const effectiveMode = enabled ? viewMode : "timeline";
+  return useMemo(() => ({ viewMode: effectiveMode, setViewMode }), [effectiveMode, setViewMode]);
+}
+
+const ViewModeContext = createContext<ViewModeValue | null>(null);
+
+export function useViewMode(): ViewModeValue {
+  const ctx = useContext(ViewModeContext);
+  if (!ctx) throw new Error("useViewMode must be used within ViewModeProvider");
+  return ctx;
+}
+
+export function ViewModeProvider({
+  value,
+  children,
+}: {
+  value: ViewModeValue;
+  children: ReactNode;
+}) {
+  return <ViewModeContext value={value}>{children}</ViewModeContext>;
+}

package/src/hooks/gsapScriptCommitTypes.ts

@@ -2,8 +2,6 @@ import type { ParsedGsap } from "@hyperframes/core/gsap-parser";
 import type { Composition } from "@hyperframes/sdk";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import type { EditHistoryKind } from "../utils/editHistory";
-import type { ShadowGsapOp } from "../utils/sdkShadow";
-import type { ShadowKeyframeOp } from "../utils/sdkShadowGsapKeyframe";
 
 export interface MutationResult {
   ok: boolean;
@@ -28,10 +26,6 @@ export interface CommitMutationOptions {
    * (and under distinct keys) run concurrently as before.
    */
   serializeKey?: string;
-  /** Stage 7 Step 3b: typed SDK equivalent of this mutation for value-fidelity shadow. */
-  shadowGsapOp?: ShadowGsapOp;
-  /** Typed SDK equivalent of a keyframe mutation for keyframe value-fidelity shadow (gsap_keyframe). */
-  shadowKeyframeOp?: ShadowKeyframeOp;
 }
 
 export type CommitMutation = (
@@ -70,6 +64,9 @@ export interface GsapScriptCommitsParams {
   onCacheInvalidate: () => void;
   onFileContentChanged?: (path: string, content: string) => void;
   showToast: (message: string, tone?: "error" | "info") => void;
-  /** Stage 7 Step 3b: SDK session for shadow GSAP dispatch (server stays authoritative). */
+  /** Stage 7 §3.5: SDK session for routing GSAP tween ops through addGsapTween/setGsapTween/removeGsapTween. */
   sdkSession?: Composition | null;
+  writeProjectFile?: (path: string, content: string) => Promise<void>;
+  /** Resync the in-memory SDK session after a server-authoritative write. */
+  forceReloadSdkSession?: () => void;
 }

package/src/hooks/sdkSelfWriteRegistry.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it, beforeEach } from "vitest";
+import {
+  hashContent,
+  markSelfWrite,
+  isSelfWriteEcho,
+  resetSelfWriteRegistry,
+} from "./sdkSelfWriteRegistry";
+import { shouldReloadOnFileChange } from "./useSdkSession";
+
+describe("sdkSelfWriteRegistry (finding #14)", () => {
+  beforeEach(() => resetSelfWriteRegistry());
+
+  it("recognizes the echo of bytes we just wrote", () => {
+    markSelfWrite("/comp.html", "<html>A</html>");
+    expect(isSelfWriteEcho("/comp.html", "<html>A</html>")).toBe(true);
+  });
+
+  it("does NOT match different content on the same path (an undo's reverted bytes)", () => {
+    markSelfWrite("/comp.html", "<html>A</html>");
+    expect(isSelfWriteEcho("/comp.html", "<html>REVERTED</html>")).toBe(false);
+  });
+
+  it("is keyed per file — a self-write to one file can't mask a change to another", () => {
+    markSelfWrite("/a.html", "<html>A</html>");
+    expect(isSelfWriteEcho("/b.html", "<html>A</html>")).toBe(false);
+  });
+
+  it("consumes a matched entry so a later genuine external write isn't suppressed", () => {
+    markSelfWrite("/comp.html", "<html>A</html>");
+    expect(isSelfWriteEcho("/comp.html", "<html>A</html>")).toBe(true);
+    // A second arrival of identical bytes is NOT our echo — must reload.
+    expect(isSelfWriteEcho("/comp.html", "<html>A</html>")).toBe(false);
+  });
+
+  it("expires entries past the TTL so a stale self-write can't suppress forever", () => {
+    const t0 = 1_000_000;
+    markSelfWrite("/comp.html", "<html>A</html>", t0);
+    // 3 s later (> 2 s TTL) the entry is gone.
+    expect(isSelfWriteEcho("/comp.html", "<html>A</html>", t0 + 3000)).toBe(false);
+  });
+
+  it("hashes are stable and distinguish different content", () => {
+    expect(hashContent("x")).toBe(hashContent("x"));
+    expect(hashContent("x")).not.toBe(hashContent("y"));
+  });
+});
+
+describe("shouldReloadOnFileChange (finding #14)", () => {
+  beforeEach(() => resetSelfWriteRegistry());
+
+  it("suppresses the reload when content matches a registered self-write (cutover echo)", () => {
+    markSelfWrite("/comp.html", "<html>SELF</html>");
+    expect(shouldReloadOnFileChange("/comp.html", "<html>SELF</html>", true)).toBe(false);
+  });
+
+  it("reloads on an undo write even inside the suppress window (content differs)", () => {
+    // The cutover registered SELF; the undo writes REVERTED bytes within the
+    // same 2 s window. Time-only suppression dropped this; identity reloads it.
+    markSelfWrite("/comp.html", "<html>SELF</html>");
+    expect(shouldReloadOnFileChange("/comp.html", "<html>REVERTED</html>", true)).toBe(true);
+  });
+
+  it("falls back to the time window only when content is unavailable", () => {
+    expect(shouldReloadOnFileChange("/comp.html", null, true)).toBe(false);
+    expect(shouldReloadOnFileChange("/comp.html", null, false)).toBe(true);
+  });
+});

package/src/hooks/sdkSelfWriteRegistry.ts

@@ -0,0 +1,77 @@
+/**
+ * Self-write identity registry — discriminates an SDK cutover ECHO from a genuine
+ * external write (notably undo/redo) in the file-change reload-suppression path.
+ *
+ * The old suppression was purely time-based: any file-change within 2 s of the
+ * shared `domEditSaveTimestampRef` was swallowed. But BOTH an SDK cutover
+ * self-write AND an undo write set that same timestamp, so the window could not
+ * tell "the echo of the bytes I just wrote" (suppress) from "the reverted bytes
+ * an undo just wrote" (must reload). An undo that landed inside the window was
+ * silently dropped, leaving the in-memory SDK doc on stale pre-undo content.
+ *
+ * Fix: tag each cutover self-write with the CONTENT it wrote (by hash). A
+ * file-change reload is suppressed only when the new on-disk content matches a
+ * recently-registered self-write hash — i.e. it is provably our own echo. Undo
+ * writes are never registered (they don't flow through persistSdkSerialize), so
+ * their content won't match and the reload always fires. Identity, not a clock.
+ */
+
+const SELF_WRITE_TTL_MS = 2000;
+
+interface SelfWriteEntry {
+  hash: string;
+  at: number;
+}
+
+// Module-scoped: the studio process has a single SDK session lifecycle at a time
+// and persists are funnelled through one persistSdkSerialize. Keyed by file path
+// so a self-write to one file can't mask a real external change to another.
+const registry = new Map<string, SelfWriteEntry[]>();
+
+/**
+ * Stable 32-bit FNV-1a hash of content. Collisions only risk SUPPRESSING a real
+ * reload, and only within the 2 s TTL for the exact same file — negligible, and
+ * strictly safer than the prior time-only window it replaces.
+ */
+export function hashContent(content: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < content.length; i++) {
+    h ^= content.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(16);
+}
+
+function prune(entries: SelfWriteEntry[], now: number): SelfWriteEntry[] {
+  return entries.filter((e) => now - e.at < SELF_WRITE_TTL_MS);
+}
+
+/** Record that WE wrote `content` to `path` (an SDK cutover self-write). */
+export function markSelfWrite(path: string, content: string, now: number = Date.now()): void {
+  const next = prune(registry.get(path) ?? [], now);
+  next.push({ hash: hashContent(content), at: now });
+  registry.set(path, next);
+}
+
+/**
+ * True when `content` matches a self-write registered for `path` within the TTL.
+ * Consumes the matched entry so a later genuinely-external write of identical
+ * bytes isn't suppressed forever.
+ */
+export function isSelfWriteEcho(path: string, content: string, now: number = Date.now()): boolean {
+  const entries = prune(registry.get(path) ?? [], now);
+  const hash = hashContent(content);
+  const idx = entries.findIndex((e) => e.hash === hash);
+  if (idx === -1) {
+    registry.set(path, entries);
+    return false;
+  }
+  entries.splice(idx, 1);
+  registry.set(path, entries);
+  return true;
+}
+
+/** Test-only: drop all registered self-writes. */
+export function resetSelfWriteRegistry(): void {
+  registry.clear();
+}

package/src/hooks/timelineEditingHelpers.ts

@@ -97,6 +97,7 @@ export interface PersistTimelineEditInput {
   recordEdit: (input: RecordEditInput) => Promise<void>;
   domEditSaveTimestampRef: React.MutableRefObject<number>;
   pendingTimelineEditPathRef: React.MutableRefObject<Set<string>>;
+  coalesceKey?: string;
 }
 
 export async function persistTimelineEdit(input: PersistTimelineEditInput): Promise<void> {
@@ -119,6 +120,7 @@ export async function persistTimelineEdit(input: PersistTimelineEditInput): Prom
     projectId: input.projectId,
     label: input.label,
     kind: "timeline",
+    coalesceKey: input.coalesceKey,
     files: { [targetPath]: patchedContent },
     readFile: async () => originalContent,
     writeFile: input.writeProjectFile,

package/src/hooks/useAppHotkeys.ts

@@ -117,6 +117,14 @@ interface UseAppHotkeysParams {
   onDeleteSelectedKeyframes: () => void;
   onAfterUndoRedo?: () => void;
   onToggleRecording?: () => void;
+  /** Active composition path — used to decide whether undo/redo must resync the SDK session. */
+  activeCompPath?: string | null;
+  /**
+   * Force-reload the SDK session after undo/redo reverts the active comp file,
+   * bypassing the self-write suppress window. Without this, the suppress window
+   * blocks the file-change reload and the SDK session stays on pre-undo content.
+   */
+  forceReloadSdkSession?: () => void;
 }
 
 // ── Extracted keydown dispatch (pure function, no hooks) ──
@@ -302,6 +310,8 @@ export function useAppHotkeys({
   onDeleteSelectedKeyframes,
   onAfterUndoRedo,
   onToggleRecording,
+  activeCompPath,
+  forceReloadSdkSession,
 }: UseAppHotkeysParams) {
   const previewHotkeyWindowRef = useRef<Window | null>(null);
   const previewHistoryCleanupRef = useRef<(() => void) | null>(null);
@@ -349,6 +359,14 @@ export function useAppHotkeys({
       }
       if (result.ok && result.label) {
         onAfterUndoRedo?.();
+        // If the active composition was among the written files, force-reload
+        // the SDK session so its in-memory doc matches the reverted content.
+        // writeHistoryFile sets domEditSaveTimestampRef which activates the
+        // 2 s suppress window — without this call the file-change event would
+        // be swallowed and the SDK session would stay on stale pre-undo content.
+        if (activeCompPath && result.paths?.includes(activeCompPath)) {
+          forceReloadSdkSession?.();
+        }
         await syncHistoryPreviewAfterApply(result.paths);
         showToast(`${direction === "undo" ? "Undid" : "Redid"} ${result.label}`, "info");
       }
@@ -361,6 +379,8 @@ export function useAppHotkeys({
       waitForPendingDomEditSaves,
       writeHistoryFile,
       onAfterUndoRedo,
+      activeCompPath,
+      forceReloadSdkSession,
     ],
   );
 

package/src/hooks/useDomEditCommits.ts

@@ -16,9 +16,6 @@ import { useDomGeometryCommits } from "./useDomGeometryCommits";
 import { useElementLifecycleOps } from "./useElementLifecycleOps";
 import { formatFieldsSuffix } from "./gsapScriptCommitHelpers";
 
-// Re-export so existing consumers keep their import path
-export { GSAP_CSS_FALLBACK_BLOCKED_MESSAGE } from "./useDomGeometryCommits";
-
 // ── Helpers ──
 
 function formatUnsafeFieldList(fields: Array<{ path: string }>): string {
@@ -45,8 +42,6 @@ interface RecordEditInput {
   files: Record<string, { before: string; after: string }>;
 }
 
-export type { PersistDomEditOperations } from "./domEditCommitTypes";
-
 export interface UseDomEditCommitsParams {
   activeCompPath: string | null;
   previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
@@ -73,10 +68,20 @@ export interface UseDomEditCommitsParams {
     target: HTMLElement,
     options?: { preferClipAncestor?: boolean },
   ) => Promise<DomEditSelection | null>;
-  /** Stage 7 Step 3b: called after a successful server-side element patch. */
-  onDomEditPersisted?: (selection: DomEditSelection, operations: PatchOperation[]) => void;
-  /** Stage 7 Step 3b: called after a successful server-side element delete. */
-  onElementDeleted?: (selection: DomEditSelection) => void;
+  /** Resync the in-memory SDK session after a SERVER-side write (NOT the SDK
+   * path, whose session is already current) so a later SDK edit doesn't
+   * serialize the pre-write doc and revert the server's change. */
+  forceReloadSdkSession?: () => void;
+  /** Stage 7 Step 3c: called before the server-side patch path; returns true if SDK handled it. */
+  onTrySdkPersist?: (
+    selection: DomEditSelection,
+    operations: PatchOperation[],
+    originalContent: string,
+    targetPath: string,
+    options?: { label?: string; coalesceKey?: string; skipRefresh?: boolean },
+  ) => Promise<boolean>;
+  /** Stage 7 §3.1: called before the server-side delete path; returns true if SDK handled it. */
+  onTrySdkDelete?: (hfId: string, originalContent: string, targetPath: string) => Promise<boolean>;
 }
 
 export function useDomEditCommits({
@@ -97,8 +102,9 @@ export function useDomEditCommits({
   clearDomSelection,
   refreshDomEditSelectionFromPreview,
   buildDomSelectionFromTarget,
-  onDomEditPersisted,
-  onElementDeleted,
+  forceReloadSdkSession,
+  onTrySdkPersist,
+  onTrySdkDelete,
 }: UseDomEditCommitsParams) {
   const resolveImportedFontAsset = useCallback(
     (fontFamilyValue: string): ImportedFontAsset | null => {
@@ -149,6 +155,10 @@ export function useDomEditCommits({
 
       if (options?.shouldSave && !options.shouldSave()) return;
 
+      // Validate layout values BEFORE any persist path runs. The SDK cutover
+      // path (onTrySdkPersist) returns early on success, so leaving this check
+      // after it let invalid numeric values bypass the guard whenever the
+      // cutover flag was on.
       const patchTarget = buildDomEditPatchTarget(selection);
       const patchBody = { target: patchTarget, operations };
       const unsafeFields = findUnsafeDomPatchValues(patchBody);
@@ -158,6 +168,23 @@ export function useDomEditCommits({
         throw new Error(`DOM patch contains unsafe values: ${fields}`);
       }
 
+      // Skip the SDK path when prepareContent is set (e.g. @font-face injection
+      // for a custom font): sdkCutoverPersist serializes only the patched DOM
+      // and would drop the injected content. Let the server path run prepareContent.
+      if (
+        onTrySdkPersist &&
+        !options?.prepareContent &&
+        (await onTrySdkPersist(selection, operations, originalContent, targetPath, {
+          label: options?.label,
+          coalesceKey: options?.coalesceKey,
+          skipRefresh: options?.skipRefresh,
+        }))
+      ) {
+        // SDK handled it — its in-memory doc is already current, so do NOT
+        // forceReload (that would echo-reload the session we just wrote).
+        return;
+      }
+
       // Mark the save timestamp before the file write so the SSE file-change
       // handler suppresses the reload even if the event arrives before the
       // response (the server writes the file and emits SSE during the fetch).
@@ -220,7 +247,7 @@ export function useDomEditCommits({
         coalesceKey: options?.coalesceKey,
         files: { [targetPath]: { before: originalContent, after: finalContent } },
       });
-      onDomEditPersisted?.(selection, operations);
+      forceReloadSdkSession?.();
 
       if (!options?.skipRefresh) {
         reloadPreview();
@@ -234,7 +261,8 @@ export function useDomEditCommits({
       domEditSaveTimestampRef,
       reloadPreview,
       showToast,
-      onDomEditPersisted,
+      forceReloadSdkSession,
+      onTrySdkPersist,
     ],
   );
 
@@ -295,8 +323,9 @@ export function useDomEditCommits({
     projectIdRef,
     reloadPreview,
     clearDomSelection,
+    onTrySdkDelete,
+    forceReloadSdkSession,
     commitPositionPatchToHtml,
-    onElementDeleted,
   });
 
   return {

package/src/hooks/useDomEditSession.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { shouldUseSdkCutover } from "../utils/sdkCutover";
+import type { PatchOperation } from "../utils/sourcePatcher";
+
+const styleOp = (property: string, value: string): PatchOperation => ({
+  type: "inline-style",
+  property,
+  value,
+});
+
+const attrOp = (property: string, value: string): PatchOperation => ({
+  type: "attribute",
+  property,
+  value,
+});
+
+describe("shouldUseSdkCutover", () => {
+  it("returns false when flag is disabled", () => {
+    expect(shouldUseSdkCutover(false, true, "hf-abc", [styleOp("color", "red")])).toBe(false);
+  });
+
+  it("returns false when no SDK session", () => {
+    expect(shouldUseSdkCutover(true, false, "hf-abc", [styleOp("color", "red")])).toBe(false);
+  });
+
+  it("returns false when selection has no hfId", () => {
+    expect(shouldUseSdkCutover(true, true, null, [styleOp("color", "red")])).toBe(false);
+    expect(shouldUseSdkCutover(true, true, undefined, [styleOp("color", "red")])).toBe(false);
+  });
+
+  it("returns false when ops array is empty", () => {
+    expect(shouldUseSdkCutover(true, true, "hf-abc", [])).toBe(false);
+  });
+
+  it("returns true when all conditions met with supported op types", () => {
+    expect(shouldUseSdkCutover(true, true, "hf-abc", [styleOp("color", "red")])).toBe(true);
+    expect(
+      shouldUseSdkCutover(true, true, "hf-abc", [styleOp("color", "red"), attrOp("data-x", "1")]),
+    ).toBe(true);
+  });
+});

package/src/hooks/useDomEditSession.ts

@@ -1,15 +1,16 @@
-import type { Composition } from "@hyperframes/sdk";
 import type { TimelineElement } from "../player";
 import type { ImportedFontAsset } from "../components/editor/fontAssets";
 import type { EditHistoryKind } from "../utils/editHistory";
 import type { RightPanelTab } from "../utils/studioHelpers";
 import type { PatchTarget } from "../utils/sourcePatcher";
 import type { SidebarTab } from "../components/sidebar/LeftSidebar";
+import type { Composition } from "@hyperframes/sdk";
+import { sdkCutoverPersist, sdkDeletePersist } from "../utils/sdkCutover";
+import { runResolverShadow } from "../utils/sdkResolverShadow";
 import { useAskAgentModal } from "./useAskAgentModal";
 import { useDomSelection } from "./useDomSelection";
 import { usePreviewInteraction } from "./usePreviewInteraction";
 import { useDomEditCommits } from "./useDomEditCommits";
-import { runShadowDispatch, runShadowDelete } from "../utils/sdkShadow";
 import { useGsapScriptCommits } from "./useGsapScriptCommits";
 import { useGsapCacheVersion } from "./useGsapTweenCache";
 import { useDomEditWiring } from "./useDomEditWiring";
@@ -60,8 +61,8 @@ export interface UseDomEditSessionParams {
   openSourceForSelection?: (sourceFile: string, target: PatchTarget) => void;
   selectSidebarTab?: (tab: SidebarTab) => void;
   getSidebarTab?: () => SidebarTab;
-  /** Stage 7 Step 3b: SDK session for shadow dispatch parity tracking. */
   sdkSession?: Composition | null;
+  forceReloadSdkSession?: () => void;
 }
 
 // ── Hook ──
@@ -101,6 +102,7 @@ export function useDomEditSession({
   selectSidebarTab,
   getSidebarTab,
   sdkSession,
+  forceReloadSdkSession,
 }: UseDomEditSessionParams) {
   void _setRefreshKey;
   void _readProjectFile;
@@ -195,6 +197,8 @@ export function useDomEditSession({
     onFileContentChanged: updateEditingFileContent,
     showToast,
     sdkSession,
+    writeProjectFile,
+    forceReloadSdkSession,
   });
 
   // ── DOM commit handlers ──
@@ -234,10 +238,38 @@ export function useDomEditSession({
     clearDomSelection,
     refreshDomEditSelectionFromPreview,
     buildDomSelectionFromTarget,
-    onDomEditPersisted: sdkSession
-      ? (sel, ops) => runShadowDispatch(sdkSession, sel, ops)
+    forceReloadSdkSession,
+    onTrySdkPersist: sdkSession
+      ? (selection, operations, originalContent, targetPath, options) => {
+          // Resolver shadow runs regardless of the cutover flag — decoupled tripwire.
+          runResolverShadow(sdkSession, selection.hfId, operations);
+          return sdkCutoverPersist(
+            selection,
+            operations,
+            originalContent,
+            targetPath,
+            sdkSession,
+            {
+              editHistory,
+              writeProjectFile,
+              reloadPreview,
+              domEditSaveTimestampRef,
+              compositionPath: activeCompPath,
+            },
+            options,
+          );
+        }
+      : undefined,
+    onTrySdkDelete: sdkSession
+      ? (hfId, originalContent, targetPath) =>
+          sdkDeletePersist(hfId, originalContent, targetPath, sdkSession, {
+            editHistory,
+            writeProjectFile,
+            reloadPreview,
+            domEditSaveTimestampRef,
+            compositionPath: activeCompPath,
+          })
       : undefined,
-    onElementDeleted: sdkSession ? (sel) => runShadowDelete(sdkSession, sel.hfId) : undefined,
   });
 
   // ── Wiring: selection sync, GSAP cache, preview sync, selection handlers ──

package/src/hooks/useDomGeometryCommits.ts

@@ -42,15 +42,11 @@ export function useDomGeometryCommits({
 }: UseDomGeometryCommitsParams) {
   const handleDomPathOffsetCommit = useCallback(
     (selection: DomEditSelection, next: { x: number; y: number }) => {
-      const gsapBlocked = isElementGsapTargeted(previewIframeRef.current, selection.element);
-      console.log(
-        "[drag:7] handleDomPathOffsetCommit (CSS path)",
-        JSON.stringify({
-          sel: selection.id,
-          gsapBlocked,
-        }),
-      );
-      if (gsapBlocked) {
+      // ponytail: GSAP-targeted elements are blocked (no SDK position-in-script op); CSS-path
+      // elements fall through to commitPositionPatchToHtml → persistDomEditOperations →
+      // onTrySdkPersist and are already SDK-cut-over as setStyle/setAttribute (§3.3 done).
+      // Upgrade path for GSAP: add a moveElementGsap SDK op in a separate SDK PR.
+      if (isElementGsapTargeted(previewIframeRef.current, selection.element)) {
         const error = new Error(GSAP_CSS_FALLBACK_BLOCKED_MESSAGE);
         showToast(error.message, "error");
         return Promise.reject(error);