npm - @hyperframes/studio - Versions diffs - 0.6.100 → 0.6.102 - Mend

@hyperframes/studio 0.6.100 → 0.6.102

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (44) hide show

package/dist/assets/index-BITwbxi-.css +1 -0
package/dist/assets/{index-CKWBqyRd.js → index-BZKngETE.js} +1 -1
package/dist/assets/index-BzjItfjX.js +296 -0
package/dist/assets/{index-gpSohHUn.js → index-C0vMHtMH.js} +1 -1
package/dist/index.html +2 -2
package/package.json +5 -5
package/src/App.tsx +2 -1
package/src/components/editor/PropertyPanel.tsx +24 -16
package/src/components/editor/manualEditingAvailability.ts +5 -3
package/src/components/nle/NLELayout.tsx +89 -1
package/src/hooks/gsapKeyframeCacheHelpers.test.ts +121 -0
package/src/hooks/gsapKeyframeCacheHelpers.ts +48 -2
package/src/hooks/gsapScriptCommitHelpers.ts +8 -5
package/src/hooks/gsapScriptCommitTypes.ts +6 -0
package/src/hooks/gsapTargetCache.ts +65 -0
package/src/hooks/useAppHotkeys.ts +10 -0
package/src/hooks/useDomEditCommits.ts +6 -5
package/src/hooks/useDomEditSession.ts +6 -1
package/src/hooks/useDomGeometryCommits.ts +1 -36
package/src/hooks/useElementLifecycleOps.ts +5 -0
package/src/hooks/useGsapAnimationOps.ts +46 -9
package/src/hooks/useGsapScriptCommits.ts +22 -3
package/src/hooks/useGsapTweenCache.ts +10 -12
package/src/hooks/useRazorSplit.ts +3 -0
package/src/hooks/useSafeGsapCommitMutation.ts +1 -14
package/src/hooks/useSdkSession.ts +15 -12
package/src/hooks/useTimelineEditing.ts +23 -3
package/src/player/components/Timeline.tsx +31 -18
package/src/player/components/TimelineClip.tsx +3 -3
package/src/player/components/useResolvedTimelineEditCallbacks.ts +30 -0
package/src/player/hooks/useExpandedTimelineElements.test.ts +91 -0
package/src/player/hooks/useExpandedTimelineElements.ts +153 -0
package/src/player/hooks/useTimelineSyncCallbacks.ts +22 -0
package/src/player/store/playerStore.ts +22 -8
package/src/telemetry/events.test.ts +16 -1
package/src/telemetry/events.ts +15 -0
package/src/utils/blockCategories.ts +2 -2
package/src/utils/sdkShadow.test.ts +232 -2
package/src/utils/sdkShadow.ts +230 -2
package/src/utils/sdkShadowGsapFidelity.ts +208 -0
package/src/utils/studioHelpers.test.ts +25 -1
package/src/utils/studioHelpers.ts +54 -28
package/dist/assets/index-B62bDCQv.css +0 -1
package/dist/assets/index-BkT9VKwz.js +0 -296

package/dist/assets/{index-gpSohHUn.js → index-C0vMHtMH.js} RENAMED Viewed

