@hyperframes/studio 0.8.24 → 0.8.26

package/src/webmcp/StudioAgentTools.tsx

@@ -1,9 +1,49 @@
-import { useCallback, useMemo } from "react";
+import { useCallback, useEffect, useMemo } from "react";
 import { useDomEditActionsContext, useDomEditSelectionContext } from "../contexts/DomEditContext";
 import { useStudioShellContext } from "../contexts/StudioContext";
 import { usePlayerStore } from "../player";
 import { useStudioAgentTools, type StudioAgentToolsDeps } from "./useStudioAgentTools";
-import type { StudioLookSnapshot } from "./tools/lookTools";
+import { collectStudioLookScene, type StudioLookSnapshot } from "./tools/lookTools";
+import { studioEditLifecycle } from "./writeCoordinator";
+import { findElementForSelection } from "../components/editor/domEditingElement";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import {
+  applyStudioBoxSizeDraft,
+  captureStudioBoxSize,
+  restoreStudioBoxSize,
+} from "../components/editor/manualEdits";
+
+export function readLiveSelectionBox(
+  doc: Document | null | undefined,
+  selection: DomEditSelection,
+  activeCompositionPath: string | null,
+) {
+  const liveElement = doc
+    ? findElementForSelection(doc, selection, activeCompositionPath)
+    : selection.element;
+  if (!liveElement) throw new Error("the target is missing from the current Studio preview");
+  const rect = liveElement.getBoundingClientRect();
+  return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+}
+
+type ResizeCommit = (
+  selection: DomEditSelection,
+  next: { width: number; height: number },
+  offset?: { x: number; y: number },
+  restore?: () => void,
+) => Promise<void>;
+
+export function resizeSelectionFromAgent(
+  selection: DomEditSelection,
+  next: { width: number; height: number },
+  commit: ResizeCommit,
+): Promise<void> {
+  const previous = captureStudioBoxSize(selection.element);
+  applyStudioBoxSizeDraft(selection.element, next);
+  return commit(selection, next, undefined, () => {
+    restoreStudioBoxSize(selection.element, previous);
+  });
+}
 
 /**
  * Mounts Studio's WebMCP tool surface. Renders nothing.
@@ -20,6 +60,7 @@ export function StudioAgentTools() {
   const { projectId, activeCompPath, editHistory, writeBlockedReason } = useStudioShellContext();
   const {
     domEditSelection,
+    activeGroupElement,
     selectedGsapAnimations,
     gsapMultipleTimelines,
     gsapUnsupportedTimelinePattern,
@@ -28,8 +69,8 @@ export function StudioAgentTools() {
     previewIframeRef,
     buildDomSelectionFromTarget,
     applyDomSelection,
-    handleDomTextCommit,
-    handleDomStyleCommit,
+    handleDomTextCommitForSelection,
+    handleDomStyleCommitForSelection,
     handleDomPathOffsetCommit,
     handleDomBoxSizeCommit,
     handleDomRotationCommit,
@@ -37,8 +78,14 @@ export function StudioAgentTools() {
     handleGsapUpdateMeta,
     handleGsapAddKeyframeBatch,
     handleGsapDeleteAnimation,
+    getGsapAnimationsForSelection,
   } = useDomEditActionsContext();
 
+  useEffect(() => {
+    studioEditLifecycle.activateProject(projectId);
+    return () => studioEditLifecycle.reset();
+  }, [projectId]);
+
   const getSnapshot = useCallback((): StudioLookSnapshot => {
     const player = usePlayerStore.getState();
     return {
@@ -48,6 +95,11 @@ export function StudioAgentTools() {
       duration: player.duration,
       isPlaying: player.isPlaying,
       elements: player.elements,
+      scene: collectStudioLookScene(
+        previewIframeRef.current?.contentDocument ?? null,
+        activeCompPath,
+        activeGroupElement,
+      ),
       selection: domEditSelection,
       selectionAnimationCount: selectedGsapAnimations.length,
       history: {
@@ -57,13 +109,21 @@ export function StudioAgentTools() {
         redoLabel: editHistory.redoLabel ?? null,
       },
     };
-  }, [projectId, activeCompPath, domEditSelection, selectedGsapAnimations, editHistory]);
+  }, [
+    projectId,
+    activeCompPath,
+    domEditSelection,
+    activeGroupElement,
+    selectedGsapAnimations,
+    editHistory,
+    previewIframeRef,
+  ]);
 
   const deps = useMemo<StudioAgentToolsDeps>(
     () => ({
       getSnapshot,
       getPreviewDocument: () => previewIframeRef.current?.contentDocument ?? null,
-      buildSelection: (element) => buildDomSelectionFromTarget(element),
+      buildSelection: (element) => buildDomSelectionFromTarget(element, { exactTarget: true }),
       applySelection: (selection) => applyDomSelection(selection, { revealPanel: true }),
       requestSeek: (time) => usePlayerStore.getState().requestSeek(time),
       readPlayhead: () => {
@@ -90,22 +150,29 @@ export function StudioAgentTools() {
       wait: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
       getCurrentSelection: () => domEditSelection,
       getWriteBlockedReason: () => writeBlockedReason,
-      setText: (value, fieldKey) => handleDomTextCommit(value, fieldKey),
-      setStyle: (property, value) => handleDomStyleCommit(property, value),
+      setText: (selection, value, fieldKey) =>
+        handleDomTextCommitForSelection(selection, value, fieldKey),
+      setStyle: (selection, property, value) =>
+        handleDomStyleCommitForSelection(selection, property, value),
       // Measured, not authored: the tool compares this before and after to
-      // tell a real change from a handler that did nothing and resolved.
-      readBox: (selection) => {
-        const rect = selection.element.getBoundingClientRect();
-        return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
-      },
+      // tell a real change from a handler that did nothing and resolved. A
+      // successful commit may replace the preview document, so re-resolve the
+      // source-safe selection instead of measuring its detached old node.
+      readBox: (selection) =>
+        readLiveSelectionBox(previewIframeRef.current?.contentDocument, selection, activeCompPath),
       moveTo: (selection, next) => handleDomPathOffsetCommit(selection, next),
-      resizeTo: (selection, next) => handleDomBoxSizeCommit(selection, next),
+      resizeTo: (selection, next) =>
+        resizeSelectionFromAgent(selection, next, handleDomBoxSizeCommit),
       rotateTo: (selection, next) => handleDomRotationCommit(selection, next),
-      addAnimation: (method) => handleGsapAddAnimation(method),
-      updateAnimation: (animationId, updates) => handleGsapUpdateMeta(animationId, updates),
-      addKeyframe: (animationId, percent, properties) =>
-        handleGsapAddKeyframeBatch(animationId, percent, properties),
-      deleteAnimation: (animationId) => handleGsapDeleteAnimation(animationId),
+      addAnimation: (selection, method) => handleGsapAddAnimation(method, selection),
+      updateAnimation: (selection, animationId, updates) =>
+        handleGsapUpdateMeta(animationId, updates, selection),
+      addKeyframe: (selection, animationId, percent, properties) =>
+        handleGsapAddKeyframeBatch(animationId, percent, properties, undefined, selection),
+      deleteAnimation: (selection, animationId) =>
+        handleGsapDeleteAnimation(animationId, selection),
+      getAnimationsForSelection: async (selection) =>
+        await getGsapAnimationsForSelection(selection),
       getGsapDiagnostics: () => ({
         animations: selectedGsapAnimations,
         multipleTimelines: gsapMultipleTimelines,
@@ -120,8 +187,8 @@ export function StudioAgentTools() {
       projectId,
       activeCompPath,
       writeBlockedReason,
-      handleDomTextCommit,
-      handleDomStyleCommit,
+      handleDomTextCommitForSelection,
+      handleDomStyleCommitForSelection,
       handleDomPathOffsetCommit,
       handleDomBoxSizeCommit,
       handleDomRotationCommit,
@@ -129,6 +196,7 @@ export function StudioAgentTools() {
       handleGsapUpdateMeta,
       handleGsapAddKeyframeBatch,
       handleGsapDeleteAnimation,
+      getGsapAnimationsForSelection,
       domEditSelection,
       selectedGsapAnimations,
       gsapMultipleTimelines,

package/src/webmcp/handles.test.ts

@@ -5,23 +5,15 @@ import {
   mintElementHandle,
   parseElementHandle,
   resolveElementHandle,
+  resolveLiveHandleSelection,
   timelineElementAddress,
 } from "./handles";
+import { previewDoc } from "./webmcpTestUtils";
 
 function timelineElement(overrides: Partial<TimelineElement>): TimelineElement {
   return { id: "synthetic-id", tag: "div", start: 0, duration: 1, track: 0, ...overrides };
 }
 
-/** A separate document, standing in for the preview iframe's realm. */
-function previewDoc(html: string): Document {
-  const iframe = document.createElement("iframe");
-  document.body.append(iframe);
-  const doc = iframe.contentDocument;
-  if (!doc) throw new Error("expected iframe document");
-  doc.body.innerHTML = html;
-  return doc;
-}
-
 describe("mintElementHandle", () => {
   it("prefers data-hf-id, the stable patch target", () => {
     const handle = mintElementHandle(
@@ -29,7 +21,7 @@ describe("mintElementHandle", () => {
         timelineElement({ hfId: "abc123", domId: "headline", selector: ".title" }),
       ),
     );
-    expect(handle).toBe("hf:abc123");
+    expect(handle).toBe("hf:v1:index.html:index.html:abc123");
   });
 
   it("falls back to the DOM id when there is no hf id", () => {
@@ -37,7 +29,7 @@ describe("mintElementHandle", () => {
       mintElementHandle(
         timelineElementAddress(timelineElement({ domId: "headline", selector: ".title" })),
       ),
-    ).toBe("dom:headline");
+    ).toBe("dom:v1:index.html:index.html:headline");
   });
 
   it("falls back to a selector with its occurrence index", () => {
@@ -45,12 +37,12 @@ describe("mintElementHandle", () => {
       mintElementHandle(
         timelineElementAddress(timelineElement({ selector: ".card", selectorIndex: 2 })),
       ),
-    ).toBe("sel:.card#2");
+    ).toBe("sel:v1:index.html:index.html:.card#2");
   });
 
   it("defaults a missing occurrence index to the first match", () => {
     expect(mintElementHandle(timelineElementAddress(timelineElement({ selector: ".card" })))).toBe(
-      "sel:.card#0",
+      "sel:v1:index.html:index.html:.card#0",
     );
   });
 
@@ -60,17 +52,110 @@ describe("mintElementHandle", () => {
   });
 });
 
+describe("resolveLiveHandleSelection", () => {
+  it("reports a transient change when the replacement preview has not rebuilt the target", async () => {
+    const firstDoc = previewDoc('<div id="headline">before</div>');
+    const replacementDoc = previewDoc("<main>reloading</main>");
+    let currentDoc = firstDoc;
+
+    const result = await resolveLiveHandleSelection(
+      () => currentDoc,
+      "dom:headline",
+      async (element) => {
+        currentDoc = replacementDoc;
+        return { element };
+      },
+    );
+
+    expect(result).toEqual({ status: "changed" });
+  });
+
+  it("reports a stable missing target as not found", async () => {
+    const doc = previewDoc("<main>settled</main>");
+
+    const result = await resolveLiveHandleSelection(
+      () => doc,
+      "dom:headline",
+      async (element) => ({ element }),
+    );
+
+    expect(result).toEqual({ status: "not-found" });
+  });
+});
+
 describe("parseElementHandle", () => {
+  it("round-trips source ownership and the active composition", () => {
+    expect(
+      parseElementHandle(
+        mintElementHandle({
+          domId: "headline:hero",
+          sourceFile: "compositions/hero.html",
+          activeCompositionPath: "index.html",
+        })!,
+      ),
+    ).toEqual({
+      scheme: "dom",
+      version: 1,
+      value: "headline:hero",
+      index: 0,
+      sourceFile: "compositions/hero.html",
+      activeCompositionPath: "index.html",
+    });
+  });
+
+  it("encodes path, selector, colon, and hash delimiters without ambiguity", () => {
+    const handle = mintElementHandle({
+      selector: '#hero[data-label="a:b"] > .card:nth-child(2)',
+      selectorIndex: 3,
+      sourceFile: "compositions/a:b#hero.html",
+      activeCompositionPath: "scenes/root:wide.html",
+    });
+
+    expect(parseElementHandle(handle!)).toEqual({
+      scheme: "sel",
+      version: 1,
+      value: '#hero[data-label="a:b"] > .card:nth-child(2)',
+      index: 3,
+      sourceFile: "compositions/a:b#hero.html",
+      activeCompositionPath: "scenes/root:wide.html",
+    });
+  });
+
   it("splits the index off the LAST hash, so id selectors survive", () => {
     expect(parseElementHandle("sel:#card > .title#3")).toEqual({
       scheme: "sel",
+      version: 0,
       value: "#card > .title",
       index: 3,
     });
   });
 
   it("treats a selector with no index as the first match", () => {
-    expect(parseElementHandle("sel:.card")).toEqual({ scheme: "sel", value: ".card", index: 0 });
+    expect(parseElementHandle("sel:.card")).toEqual({
+      scheme: "sel",
+      version: 0,
+      value: ".card",
+      index: 0,
+    });
+  });
+
+  it("round-trips the project identity in a writable v2 handle", () => {
+    const handle = mintElementHandle({
+      projectId: "project:demo",
+      domId: "headline",
+      sourceFile: "index.html",
+      activeCompositionPath: "index.html",
+    });
+
+    expect(parseElementHandle(handle!)).toEqual({
+      scheme: "dom",
+      version: 2,
+      projectId: "project:demo",
+      value: "headline",
+      sourceFile: "index.html",
+      activeCompositionPath: "index.html",
+      index: 0,
+    });
   });
 
   it("rejects an unknown scheme", () => {
@@ -106,6 +191,78 @@ describe("resolveElementHandle", () => {
     expect(resolved instanceof HTMLElement).toBe(false);
   });
 
+  it("distinguishes duplicate authored ids by source file", () => {
+    const doc = previewDoc(
+      `<main data-composition-id="root" data-composition-file="index.html">
+         <div id="duplicate">root</div>
+         <section data-composition-id="nested" data-composition-file="compositions/nested.html">
+           <div id="duplicate">nested</div>
+         </section>
+       </main>`,
+    );
+    const rootHandle = mintElementHandle({
+      domId: "duplicate",
+      sourceFile: "index.html",
+      activeCompositionPath: "index.html",
+    });
+    const nestedHandle = mintElementHandle({
+      domId: "duplicate",
+      sourceFile: "compositions/nested.html",
+      activeCompositionPath: "index.html",
+    });
+
+    expect(rootHandle).not.toBe(nestedHandle);
+    expect(resolveElementHandle(doc, rootHandle!)?.textContent).toBe("root");
+    expect(resolveElementHandle(doc, nestedHandle!)?.textContent).toBe("nested");
+  });
+
+  it("keeps selector occurrence indexes scoped to their source file", () => {
+    const doc = previewDoc(
+      `<main data-composition-id="root" data-composition-file="index.html">
+         <div class="card">root first</div><div class="card">root second</div>
+         <section data-composition-id="nested" data-composition-file="compositions/nested.html">
+           <div class="card">nested first</div><div class="card">nested second</div>
+         </section>
+       </main>`,
+    );
+    const rootSecond = mintElementHandle({
+      selector: ".card",
+      selectorIndex: 1,
+      sourceFile: "index.html",
+      activeCompositionPath: "index.html",
+    });
+    const nestedSecond = mintElementHandle({
+      selector: ".card",
+      selectorIndex: 1,
+      sourceFile: "compositions/nested.html",
+      activeCompositionPath: "index.html",
+    });
+
+    expect(resolveElementHandle(doc, rootSecond!)?.textContent).toBe("root second");
+    expect(resolveElementHandle(doc, nestedSecond!)?.textContent).toBe("nested second");
+  });
+
+  it("re-resolves a scoped handle against the live document after reload", () => {
+    const handle = mintElementHandle({
+      domId: "headline",
+      sourceFile: "index.html",
+      activeCompositionPath: "index.html",
+    });
+    const firstDoc = previewDoc(
+      '<main data-composition-id="root" data-composition-file="index.html"><div id="headline">before</div></main>',
+    );
+    const first = resolveElementHandle(firstDoc, handle!);
+    const reloadedDoc = previewDoc(
+      '<main data-composition-id="root" data-composition-file="index.html"><div id="headline">after</div></main>',
+    );
+    const reloaded = resolveElementHandle(reloadedDoc, handle!);
+
+    expect(first?.textContent).toBe("before");
+    expect(reloaded?.textContent).toBe("after");
+    expect(reloaded).not.toBe(first);
+    expect(reloaded?.ownerDocument).toBe(reloadedDoc);
+  });
+
   it("returns null for a handle that no longer matches", () => {
     const doc = previewDoc('<div id="headline">A</div>');
     expect(resolveElementHandle(doc, "dom:deleted")).toBeNull();