@hyperframes/studio 0.7.17 → 0.7.19

package/src/hooks/useDomEditSession.ts

@@ -18,6 +18,7 @@ import { useGsapScriptCommits } from "./useGsapScriptCommits";
 import { useGsapCacheVersion } from "./useGsapTweenCache";
 import { useDomEditWiring } from "./useDomEditWiring";
 import { useGsapAwareEditing } from "./useGsapAwareEditing";
+import { useStudioSelectionPublisher } from "./useStudioSelectionPublisher";
 
 // ── Types ──
 
@@ -54,6 +55,7 @@ export interface UseDomEditSessionParams {
   projectIdRef: React.MutableRefObject<string | null>;
   previewIframe: HTMLIFrameElement | null;
   refreshKey: number;
+  previewDocumentVersion: number;
   rightPanelTab: RightPanelTab;
   applyStudioManualEditsToPreviewRef: React.MutableRefObject<
     (iframe: HTMLIFrameElement) => Promise<void>
@@ -96,6 +98,7 @@ export function useDomEditSession({
   projectIdRef,
   previewIframe,
   refreshKey,
+  previewDocumentVersion,
   rightPanelTab,
   applyStudioManualEditsToPreviewRef,
   syncPreviewHistoryHotkey,
@@ -168,6 +171,15 @@ export function useDomEditSession({
     domEditSelection,
   });
 
+  useStudioSelectionPublisher({
+    projectId,
+    domEditSelection,
+    domEditSelectionRef,
+    refreshKey,
+    previewDocumentVersion,
+    refreshDomEditSelectionFromPreview,
+  });
+
   // ── GSAP cache (hoisted so both useGsapScriptCommits and useDomEditWiring share the same instance) ──
 
   const { version: gsapCacheVersion, bump: bumpGsapCache } = useGsapCacheVersion();
@@ -189,6 +201,8 @@ export function useDomEditSession({
     addKeyframe,
     addKeyframeBatch,
     removeKeyframe,
+    moveKeyframe,
+    resizeKeyframedTween,
     convertToKeyframes,
     removeAllKeyframes,
     setArcPath,
@@ -344,6 +358,9 @@ export function useDomEditSession({
     handleGsapAddKeyframe,
     handleGsapAddKeyframeBatch,
     handleGsapRemoveKeyframe,
+    handleGsapMoveKeyframeToPlayhead,
+    handleGsapMoveKeyframe,
+    handleGsapResizeKeyframedTween,
     handleGsapConvertToKeyframes,
     handleGsapRemoveAllKeyframes,
     handleResetSelectedElementKeyframes,
@@ -381,6 +398,8 @@ export function useDomEditSession({
     addKeyframe,
     addKeyframeBatch,
     removeKeyframe,
+    moveKeyframe,
+    resizeKeyframedTween,
     convertToKeyframes,
     removeAllKeyframes,
     handleDomManualEditsReset,
@@ -541,6 +560,9 @@ export function useDomEditSession({
     handleGsapAddKeyframe,
     handleGsapAddKeyframeBatch,
     handleGsapRemoveKeyframe,
+    handleGsapMoveKeyframeToPlayhead,
+    handleGsapMoveKeyframe,
+    handleGsapResizeKeyframedTween,
     handleGsapConvertToKeyframes,
     handleGsapRemoveAllKeyframes,
     handleResetSelectedElementKeyframes,

package/src/hooks/useDomEditWiring.ts

@@ -87,6 +87,19 @@ export interface UseDomEditWiringParams {
     properties: Record<string, number | string>,
   ) => Promise<void>;
   removeKeyframe: (sel: DomEditSelection, animId: string, percentage: number) => void;
+  moveKeyframe: (
+    sel: DomEditSelection,
+    animId: string,
+    fromPercentage: number,
+    toPercentage: number,
+  ) => void;
+  resizeKeyframedTween: (
+    sel: DomEditSelection,
+    animId: string,
+    position: number,
+    duration: number,
+    pctRemap: Array<{ from: number; to: number }>,
+  ) => void;
   convertToKeyframes: (
     sel: DomEditSelection,
     animId: string,
@@ -131,6 +144,8 @@ export function useDomEditWiring({
   addKeyframe,
   addKeyframeBatch,
   removeKeyframe,
+  moveKeyframe,
+  resizeKeyframedTween,
   convertToKeyframes,
   removeAllKeyframes,
   handleDomManualEditsReset,
@@ -224,6 +239,8 @@ export function useDomEditWiring({
     addKeyframe,
     addKeyframeBatch,
     removeKeyframe,
+    moveKeyframe,
+    resizeKeyframedTween,
     convertToKeyframes,
     removeAllKeyframes,
     handleDomManualEditsReset,

package/src/hooks/useDomSelection.ts

@@ -381,7 +381,10 @@ export function useDomSelection({
       if (!doc) return;
 
       const element = findElementForSelection(doc, selection, activeCompPath);
-      if (!element) return;
+      if (!element) {
+        applyDomSelection(null, { revealPanel: false });
+        return;
+      }
 
       const nextSelection = await buildDomSelectionFromTarget(element);
       if (nextSelection) {

package/src/hooks/useGsapKeyframeOps.test.tsx

@@ -0,0 +1,101 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+// Tell React this is an act-capable environment so act(...) flushes effects.
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { useGsapKeyframeOps } from "./useGsapKeyframeOps";
+
+type HookApi = ReturnType<typeof useGsapKeyframeOps>;
+
+let cleanup: (() => void) | null = null;
+afterEach(() => {
+  cleanup?.();
+  cleanup = null;
+});
+
+const selection: DomEditSelection = { id: "box", selector: "#box" } as DomEditSelection;
+
+function renderKeyframeOps(over: {
+  commitMutation: (...args: unknown[]) => Promise<unknown>;
+  trackGsapSaveFailure: (...args: unknown[]) => void;
+}) {
+  const captured: { api: HookApi | null } = { api: null };
+  function Probe() {
+    captured.api = useGsapKeyframeOps({
+      activeCompPath: "index.html",
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- test doubles
+      commitMutation: over.commitMutation as any,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- test doubles
+      commitMutationSafely: (() => {}) as any,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- test doubles
+      trackGsapSaveFailure: over.trackGsapSaveFailure as any,
+      sdkSession: null,
+      sdkDeps: null,
+    });
+    return null;
+  }
+  const container = document.createElement("div");
+  const root = createRoot(container);
+  act(() => {
+    root.render(<Probe />);
+  });
+  cleanup = () => act(() => root.unmount());
+  if (!captured.api) throw new Error("hook did not initialize");
+  return captured.api;
+}
+
+describe("useGsapKeyframeOps — resizeKeyframedTween", () => {
+  it("issues a resize-keyframed-tween mutation with the remap + window", async () => {
+    const commitMutation = vi.fn<(...args: unknown[]) => Promise<unknown>>(async () => ({
+      ok: true,
+    }));
+    const trackGsapSaveFailure = vi.fn<(...args: unknown[]) => void>();
+    const api = renderKeyframeOps({ commitMutation, trackGsapSaveFailure });
+
+    const pctRemap = [
+      { from: 0, to: 0 },
+      { from: 100, to: 100 },
+    ];
+    await act(async () => {
+      api.resizeKeyframedTween(selection, "box-to-0-opacity", 0.2, 2, pctRemap);
+    });
+
+    expect(commitMutation).toHaveBeenCalledTimes(1);
+    const [sel, mutation] = commitMutation.mock.calls[0]!;
+    expect(sel).toBe(selection);
+    expect(mutation).toEqual({
+      type: "resize-keyframed-tween",
+      animationId: "box-to-0-opacity",
+      position: 0.2,
+      duration: 2,
+      pctRemap,
+    });
+    expect(trackGsapSaveFailure).not.toHaveBeenCalled();
+  });
+
+  it("routes a rejected commit to trackGsapSaveFailure (no unhandled rejection)", async () => {
+    const error = new Error("network down");
+    const commitMutation = vi.fn<(...args: unknown[]) => Promise<unknown>>(async () => {
+      throw error;
+    });
+    const trackGsapSaveFailure = vi.fn<(...args: unknown[]) => void>();
+    const api = renderKeyframeOps({ commitMutation, trackGsapSaveFailure });
+
+    await act(async () => {
+      api.resizeKeyframedTween(selection, "box-to-0-opacity", 0.2, 2, [{ from: 100, to: 100 }]);
+      // let the rejected commit promise settle inside act
+      await Promise.resolve();
+    });
+
+    expect(trackGsapSaveFailure).toHaveBeenCalledTimes(1);
+    const [errArg, selArg, mutationArg, labelArg] = trackGsapSaveFailure.mock.calls[0]!;
+    expect(errArg).toBe(error);
+    expect(selArg).toBe(selection);
+    expect((mutationArg as { type: string }).type).toBe("resize-keyframed-tween");
+    expect(labelArg).toBe("Retime keyframe (resize tween)");
+  });
+});

package/src/hooks/useGsapKeyframeOps.ts

@@ -12,7 +12,11 @@ import {
 } from "../utils/sdkCutover";
 import type { KeyframeCacheEntry } from "../player/store/playerStore";
 import { commitKeyframeAtTimeImpl } from "./gsapKeyframeCommit";
-import { readKeyframeSnapshot, writeKeyframeCache } from "./gsapKeyframeCacheHelpers";
+import {
+  clearKeyframeCacheForElement,
+  readKeyframeSnapshot,
+  writeKeyframeCache,
+} from "./gsapKeyframeCacheHelpers";
 import type {
   CommitMutation,
   SafeGsapCommitMutation,
@@ -201,6 +205,56 @@ export function useGsapKeyframeOps({
     [activeCompPath, commitMutation, trackGsapSaveFailure, sdkSession, sdkDeps],
   );
 
+  const moveKeyframe = useCallback(
+    (
+      selection: DomEditSelection,
+      animationId: string,
+      fromPercentage: number,
+      toPercentage: number,
+    ) => {
+      const mutation = { type: "move-keyframe", animationId, fromPercentage, toPercentage };
+      // No SDK persist helper exists for retime — server path only. The post-commit
+      // updateKeyframeCacheFromParsed re-keys the diamond from the fresh parse, so no
+      // optimistic cache write is needed (mapping the tween-% to clip-% here would
+      // duplicate that math). softReload mirrors remove-keyframe.
+      void commitMutation(selection, mutation, {
+        label: `Move keyframe to ${toPercentage}%`,
+        softReload: true,
+      }).catch((error) => {
+        trackGsapSaveFailure(error, selection, mutation, `Move keyframe to ${toPercentage}%`);
+      });
+    },
+    [commitMutation, trackGsapSaveFailure],
+  );
+
+  const resizeKeyframedTween = useCallback(
+    (
+      selection: DomEditSelection,
+      animationId: string,
+      position: number,
+      duration: number,
+      pctRemap: Array<{ from: number; to: number }>,
+    ) => {
+      const mutation = {
+        type: "resize-keyframed-tween",
+        animationId,
+        position,
+        duration,
+        pctRemap,
+      };
+      // Boundary drag-to-retime: the server re-keys keyframes in place + grows the
+      // tween window, preserving _auto / per-keyframe ease / easeEach / outer ease.
+      // softReload re-keys the diamonds from the fresh parse (mirrors moveKeyframe).
+      void commitMutation(selection, mutation, {
+        label: "Retime keyframe (resize tween)",
+        softReload: true,
+      }).catch((error) => {
+        trackGsapSaveFailure(error, selection, mutation, "Retime keyframe (resize tween)");
+      });
+    },
+    [commitMutation, trackGsapSaveFailure],
+  );
+
   const convertToKeyframes = useCallback(
     async (
       selection: DomEditSelection,
@@ -233,8 +287,13 @@ export function useGsapKeyframeOps({
 
   const removeAllKeyframes = useCallback(
     async (selection: DomEditSelection, animationId: string) => {
+      const targetPath = selection.sourceFile || activeCompPath || "index.html";
+      // remove-all-keyframes collapses the tween to a static hold and the commit
+      // path doesn't return parsed animations, so the keyframe cache is never
+      // refreshed — clear it here so the timeline diamonds disappear immediately.
+      const elementId = selection.id ?? selection.selector?.match(/^#([\w-]+)/)?.[1] ?? null;
+      if (elementId) clearKeyframeCacheForElement(targetPath, elementId);
       if (sdkSession && sdkDeps) {
-        const targetPath = selection.sourceFile || activeCompPath || "index.html";
         const handled = await sdkGsapRemoveAllKeyframesPersist(
           targetPath,
           animationId,
@@ -267,6 +326,8 @@ export function useGsapKeyframeOps({
     addKeyframe,
     addKeyframeBatch,
     removeKeyframe,
+    moveKeyframe,
+    resizeKeyframedTween,
     convertToKeyframes,
     removeAllKeyframes,
     commitKeyframeAtTime,

package/src/hooks/useGsapSelectionHandlers.ts

@@ -1,6 +1,8 @@
 import { useCallback, useRef } from "react";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditing";
 import { usePlayerStore } from "../player";
+import { computeCurrentPercentage } from "./gsapDragCommit";
 import { trackStudioSaveFailure } from "../utils/studioSaveDiagnostics";
 import { trackStudioEvent } from "../utils/studioTelemetry";
 
@@ -25,6 +27,8 @@ export function useGsapSelectionHandlers({
   addKeyframe,
   addKeyframeBatch,
   removeKeyframe,
+  moveKeyframe,
+  resizeKeyframedTween,
   convertToKeyframes,
   removeAllKeyframes,
   handleDomManualEditsReset,
@@ -73,6 +77,19 @@ export function useGsapSelectionHandlers({
     properties: Record<string, number | string>,
   ) => Promise<void>;
   removeKeyframe: (sel: DomEditSelection, animId: string, percentage: number) => void;
+  moveKeyframe: (
+    sel: DomEditSelection,
+    animId: string,
+    fromPercentage: number,
+    toPercentage: number,
+  ) => void;
+  resizeKeyframedTween: (
+    sel: DomEditSelection,
+    animId: string,
+    position: number,
+    duration: number,
+    pctRemap: Array<{ from: number; to: number }>,
+  ) => void;
   convertToKeyframes: (
     sel: DomEditSelection,
     animId: string,
@@ -82,7 +99,7 @@ export function useGsapSelectionHandlers({
   removeAllKeyframes: (sel: DomEditSelection, animId: string) => void;
 
   handleDomManualEditsReset: (sel: DomEditSelection) => void;
-  selectedGsapAnimations: { id: string; keyframes?: unknown }[];
+  selectedGsapAnimations: GsapAnimation[];
 }) {
   const lastSelectionRef = useRef<DomEditSelection | null>(null);
   if (domEditSelection) lastSelectionRef.current = domEditSelection;
@@ -233,6 +250,57 @@ export function useGsapSelectionHandlers({
     [domEditSelection, removeKeyframe],
   );
 
+  const handleGsapMoveKeyframeToPlayhead = useCallback(
+    (animId: string, fromPercentage: number, selectionOverride?: DomEditSelection | null) => {
+      const sel = selectionOverride ?? domEditSelection ?? lastSelectionRef.current;
+      if (!sel) return;
+      // Retime the keyframe to the playhead, preserving its value + ease. The
+      // playhead's tween-relative percentage is the move target.
+      const anim = selectedGsapAnimations.find((a) => a.id === animId);
+      const toPercentage = computeCurrentPercentage(sel, anim);
+      trackStudioEvent("keyframe", { action: "move_to_playhead" });
+      moveKeyframe(sel, animId, fromPercentage, toPercentage);
+    },
+    [domEditSelection, selectedGsapAnimations, moveKeyframe],
+  );
+
+  const handleGsapMoveKeyframe = useCallback(
+    (
+      animId: string,
+      fromPercentage: number,
+      toPercentage: number,
+      selectionOverride?: DomEditSelection | null,
+    ) => {
+      const sel = selectionOverride ?? domEditSelection ?? lastSelectionRef.current;
+      if (!sel) return;
+      // Atomic retime: preserves the keyframe's value + per-keyframe ease. Both
+      // percentages are tween-relative (the drag handler converts the drop
+      // position before calling). No optimistic runtime hold — the soft-reload
+      // re-keys the diamond from source.
+      trackStudioEvent("keyframe", { action: "retime" });
+      moveKeyframe(sel, animId, fromPercentage, toPercentage);
+    },
+    [domEditSelection, moveKeyframe],
+  );
+
+  const handleGsapResizeKeyframedTween = useCallback(
+    (
+      animId: string,
+      position: number,
+      duration: number,
+      pctRemap: Array<{ from: number; to: number }>,
+      selectionOverride?: DomEditSelection | null,
+    ) => {
+      const sel = selectionOverride ?? domEditSelection ?? lastSelectionRef.current;
+      if (!sel) return;
+      // Boundary drag-to-retime: grows/shifts the tween window + re-keys keyframes
+      // in place. Distinct telemetry action so resize is separable from in-window move.
+      trackStudioEvent("keyframe", { action: "retime_resize" });
+      resizeKeyframedTween(sel, animId, position, duration, pctRemap);
+    },
+    [domEditSelection, resizeKeyframedTween],
+  );
+
   const handleGsapConvertToKeyframes = useCallback(
     (animId: string, resolvedFromValues?: Record<string, number | string>, duration?: number) => {
       if (!domEditSelection) return Promise.resolve();
@@ -280,6 +348,9 @@ export function useGsapSelectionHandlers({
     handleGsapAddKeyframe,
     handleGsapAddKeyframeBatch,
     handleGsapRemoveKeyframe,
+    handleGsapMoveKeyframeToPlayhead,
+    handleGsapMoveKeyframe,
+    handleGsapResizeKeyframedTween,
     handleGsapConvertToKeyframes,
     handleGsapRemoveAllKeyframes,
     handleResetSelectedElementKeyframes,

package/src/hooks/useGsapTweenCache.ts

@@ -128,7 +128,7 @@ export async function fetchParsedAnimations(
  * Fall back to the sub-comp HOST's bounds, resolved via domClipChildren (the host's
  * data-composition-src is stripped in the rendered DOM, so we can't query it).
  */
-function resolveClipTimingBasis(
+export function resolveClipTimingBasis(
   elementId: string,
   sourceFile: string,
   elements: ReadonlyArray<{
@@ -346,9 +346,16 @@ export function useGsapAnimationsForElement(
     let ease: string | undefined;
     let easeEach: string | undefined;
     for (const anim of animations) {
+      // A static position hold (only x/y, no real motion) is a `set`, not a
+      // keyframe — don't synthesize a diamond for it. Covers both `tl.set(...)`
+      // and the `tl.to({ duration: 0, immediateRender: true })` hold that
+      // remove-all-keyframes collapses to (which is otherwise shown as a stray
+      // 0% keyframe).
       if (
-        anim.method === "set" &&
-        Object.keys(anim.properties).every((k) => k === "x" || k === "y")
+        !anim.keyframes &&
+        Object.keys(anim.properties).length > 0 &&
+        Object.keys(anim.properties).every((k) => k === "x" || k === "y") &&
+        (anim.method === "set" || (anim.duration ?? 0) === 0)
       )
         continue;
       const kf = anim.keyframes ?? synthesizeFlatTweenKeyframes(anim);
@@ -454,11 +461,13 @@ export function usePopulateKeyframeCacheForFile(
       const mergedByElement = new Map<string, GsapKeyframesData>();
       for (const anim of parsed.animations) {
         if (anim.hasUnresolvedKeyframes) continue;
-        // Position-only set tweens are static holds (created by drag), not
-        // keyframed animations — skip them so they don't show timeline diamonds.
-        if (anim.method === "set") {
+        // Position-only static holds are not keyframed animations — skip them so
+        // they don't draw a timeline diamond. Covers both a `tl.set(...)` and the
+        // `tl.to({ duration: 0, immediateRender: true })` that remove-all-keyframes
+        // collapses a keyframed tween to.
+        if (!anim.keyframes && (anim.method === "set" || (anim.duration ?? 0) === 0)) {
           const propKeys = Object.keys(anim.properties).filter((k) => k !== "immediateRender");
-          if (propKeys.every((k) => k === "x" || k === "y")) {
+          if (propKeys.length > 0 && propKeys.every((k) => k === "x" || k === "y")) {
             continue;
           }
         }

package/src/hooks/useKeyframeKeyboard.ts

@@ -33,53 +33,48 @@ export function useKeyframeKeyboard({
     (e: KeyboardEvent) => {
       if (!enabled) return;
       if (isTextInput(document.activeElement)) return;
+      if (e.metaKey || e.ctrlKey) return; // never shadow browser/system combos
 
       const hasSelectedKeyframes = usePlayerStore.getState().selectedKeyframes.size > 0;
 
+      // Only consume a key we can actually act on. The fall-through matters:
+      // these keys (k/j/arrows) double as JKL playback shortcuts in
+      // usePlaybackKeyboard, so when a handler is absent we must let the event
+      // continue. When we DO act, stopImmediatePropagation prevents the playback
+      // handler from also firing (e.g. K pausing instead of adding a keyframe).
+      // The listener is registered in the capture phase so it runs first.
+      const consume = (run: () => void) => {
+        e.preventDefault();
+        e.stopImmediatePropagation();
+        run();
+      };
+
       switch (e.key.toLowerCase()) {
         case "k":
-          if (!e.metaKey && !e.ctrlKey) {
-            e.preventDefault();
-            onAddKeyframe?.();
-          }
+          if (onAddKeyframe) consume(onAddKeyframe);
           break;
         case "delete":
         case "backspace":
-          if (hasSelectedKeyframes) {
-            e.preventDefault();
-            onDeleteKeyframe?.();
-          }
+          if (onDeleteKeyframe && hasSelectedKeyframes) consume(onDeleteKeyframe);
           break;
-        case "j":
-          if (!e.metaKey && !e.ctrlKey) {
-            e.preventDefault();
-            if (e.shiftKey) onNextKeyframe?.();
-            else onPrevKeyframe?.();
-          }
+        case "j": {
+          const nav = e.shiftKey ? onNextKeyframe : onPrevKeyframe;
+          if (nav) consume(nav);
           break;
+        }
         case "h":
-          if (!e.metaKey && !e.ctrlKey && hasSelectedKeyframes) {
-            e.preventDefault();
-            onToggleHold?.();
-          }
+          if (onToggleHold && hasSelectedKeyframes) consume(onToggleHold);
           break;
         case "u":
-          if (!e.metaKey && !e.ctrlKey) {
-            e.preventDefault();
-            onToggleExpand?.();
-          }
+          if (onToggleExpand) consume(onToggleExpand);
           break;
         case "arrowleft":
-          if (hasSelectedKeyframes && !e.metaKey && !e.ctrlKey && !e.altKey) {
-            e.preventDefault();
-            onNudgeKeyframe?.(-1, e.shiftKey);
-          }
+          if (onNudgeKeyframe && hasSelectedKeyframes && !e.altKey)
+            consume(() => onNudgeKeyframe(-1, e.shiftKey));
           break;
         case "arrowright":
-          if (hasSelectedKeyframes && !e.metaKey && !e.ctrlKey && !e.altKey) {
-            e.preventDefault();
-            onNudgeKeyframe?.(1, e.shiftKey);
-          }
+          if (onNudgeKeyframe && hasSelectedKeyframes && !e.altKey)
+            consume(() => onNudgeKeyframe(1, e.shiftKey));
           break;
       }
     },
@@ -97,7 +92,9 @@ export function useKeyframeKeyboard({
 
   useEffect(() => {
     if (!enabled) return;
-    window.addEventListener("keydown", handler);
-    return () => window.removeEventListener("keydown", handler);
+    // Capture phase: run before usePlaybackKeyboard's (bubble-phase) JKL handler
+    // so an active keyframe shortcut can claim the key.
+    window.addEventListener("keydown", handler, { capture: true });
+    return () => window.removeEventListener("keydown", handler, { capture: true });
   }, [enabled, handler]);
 }

package/src/hooks/useStudioSelectionPublisher.ts

@@ -0,0 +1,102 @@
+import { useEffect, useRef, type MutableRefObject } from "react";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import { usePlayerStore } from "../player";
+import { buildStudioSelectionSnapshot } from "../utils/studioSelectionSnapshot";
+import { trackStudioEvent } from "../utils/studioTelemetry";
+
+interface UseStudioSelectionPublisherParams {
+  projectId: string | null;
+  domEditSelection: DomEditSelection | null;
+  domEditSelectionRef: MutableRefObject<DomEditSelection | null>;
+  refreshKey: number;
+  previewDocumentVersion: number;
+  refreshDomEditSelectionFromPreview: (selection: DomEditSelection) => Promise<void>;
+}
+
+function reportSelectionPublishError(error: unknown): void {
+  if (error instanceof Error && error.name === "AbortError") return;
+  const errorName = error instanceof Error ? error.name : typeof error;
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  trackStudioEvent("studio_selection_publish_failed", {
+    error_name: errorName,
+    error_message: errorMessage.slice(0, 500),
+  });
+  // eslint-disable-next-line no-console
+  console.warn("[Studio] Failed to update agent selection context", error);
+}
+
+function putSelection(projectId: string, selection: unknown, signal?: AbortSignal): Promise<void> {
+  return fetch(`/api/projects/${encodeURIComponent(projectId)}/selection`, {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ selection }),
+    signal,
+  }).then(() => undefined);
+}
+
+export function useStudioSelectionPublisher({
+  projectId,
+  domEditSelection,
+  domEditSelectionRef,
+  refreshKey,
+  previewDocumentVersion,
+  refreshDomEditSelectionFromPreview,
+}: UseStudioSelectionPublisherParams): void {
+  const lastSelectionRefreshKeyRef = useRef(refreshKey);
+  const pendingSelectionRefreshKeyRef = useRef<number | null>(null);
+
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (!projectId) return;
+    const selection = domEditSelection?.element.isConnected
+      ? buildStudioSelectionSnapshot({
+          projectId,
+          selection: domEditSelection,
+          currentTime: usePlayerStore.getState().currentTime,
+        })
+      : null;
+    const controller = new AbortController();
+    void putSelection(projectId, selection, controller.signal).catch(reportSelectionPublishError);
+    return () => controller.abort();
+  }, [domEditSelection, projectId]);
+
+  // Clear server-side agent context when Studio leaves a project. Without this,
+  // a long-running multi-project preview server can keep serving the last
+  // selected element for a project after its tab/session unmounts.
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (!projectId) return;
+    return () => {
+      void putSelection(projectId, null).catch(reportSelectionPublishError);
+    };
+  }, [projectId]);
+
+  // On external file edits, the iframe reloads while React keeps the previous
+  // DOM selection object alive. Clear the agent-facing snapshot immediately so
+  // `preview --context` never serves a detached or stale target, then let the
+  // post-load preview document refresh below re-resolve the selection if it
+  // still exists in the new document.
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (lastSelectionRefreshKeyRef.current === refreshKey) return;
+    lastSelectionRefreshKeyRef.current = refreshKey;
+    pendingSelectionRefreshKeyRef.current = domEditSelectionRef.current ? refreshKey : null;
+    if (!projectId || !domEditSelectionRef.current) return;
+    const controller = new AbortController();
+    void putSelection(projectId, null, controller.signal).catch(reportSelectionPublishError);
+    return () => controller.abort();
+  }, [domEditSelectionRef, projectId, refreshKey]);
+
+  // `refreshPreviewDocumentVersion` ticks after iframe load and shortly after.
+  // Consume one pending refresh per external reload: enough to re-resolve the
+  // selected element once the new document is queryable, without republishing
+  // the same snapshot on every follow-up 80/300ms tick.
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (pendingSelectionRefreshKeyRef.current === null) return;
+    pendingSelectionRefreshKeyRef.current = null;
+    const selection = domEditSelectionRef.current;
+    if (!selection) return;
+    void refreshDomEditSelectionFromPreview(selection);
+  }, [domEditSelectionRef, previewDocumentVersion, refreshDomEditSelectionFromPreview]);
+}