@@ -1,4 +1,4 @@
-import{n as Qi}from"./index-BkT9VKwz.js";/*!
+import{n as Qi}from"./index-BzjItfjX.js";/*!
  * Copyright (c) 2026-present, Vanilagy and contributors
  *
  * This Source Code Form is subject to the terms of the Mozilla Public

package/dist/index.html CHANGED Viewed

@@ -5,8 +5,8 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <title>HyperFrames Studio</title>
-    <script type="module" crossorigin src="/assets/index-BkT9VKwz.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-B62bDCQv.css">
+    <script type="module" crossorigin src="/assets/index-BzjItfjX.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BITwbxi-.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.6.100",
+  "version": "0.6.102",
   "description": "",
   "repository": {
     "type": "git",
@@ -33,9 +33,9 @@
     "@phosphor-icons/react": "^2.1.10",
     "bpm-detective": "^2.0.5",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.6.100",
-    "@hyperframes/sdk": "0.6.100",
-    "@hyperframes/player": "0.6.100"
+    "@hyperframes/core": "0.6.102",
+    "@hyperframes/player": "0.6.102",
+    "@hyperframes/sdk": "0.6.102"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -49,7 +49,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.6.100"
+    "@hyperframes/producer": "0.6.102"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx CHANGED Viewed

@@ -175,6 +175,7 @@ export function StudioApp() {
     reloadPreview: () => setRefreshKey((k) => k + 1),
     pendingTimelineEditPathRef,
   });
+  const sdkSession = useSdkSession(projectId, activeCompPath);
   const timelineEditing = useTimelineEditing({
     projectId,
     activeCompPath,
@@ -188,6 +189,7 @@ export function StudioApp() {
     pendingTimelineEditPathRef,
     uploadProjectFiles: fileManager.uploadProjectFiles,
     isRecordingRef: isGestureRecordingRef,
+    sdkSession,
   });
   const {
     activeBlockParams,
@@ -267,7 +269,6 @@ export function StudioApp() {
     () => leftSidebarRef.current?.getTab() ?? "compositions",
     [],
   );
-  const sdkSession = useSdkSession(projectId, activeCompPath);
   const domEditSession = useDomEditSession({
     projectId,
     activeCompPath,

package/src/components/editor/PropertyPanel.tsx CHANGED Viewed

@@ -1,4 +1,4 @@
-import { memo, useEffect, useRef, useState } from "react";
+import { memo, useEffect, useMemo, useRef, useState } from "react";
 import { Eye, Layers, Move, X } from "../../icons/SystemIcons";
 import { useStudioShellContext } from "../../contexts/StudioContext";
 import { readStudioBoxSize, readStudioPathOffset, readStudioRotation } from "./manualEdits";
@@ -111,6 +111,29 @@ export const PropertyPanel = memo(function PropertyPanel({
   const cacheElementKey = element?.id ?? element?.selector ?? "";
   const cacheEntry = usePlayerStore((s) => s.keyframeCache.get(cacheElementKey));
+  const iframeRef = previewIframeRef ?? { current: null };
+  const gsapAnimIdForMemo = element
+    ? (gsapAnimations?.find((a: { keyframes?: unknown }) => a.keyframes)?.id ??
+      gsapAnimations?.[0]?.id ??
+      null)
+    : null;
+  const gsapRuntimeValues = useMemo(
+    () =>
+      element
+        ? readGsapRuntimeValuesForPanel(gsapAnimIdForMemo, gsapAnimations, element, iframeRef)
+        : null,
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- iframeRef is stable; currentTime drives re-reads during playback
+    [gsapAnimIdForMemo, gsapAnimations, element, currentTime],
+  );
+  const gsapBorderRadius = useMemo(
+    () =>
+      element
+        ? readGsapBorderRadiusForPanel(gsapRuntimeValues, gsapAnimations, element, iframeRef)
+        : null,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [gsapRuntimeValues, gsapAnimations, element, currentTime],
+  );
   if (!element) {
     return (
       <div className="flex h-full flex-col bg-neutral-900">
@@ -194,21 +217,6 @@ export const PropertyPanel = memo(function PropertyPanel({
     return gsapAnimId ?? "";
   };
-  // Read ALL GSAP-interpolated values at the current seek time.
-  const gsapRuntimeValues = readGsapRuntimeValuesForPanel(
-    gsapAnimId,
-    gsapAnimations,
-    element,
-    previewIframeRef ?? { current: null },
-  );
-  const gsapBorderRadius = readGsapBorderRadiusForPanel(
-    gsapRuntimeValues,
-    gsapAnimations,
-    element,
-    previewIframeRef ?? { current: null },
-  );
   const displayX = gsapRuntimeValues?.x ?? manualOffset.x;
   const displayY = gsapRuntimeValues?.y ?? manualOffset.y;
   const displayW = gsapRuntimeValues?.width ?? resolvedWidth;

package/src/components/editor/manualEditingAvailability.ts CHANGED Viewed

@@ -73,7 +73,7 @@ export const STUDIO_KEYFRAMES_ENABLED = resolveStudioBooleanEnvFlag(
 export const STUDIO_RAZOR_TOOL_ENABLED = resolveStudioBooleanEnvFlag(
   env,
   ["VITE_STUDIO_ENABLE_RAZOR_TOOL", "VITE_STUDIO_RAZOR_TOOL_ENABLED"],
-  false,
+  true,
 );
 // When disabled (the default), drag/resize/rotate commits always take the CSS
@@ -90,11 +90,13 @@ export const STUDIO_PREVIEW_SELECTION_ENABLED = STUDIO_INSPECTOR_PANELS_ENABLED;
 // Stage 7 Step 3b: shadow dispatch parity mode — dispatches ops to the SDK
 // session alongside the server patch path and logs mismatches via telemetry.
-// Default false in production; enable via VITE_STUDIO_SDK_SHADOW_ENABLED=true.
+// Default on: server stays authoritative (no user-visible change), so we want
+// the sdk_shadow_dispatch parity signal from all traffic. Disable via
+// VITE_STUDIO_SDK_SHADOW_ENABLED=false.
 export const STUDIO_SDK_SHADOW_ENABLED = resolveStudioBooleanEnvFlag(
   env,
   ["VITE_STUDIO_SDK_SHADOW_ENABLED"],
-  false,
+  true,
 );
 export const STUDIO_MANUAL_EDITING_DISABLED_TITLE = "Manual editing is temporarily disabled";

package/src/components/nle/NLELayout.tsx CHANGED Viewed

@@ -10,10 +10,13 @@ import {
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { useTimelinePlayer, PlayerControls, Timeline, usePlayerStore } from "../../player";
 import type { TimelineElement } from "../../player";
+import type { BlockedTimelineEditIntent } from "../../player/components/timelineEditing";
 import { NLEPreview } from "./NLEPreview";
 import { CompositionBreadcrumb } from "./CompositionBreadcrumb";
 import { usePreviewBlockDrop } from "./usePreviewBlockDrop";
 import { useCompositionStack } from "./useCompositionStack";
+import { useTimelineEditContext } from "../../contexts/TimelineEditContext";
+import { trackStudioExpandedClipEdit } from "../../telemetry/events";
 import {
   TIMELINE_TOGGLE_SHORTCUT_LABEL,
   getTimelineToggleTitle,
@@ -58,6 +61,7 @@ interface NLELayoutProps {
     blockName: string,
     position: { left: number; top: number },
   ) => Promise<void> | void;
+  onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
   onSelectTimelineElement?: (element: TimelineElement | null) => void;
   /** Exposes the compIdToSrc map for parent components (e.g., useRenderClipContent) */
   onCompIdToSrcChange?: (map: Map<string, string>) => void;
@@ -103,6 +107,7 @@ export const NLELayout = memo(function NLELayout({
   onAssetDrop,
   onBlockDrop,
   onPreviewBlockDrop,
+  onBlockedEditAttempt,
   onSelectTimelineElement,
   onCompIdToSrcChange,
   timelineVisible,
@@ -175,6 +180,7 @@ export const NLELayout = memo(function NLELayout({
   const handleDrillDown = useCallback(
     (element: TimelineElement) => {
       if (!element.compositionSrc) return;
+      usePlayerStore.getState().setSelectedElementId(null);
       // Check compIdToSrc map first; then scan iframe DOM; then fall through to drillDown
       const compId = element.id;
       let resolvedPath = compIdToSrc.get(compId);
@@ -202,6 +208,73 @@ export const NLELayout = memo(function NLELayout({
     [compIdToSrc, drillDown, iframeRef_],
   );
+  // Move/resize/split come from the timeline edit context, not props — the
+  // wrappers below intercept expanded clips and must call the *real* handlers.
+  // (Delete is a direct prop; it stays that way.)
+  const { onMoveElement, onResizeElement, onSplitElement } = useTimelineEditContext();
+  // An expanded sub-comp child reaches the normal edit handlers in its own
+  // local coordinates: addressed by its real DOM id, with timeline time rebased
+  // onto the sub-comp it lives in. The handlers then save + reloadPreview exactly
+  // as they do for top-level clips — no separate live-DOM path.
+  const toLocalElement = useCallback(
+    (element: TimelineElement, basis: number): TimelineElement => ({
+      ...element,
+      id: element.domId ?? element.id,
+      start: element.start - basis,
+    }),
+    [],
+  );
+  const handleMoveElement = useCallback(
+    (element: TimelineElement, updates: Pick<TimelineElement, "start" | "track">) => {
+      const basis = element.expandedParentStart;
+      if (basis === undefined) return onMoveElement?.(element, updates);
+      trackStudioExpandedClipEdit({ action: "move" });
+      onMoveElement?.(toLocalElement(element, basis), {
+        ...updates,
+        start: Math.max(0, updates.start - basis),
+      });
+    },
+    [onMoveElement, toLocalElement],
+  );
+  const handleResizeElement = useCallback(
+    (
+      element: TimelineElement,
+      updates: Pick<TimelineElement, "start" | "duration" | "playbackStart">,
+    ) => {
+      const basis = element.expandedParentStart;
+      if (basis === undefined) return onResizeElement?.(element, updates);
+      trackStudioExpandedClipEdit({ action: "resize" });
+      onResizeElement?.(toLocalElement(element, basis), {
+        ...updates,
+        start: Math.max(0, updates.start - basis),
+      });
+    },
+    [onResizeElement, toLocalElement],
+  );
+  const handleDeleteElement = useCallback(
+    (element: TimelineElement) => {
+      const basis = element.expandedParentStart;
+      if (basis === undefined) return onDeleteElement?.(element);
+      trackStudioExpandedClipEdit({ action: "delete" });
+      return onDeleteElement?.(toLocalElement(element, basis));
+    },
+    [onDeleteElement, toLocalElement],
+  );
+  const handleSplitElement = useCallback(
+    (element: TimelineElement, splitTime: number) => {
+      const basis = element.expandedParentStart;
+      if (basis === undefined) return onSplitElement?.(element, splitTime);
+      trackStudioExpandedClipEdit({ action: "split" });
+      return onSplitElement?.(toLocalElement(element, basis), Math.max(0, splitTime - basis));
+    },
+    [onSplitElement, toLocalElement],
+  );
   // Composition ID → file path map from raw index.html
   const compIdToSrcRef = useRef(compIdToSrc);
   compIdToSrcRef.current = compIdToSrc;
@@ -356,6 +429,17 @@ export const NLELayout = memo(function NLELayout({
         <div
           className="flex-1 min-h-0 relative"
           data-preview-pan-surface="true"
+          onPointerDown={(e) => {
+            const el = iframeRef.current?.parentElement ?? iframeRef.current;
+            if (!el) return;
+            const rect = el.getBoundingClientRect();
+            const inside =
+              e.clientX >= rect.left &&
+              e.clientX <= rect.right &&
+              e.clientY >= rect.top &&
+              e.clientY <= rect.bottom;
+            if (!inside) onSelectTimelineElement?.(null);
+          }}
           onDragOver={handlePreviewDragOver}
           onDragLeave={handlePreviewDragLeave}
           onDrop={handlePreviewDrop}
@@ -429,9 +513,13 @@ export const NLELayout = memo(function NLELayout({
                 onDrillDown={handleDrillDown}
                 renderClipContent={renderClipContent}
                 onFileDrop={onFileDrop}
-                onDeleteElement={onDeleteElement}
+                onDeleteElement={handleDeleteElement}
                 onAssetDrop={onAssetDrop}
                 onBlockDrop={onBlockDrop}
+                onMoveElement={handleMoveElement}
+                onResizeElement={handleResizeElement}
+                onBlockedEditAttempt={onBlockedEditAttempt}
+                onSplitElement={handleSplitElement}
                 onSelectElement={onSelectTimelineElement}
               />
             </div>

package/src/hooks/gsapKeyframeCacheHelpers.test.ts ADDED Viewed

@@ -0,0 +1,121 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { usePlayerStore, type KeyframeCacheEntry } from "../player/store/playerStore";
+import {
+  clearKeyframeCacheForElement,
+  clearKeyframeCacheForFile,
+  updateKeyframeCacheFromParsed,
+} from "./gsapKeyframeCacheHelpers";
+const entry = (): KeyframeCacheEntry => ({
+  format: "percentage",
+  keyframes: [{ percentage: 0, properties: { x: 0 } }],
+});
+const seed = (key: string) => usePlayerStore.getState().setKeyframeCache(key, entry());
+const cache = () => usePlayerStore.getState().keyframeCache;
+const animWithKeyframes = (id: string): GsapAnimation => ({
+  id,
+  targetSelector: `#${id}`,
+  method: "to",
+  position: 0,
+  properties: {},
+  duration: 1,
+  resolvedStart: 0,
+  propertyGroup: "position",
+  keyframes: { format: "percentage", keyframes: [{ percentage: 50, properties: { x: 100 } }] },
+});
+beforeEach(() => {
+  usePlayerStore.setState({ keyframeCache: new Map(), elements: [] });
+});
+describe("clearKeyframeCacheForElement", () => {
+  it("drops the prefixed, index.html fallback, and bare key for a non-index source", () => {
+    seed("comp.html#box");
+    seed("index.html#box");
+    seed("box");
+    clearKeyframeCacheForElement("comp.html", "box");
+    expect(cache().has("comp.html#box")).toBe(false);
+    expect(cache().has("index.html#box")).toBe(false);
+    // The bare key is what PropertyPanel's keyframe nav reads (element.id), so
+    // it must be cleared too, not just the prefixed variants.
+    expect(cache().has("box")).toBe(false);
+  });
+  it("drops the prefixed and bare key for an index.html source", () => {
+    seed("index.html#hero");
+    seed("hero");
+    clearKeyframeCacheForElement("index.html", "hero");
+    expect(cache().has("index.html#hero")).toBe(false);
+    expect(cache().has("hero")).toBe(false);
+  });
+  it("leaves other elements' keys untouched", () => {
+    seed("index.html#box");
+    seed("box");
+    seed("index.html#other");
+    seed("other");
+    clearKeyframeCacheForElement("index.html", "box");
+    expect(cache().has("index.html#other")).toBe(true);
+    expect(cache().has("other")).toBe(true);
+  });
+});
+describe("clearKeyframeCacheForFile", () => {
+  it("clears the prefixed, fallback, and bare keys for every element of the file", () => {
+    seed("comp.html#a");
+    seed("index.html#a");
+    seed("a");
+    seed("comp.html#b");
+    seed("b");
+    clearKeyframeCacheForFile("comp.html");
+    for (const key of ["comp.html#a", "index.html#a", "a", "comp.html#b", "b"]) {
+      expect(cache().has(key)).toBe(false);
+    }
+  });
+  it("leaves entries that belong to a different source file", () => {
+    seed("comp.html#a");
+    seed("a");
+    seed("other.html#z");
+    seed("z");
+    clearKeyframeCacheForFile("comp.html");
+    expect(cache().has("other.html#z")).toBe(true);
+    expect(cache().has("z")).toBe(true);
+  });
+});
+describe("updateKeyframeCacheFromParsed", () => {
+  it("clears the bare key when the selected element no longer has keyframes", () => {
+    // Element previously had keyframes, so a bare entry exists (writes set both).
+    seed("index.html#box");
+    seed("box");
+    // A mutation leaves #box without any keyframes in the parsed animations.
+    updateKeyframeCacheFromParsed([], "index.html", "box", {});
+    expect(cache().has("index.html#box")).toBe(false);
+    // Without the bare-key clear this assertion fails: the stale entry survives
+    // and PropertyPanel keeps rendering the removed keyframes.
+    expect(cache().has("box")).toBe(false);
+  });
+  it("still writes the bare key for elements that have keyframes", () => {
+    updateKeyframeCacheFromParsed([animWithKeyframes("hero")], "index.html", "hero", {});
+    expect(cache().has("index.html#hero")).toBe(true);
+    expect(cache().has("hero")).toBe(true);
+  });
+});

package/src/hooks/gsapKeyframeCacheHelpers.ts CHANGED Viewed

@@ -67,8 +67,54 @@ export function updateKeyframeCacheFromParsed(
     (mutation as { targetSelector?: string }).targetSelector?.match(/^#([\w-]+)/)?.[1] ??
     selectionId;
   if (targetId && !idsWithKeyframes.has(targetId)) {
-    setKeyframeCache(`${targetPath}#${targetId}`, undefined);
-    if (targetPath !== "index.html") setKeyframeCache(`index.html#${targetId}`, undefined);
+    clearKeyframeCacheForElement(targetPath, targetId);
+  }
+}
+/**
+ * Clear every keyframe-cache key variant written for an element: the
+ * source-prefixed key, the index.html fallback, and the bare element id.
+ * Writes set all three (see updateKeyframeCacheFromParsed and
+ * usePopulateKeyframeCacheForFile). PropertyPanel's keyframe nav reads the bare
+ * id directly (`element.id`), and other consumers (timeline diamonds, the
+ * preview overlay) fall back to the bare id when an element has no
+ * source-prefixed key — so a clear that drops only the prefixed keys leaves the
+ * bare entry behind and those readers keep showing keyframes the element no
+ * longer has. Each delete is guarded by `has` so an absent key doesn't allocate
+ * a new cache map and re-render every subscriber.
+ */
+export function clearKeyframeCacheForElement(sourceFile: string, elementId: string): void {
+  const { keyframeCache, setKeyframeCache } = usePlayerStore.getState();
+  const keys =
+    sourceFile === "index.html"
+      ? [`index.html#${elementId}`, elementId]
+      : [`${sourceFile}#${elementId}`, `index.html#${elementId}`, elementId];
+  for (const key of keys) {
+    if (keyframeCache.has(key)) setKeyframeCache(key, undefined);
+  }
+}
+/**
+ * Clear every cached element of `sourceFile` before a full re-scan repopulates
+ * it. Collects the element ids that currently have a prefixed or index.html
+ * fallback key for the file and drops each through clearKeyframeCacheForElement
+ * so the bare key goes too — an element whose keyframes were removed (and so is
+ * absent from the re-scan) leaves no stale bare entry behind.
+ */
+export function clearKeyframeCacheForFile(sourceFile: string): void {
+  const { keyframeCache } = usePlayerStore.getState();
+  const sfPrefix = `${sourceFile}#`;
+  const fallbackPrefix = "index.html#";
+  const ids = new Set<string>();
+  for (const key of keyframeCache.keys()) {
+    const matchesFile =
+      key.startsWith(sfPrefix) || (sourceFile !== "index.html" && key.startsWith(fallbackPrefix));
+    if (!matchesFile) continue;
+    const hashIdx = key.indexOf("#");
+    if (hashIdx !== -1) ids.add(key.slice(hashIdx + 1));
+  }
+  for (const id of ids) {
+    clearKeyframeCacheForElement(sourceFile, id);
   }
 }

package/src/hooks/gsapScriptCommitHelpers.ts CHANGED Viewed

@@ -37,6 +37,13 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }
+export function formatFieldsSuffix(rawFields: unknown): string {
+  const fields = Array.isArray(rawFields)
+    ? rawFields.filter((f): f is string => typeof f === "string")
+    : [];
+  return fields.length > 0 ? ` (${fields.join(", ")})` : "";
+}
 export async function readJsonResponseBody(res: Response): Promise<unknown> {
   const contentType = res.headers.get("content-type") ?? "";
   if (!contentType.includes("application/json")) {
@@ -55,14 +62,10 @@ function formatGsapMutationHttpErrorMessage(statusCode: number, body: unknown):
 export function formatGsapMutationRejectionToast(error: GsapMutationHttpError): string {
   const body = error.responseBody;
   if (isRecord(body)) {
-    const fields = Array.isArray(body.fields)
-      ? body.fields.filter((field): field is string => typeof field === "string")
-      : [];
-    const suffix = fields.length > 0 ? ` (${fields.join(", ")})` : "";
     return `Couldn't save animation: ${formatGsapMutationHttpErrorMessage(
       error.statusCode,
       body,
-    )}${suffix}`;
+    )}${formatFieldsSuffix(body.fields)}`;
   }
   return `Couldn't save animation: ${error.message}`;
 }

package/src/hooks/gsapScriptCommitTypes.ts CHANGED Viewed

@@ -1,6 +1,8 @@
 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";
 export interface MutationResult {
   ok: boolean;
@@ -17,6 +19,8 @@ export interface CommitMutationOptions {
   softReload?: boolean;
   skipReload?: boolean;
   beforeReload?: () => void;
+  /** Stage 7 Step 3b: typed SDK equivalent of this mutation for value-fidelity shadow. */
+  shadowGsapOp?: ShadowGsapOp;
 }
 export type CommitMutation = (
@@ -55,4 +59,6 @@ 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). */
+  sdkSession?: Composition | null;
 }

package/src/hooks/gsapTargetCache.ts ADDED Viewed

@@ -0,0 +1,65 @@
+import { STUDIO_GSAP_DRAG_INTERCEPT_ENABLED } from "../components/editor/manualEditingAvailability";
+type TimelineLike = { getChildren?: (nested: boolean) => Array<{ targets?: () => Element[] }> };
+let _gsapCachedTimelines: Record<string, TimelineLike> | undefined;
+let _gsapTargetIds: Set<string> | undefined;
+let _gsapTargetNodes: WeakSet<Element> | undefined;
+function addTargetsFromTimeline(tl: TimelineLike, ids: Set<string>, nodes: WeakSet<Element>): void {
+  const children = tl.getChildren?.(true);
+  if (!children) return;
+  for (const child of children) {
+    const targets = child.targets?.();
+    if (!targets) continue;
+    for (const t of targets) {
+      nodes.add(t);
+      if (t.id) ids.add(t.id);
+    }
+  }
+}
+function collectGsapTargets(timelines: Record<string, TimelineLike>): {
+  ids: Set<string>;
+  nodes: WeakSet<Element>;
+} {
+  const ids = new Set<string>();
+  const nodes = new WeakSet<Element>();
+  for (const tl of Object.values(timelines)) {
+    if (!tl) continue;
+    try {
+      addTargetsFromTimeline(tl, ids, nodes);
+    } catch {
+      /* teardown race */
+    }
+  }
+  return { ids, nodes };
+}
+function readTimelines(iframe: HTMLIFrameElement | null): Record<string, TimelineLike> | undefined {
+  if (!iframe?.contentWindow) return undefined;
+  try {
+    return (iframe.contentWindow as Window & { __timelines?: Record<string, TimelineLike> })
+      .__timelines;
+  } catch {
+    return undefined;
+  }
+}
+export function isElementGsapTargeted(
+  iframe: HTMLIFrameElement | null,
+  element: HTMLElement,
+): boolean {
+  if (!STUDIO_GSAP_DRAG_INTERCEPT_ENABLED) return false;
+  const timelines = readTimelines(iframe);
+  if (!timelines) return false;
+  if (timelines !== _gsapCachedTimelines) {
+    const cache = collectGsapTargets(timelines);
+    _gsapTargetIds = cache.ids;
+    _gsapTargetNodes = cache.nodes;
+    _gsapCachedTimelines = timelines;
+  }
+  return _gsapTargetNodes!.has(element) || !!(element.id && _gsapTargetIds!.has(element.id));
+}

package/src/hooks/useAppHotkeys.ts CHANGED Viewed

@@ -136,6 +136,7 @@ interface HotkeyCallbacks {
   onToggleRecording?: () => void;
   leftSidebarRef: React.RefObject<LeftSidebarHandle | null>;
   domEditSelectionRef: React.MutableRefObject<DomEditSelection | null>;
+  showToast: (message: string, tone?: "error" | "info") => void;
 }
 function dispatchModifierKey(event: KeyboardEvent, key: string, cb: HotkeyCallbacks): boolean {
@@ -205,6 +206,14 @@ function dispatchPlainKey(event: KeyboardEvent, key: string, cb: HotkeyCallbacks
         void cb.handleTimelineElementSplit(el, currentTime);
         return;
       }
+      // Expanded sub-comp children carry a qualified `sourceFile#id` selection
+      // that isn't in the raw `elements` list, so the s-key can't resolve them.
+      // Nudge toward the razor tool instead of failing silently.
+      if (!el && selectedElementId.includes("#")) {
+        event.preventDefault();
+        cb.showToast("Use the razor tool (B) to split clips inside a sub-composition", "info");
+        return;
+      }
     }
   }
@@ -376,6 +385,7 @@ export function useAppHotkeys({
     onToggleRecording,
     leftSidebarRef,
     domEditSelectionRef,
+    showToast,
   };
   // ── Keydown dispatch ──

package/src/hooks/useDomEditCommits.ts CHANGED Viewed

@@ -14,6 +14,7 @@ import { useDomEditPositionPatchCommit } from "./useDomEditPositionPatchCommit";
 import { useDomEditTextCommits } from "./useDomEditTextCommits";
 import { useDomGeometryCommits } from "./useDomGeometryCommits";
 import { useElementLifecycleOps } from "./useElementLifecycleOps";
+import { formatFieldsSuffix } from "./gsapScriptCommitHelpers";
 // ── Helpers ──
@@ -31,11 +32,7 @@ async function readErrorResponseBody(
 function formatPatchRejectionMessage(body: { error?: string; fields?: string[] } | null): string {
   if (!body?.error) return "Couldn't save edit";
-  const fields = Array.isArray(body.fields)
-    ? body.fields.filter((field): field is string => typeof field === "string")
-    : [];
-  const suffix = fields.length > 0 ? ` (${fields.join(", ")})` : "";
-  return `Couldn't save edit: ${body.error}${suffix}`;
+  return `Couldn't save edit: ${body.error}${formatFieldsSuffix(body.fields)}`;
 }
 interface RecordEditInput {
@@ -73,6 +70,8 @@ export interface UseDomEditCommitsParams {
   ) => 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;
 }
 export function useDomEditCommits({
@@ -94,6 +93,7 @@ export function useDomEditCommits({
   refreshDomEditSelectionFromPreview,
   buildDomSelectionFromTarget,
   onDomEditPersisted,
+  onElementDeleted,
 }: UseDomEditCommitsParams) {
   const resolveImportedFontAsset = useCallback(
     (fontFamilyValue: string): ImportedFontAsset | null => {
@@ -290,6 +290,7 @@ export function useDomEditCommits({
     reloadPreview,
     clearDomSelection,
     commitPositionPatchToHtml,
+    onElementDeleted,
   });
   return {