@hyperframes/studio 0.8.24 → 0.8.25

package/src/webmcp/tools/lookTools.ts

@@ -8,11 +8,20 @@
  * values. Gathering the snapshot is the React layer's job.
  */
 
-import type { DomEditSelection } from "../../components/editor/domEditingTypes";
+import { collectDomEditLayerItems } from "../../components/editor/domEditingLayers";
+import type { DomEditLayerItem, DomEditSelection } from "../../components/editor/domEditingTypes";
 import type { TimelineElement } from "../../player/store/timelineElement";
 import { mintElementHandle, patchTargetAddress, timelineElementAddress } from "../handles";
 import { toolOk, type ToolResult } from "../toolResult";
 
+export type StudioLookSceneSnapshot =
+  | { status: "loading" }
+  | {
+      status: "ready";
+      items: readonly DomEditLayerItem[];
+      drillInItem: DomEditLayerItem | null;
+    };
+
 export interface StudioLookSnapshot {
   projectId: string | null;
   compositionPath: string | null;
@@ -20,6 +29,7 @@ export interface StudioLookSnapshot {
   duration: number;
   isPlaying: boolean;
   elements: readonly TimelineElement[];
+  scene: StudioLookSceneSnapshot;
   selection: DomEditSelection | null;
   /** Live animations for the current selection arrive outside DomEditSelection. */
   selectionAnimationCount: number;
@@ -41,16 +51,24 @@ export interface StudioLookSnapshot {
   };
 }
 
-interface LookElement {
-  /** Pass back to any tool that takes a handle. Null means unaddressable. */
-  handle: string | null;
-  label: string | null;
-  tag: string;
-  kind: string | null;
+interface LookTimeline {
   start: number;
   duration: number;
   track: number;
   zIndex: number | null;
+  kind: string | null;
+}
+
+interface LookElement {
+  /** Pass back unchanged to tools that take a handle. */
+  handle: string;
+  parentHandle: string | null;
+  label: string;
+  tag: string;
+  depth: number;
+  childCount: number;
+  sourceFile: string;
+  timeline: LookTimeline | null;
 }
 
 interface LookSelection {
@@ -84,7 +102,10 @@ export interface StudioLook {
   isPlaying: boolean;
   history: StudioLookSnapshot["history"];
   selection: LookSelection | null;
+  sceneStatus: StudioLookSceneSnapshot["status"];
+  drillIn: { handle: string; label: string; sourceFile: string } | null;
   elementCount: number;
+  truncated: boolean;
   elements: LookElement[];
 }
 
@@ -98,23 +119,25 @@ export interface StudioLookInput {
 const DEFAULT_LIMIT = 200;
 const MAX_FILTER_LENGTH = 128;
 
-function describeElement(element: TimelineElement): LookElement {
+function describeTimeline(element: TimelineElement): LookTimeline {
   return {
-    handle: mintElementHandle(timelineElementAddress(element)),
-    label: element.label ?? null,
-    tag: element.tag,
-    kind: element.kind ?? null,
     start: element.start,
     duration: element.duration,
     track: element.track,
     zIndex: element.zIndex ?? null,
+    kind: element.kind ?? null,
   };
 }
 
-function describeSelection(selection: DomEditSelection, animationCount: number): LookSelection {
+function describeSelection(
+  selection: DomEditSelection,
+  animationCount: number,
+  activeCompositionPath: string,
+  projectId: string | null,
+): LookSelection {
   const { capabilities } = selection;
   return {
-    handle: mintElementHandle(patchTargetAddress(selection)),
+    handle: mintElementHandle(patchTargetAddress(selection, activeCompositionPath, projectId)),
     label: selection.label,
     tagName: selection.tagName,
     sourceFile: selection.sourceFile,
@@ -133,21 +156,102 @@ function describeSelection(selection: DomEditSelection, animationCount: number):
 
 function matchesFilter(element: LookElement, needle: string): boolean {
   return (
-    (element.label?.toLowerCase().includes(needle) ?? false) ||
+    element.label.toLowerCase().includes(needle) ||
     element.tag.toLowerCase().includes(needle) ||
-    (element.handle?.toLowerCase().includes(needle) ?? false)
+    element.handle.toLowerCase().includes(needle)
   );
 }
 
+/** Gather the live scene once per tool call. The response never retains DOM nodes. */
+export function collectStudioLookScene(
+  doc: Document | null,
+  activeCompositionPath: string | null,
+  activeGroupElement: HTMLElement | null,
+): StudioLookSceneSnapshot {
+  if (!doc) return { status: "loading" };
+
+  const root = doc.querySelector<HTMLElement>("[data-composition-id]");
+  if (!root) return { status: "loading" };
+
+  const options = {
+    activeCompositionPath,
+    isMasterView: !activeCompositionPath || activeCompositionPath === "index.html",
+    activeGroupElement: null,
+  };
+  const items = collectDomEditLayerItems(root, options);
+  const liveGroup =
+    activeGroupElement?.isConnected && activeGroupElement.ownerDocument === doc
+      ? activeGroupElement
+      : null;
+  return {
+    status: "ready",
+    items,
+    drillInItem: liveGroup ? (items.find((item) => item.element === liveGroup) ?? null) : null,
+  };
+}
+
+function describeScene(snapshot: StudioLookSnapshot): {
+  elements: LookElement[];
+  drillIn: StudioLook["drillIn"];
+} {
+  if (snapshot.scene.status === "loading") return { elements: [], drillIn: null };
+
+  const activeCompositionPath = snapshot.compositionPath ?? "index.html";
+  const timelineByHandle = new Map<string, LookTimeline>();
+  for (const element of snapshot.elements) {
+    const handle = mintElementHandle(
+      timelineElementAddress(element, activeCompositionPath, snapshot.projectId),
+    );
+    if (handle) timelineByHandle.set(handle, describeTimeline(element));
+  }
+
+  const parentHandles: string[] = [];
+  const elements = snapshot.scene.items.map((item) => {
+    const handle = mintElementHandle(
+      patchTargetAddress(item, activeCompositionPath, snapshot.projectId),
+    );
+    if (!handle) throw new Error("collectDomEditLayerItems returned an unaddressable layer");
+    const parentHandle = item.depth > 0 ? (parentHandles[item.depth - 1] ?? null) : null;
+    parentHandles[item.depth] = handle;
+    parentHandles.length = item.depth + 1;
+    return {
+      handle,
+      parentHandle,
+      label: item.label,
+      tag: item.tagName,
+      depth: item.depth,
+      childCount: item.childCount,
+      sourceFile: item.sourceFile,
+      timeline: timelineByHandle.get(handle) ?? null,
+    };
+  });
+
+  const drillInItem = snapshot.scene.drillInItem;
+  const drillInHandle = drillInItem
+    ? mintElementHandle(patchTargetAddress(drillInItem, activeCompositionPath, snapshot.projectId))
+    : null;
+  return {
+    elements,
+    drillIn:
+      drillInItem && drillInHandle
+        ? {
+            handle: drillInHandle,
+            label: drillInItem.label,
+            sourceFile: drillInItem.sourceFile,
+          }
+        : null,
+  };
+}
+
 export function buildStudioLook(
   snapshot: StudioLookSnapshot,
   input: StudioLookInput = {},
 ): ToolResult<StudioLook> {
-  const described = snapshot.elements.map(describeElement);
+  const scene = describeScene(snapshot);
   const needle = input.filter?.slice(0, MAX_FILTER_LENGTH).trim().toLowerCase();
   const matched = needle
-    ? described.filter((element) => matchesFilter(element, needle))
-    : described;
+    ? scene.elements.filter((element) => matchesFilter(element, needle))
+    : scene.elements;
 
   // Clamp rather than reject: a bad limit should not cost the agent a round trip
   // when the answer it wants is right here.
@@ -163,11 +267,19 @@ export function buildStudioLook(
     isPlaying: snapshot.isPlaying,
     history: snapshot.history,
     selection: snapshot.selection
-      ? describeSelection(snapshot.selection, snapshot.selectionAnimationCount)
+      ? describeSelection(
+          snapshot.selection,
+          snapshot.selectionAnimationCount,
+          snapshot.compositionPath ?? "index.html",
+          snapshot.projectId,
+        )
       : null,
+    sceneStatus: snapshot.scene.status,
+    drillIn: scene.drillIn,
     // The count is of everything that MATCHED, so a truncated list is visible
     // as a truncated list rather than reading as "that is all there is".
     elementCount: matched.length,
+    truncated: matched.length > limit,
     elements: matched.slice(0, limit),
   });
 }
@@ -193,7 +305,8 @@ export const STUDIO_LOOK_INPUT_SCHEMA = {
 export const STUDIO_LOOK_DESCRIPTION = [
   "Read HyperFrames Studio's live state in one call: the open project and composition,",
   "the playhead and duration, what the human currently has selected (including what that",
-  "element will and will not accept), and the timeline's elements with a handle for each.",
+  "element will and will not accept), and the live nested scene in DOM preorder.",
+  "Each scene element includes source ownership, hierarchy, and optional timeline timing.",
   "Pass a handle back to any tool that edits an element.",
   "Returns an object with `ok: true`, or `ok: false` with `kind`, `reason` and often a `hint`.",
   "`history.undoLabel` is worth checkpointing before a batch: if it later names something",

package/src/webmcp/tools/selectionTools.test.ts

@@ -7,20 +7,37 @@ import {
   type StudioSeekResult,
   type StudioSelectResult,
 } from "./selectionTools";
-import { expectFailure, expectOk, previewDoc, selectionFor } from "../webmcpTestUtils";
+import {
+  expectFailure,
+  expectOk,
+  previewDoc,
+  selectionFor,
+  selectionToolDeps,
+  sourceHandle,
+} from "../webmcpTestUtils";
 
 function selectionDeps(overrides: Partial<SelectionToolDeps> = {}): SelectionToolDeps {
-  return {
-    getPreviewDocument: () => null,
-    buildSelection: async (element) => selectionFor(element),
-    applySelection: () => undefined,
-    requestSeek: () => undefined,
-    readPlayhead: () => ({ currentTime: 0, duration: 10, isPlaying: false }),
-    ...overrides,
-  };
+  return selectionToolDeps(overrides);
 }
 
 describe("studioSelect", () => {
+  it("refuses a scoped handle from another project before selecting", async () => {
+    const doc = previewDoc('<h1 id="headline">Ship it</h1>');
+    const applySelection = vi.fn();
+
+    const result = await studioSelect(
+      selectionDeps({ getPreviewDocument: () => doc, applySelection }),
+      sourceHandle("headline", "project-b"),
+    );
+
+    expect(result).toMatchObject({
+      ok: false,
+      kind: "invalid",
+      reason: "the handle belongs to a different project",
+    });
+    expect(applySelection).not.toHaveBeenCalled();
+  });
+
   it("applies the selection a click would produce and reports it back", async () => {
     const doc = previewDoc('<h1 id="headline" data-hf-id="abc">Ship it</h1>');
     const applySelection = vi.fn();
@@ -38,6 +55,85 @@ describe("studioSelect", () => {
     expect(applySelection).toHaveBeenCalledTimes(1);
   });
 
+  it("returns the exact source-safe handle it resolved", async () => {
+    const doc = previewDoc(
+      '<main data-composition-id="root" data-composition-file="index.html"><h1 id="headline">Ship it</h1></main>',
+    );
+    const handle = "dom:v1:index.html:index.html:headline";
+
+    const ok = expectOk<StudioSelectResult>(
+      await studioSelect(selectionDeps({ getPreviewDocument: () => doc }), handle),
+    );
+
+    expect(ok.handle).toBe(handle);
+  });
+
+  it("reacquires once when the preview document reloads during selection resolution", async () => {
+    const firstDoc = previewDoc('<h1 data-hf-id="abc">Old preview</h1>');
+    const nextDoc = previewDoc('<h1 data-hf-id="abc">Current preview</h1>');
+    let currentDoc = firstDoc;
+    const buildSelection = vi.fn(async (element: HTMLElement) => {
+      if (element.ownerDocument === firstDoc) {
+        currentDoc = nextDoc;
+        return selectionFor(element, { boundingBox: { x: 0, y: 0, width: 0, height: 0 } });
+      }
+      return selectionFor(element, {
+        boundingBox: { x: 98, y: 206, width: 304, height: 50 },
+      });
+    });
+    const applySelection = vi.fn();
+
+    const ok = expectOk<StudioSelectResult>(
+      await studioSelect(
+        selectionDeps({
+          getPreviewDocument: () => currentDoc,
+          buildSelection,
+          applySelection,
+        }),
+        "hf:abc",
+      ),
+    );
+
+    expect(ok.box).toEqual({ x: 98, y: 206, width: 304, height: 50 });
+    expect(buildSelection).toHaveBeenCalledTimes(2);
+    expect(applySelection).toHaveBeenCalledWith(
+      expect.objectContaining({ element: nextDoc.querySelector("h1") }),
+    );
+  });
+
+  it("refuses when the preview changes again during the bounded reacquire", async () => {
+    const documents = [
+      previewDoc('<h1 data-hf-id="abc">First preview</h1>'),
+      previewDoc('<h1 data-hf-id="abc">Second preview</h1>'),
+      previewDoc('<h1 data-hf-id="abc">Third preview</h1>'),
+    ];
+    let currentIndex = 0;
+    const buildSelection = vi.fn(async (element: HTMLElement) => {
+      currentIndex += 1;
+      return selectionFor(element);
+    });
+    const applySelection = vi.fn();
+
+    const failure = expectFailure(
+      await studioSelect(
+        selectionDeps({
+          getPreviewDocument: () => documents[currentIndex] ?? documents.at(-1)!,
+          buildSelection,
+          applySelection,
+        }),
+        "hf:abc",
+      ),
+    );
+
+    expect(failure).toMatchObject({
+      kind: "invalid",
+      reason: "the target changed while it was resolving",
+      hint: "Call studio_look again.",
+    });
+    expect(buildSelection).toHaveBeenCalledTimes(2);
+    expect(applySelection).not.toHaveBeenCalled();
+  });
+
   it("distinguishes a preview that is not mounted from a handle that does not match", async () => {
     const notMounted = expectFailure(await studioSelect(selectionDeps(), "dom:headline"));
     expect(notMounted.kind).toBe("blocked");

package/src/webmcp/tools/selectionTools.ts

@@ -2,21 +2,20 @@
  * `studio_select` and `studio_seek`: pointing the human and the agent at the
  * same thing.
  *
- * Selection is shared state, not a per-call argument. That is deliberate and it
- * is also forced: most of Studio's edit handlers read the ambient React
- * selection, and `applyDomSelection` only schedules a state update, so
- * selecting and committing inside ONE call would write to whatever was selected
- * before. Two tool calls are separated by a render, so the contract is select
- * first, then act, which is also how a human works: click, then type.
+ * Selection is shared human-visible state. Element writes do not infer their
+ * target from it: they resolve an explicit source-safe handle per call. Keeping
+ * these contracts separate means a human click cannot redirect an agent write.
  */
 
 import type { DomEditSelection } from "../../components/editor/domEditingTypes";
-import { mintElementHandle, patchTargetAddress, resolveElementHandle } from "../handles";
+import { elementHandleMatchesProject, resolveLiveHandleSelection } from "../handles";
 import { toolFailure, toolOk, type ToolResult } from "../toolResult";
 
 export interface SelectionToolDeps {
   /** The preview iframe's document, or null before it mounts. */
   getPreviewDocument: () => Document | null;
+  getCompositionPath: () => string | null;
+  getProjectId: () => string | null;
   buildSelection: (element: HTMLElement) => Promise<DomEditSelection | null>;
   applySelection: (selection: DomEditSelection) => void;
   /** Out-of-loop seek. `requestSeek`, not `setCurrentTime`. */
@@ -25,7 +24,7 @@ export interface SelectionToolDeps {
 }
 
 export interface StudioSelectResult {
-  handle: string | null;
+  handle: string;
   label: string;
   tagName: string;
   box: { x: number; y: number; width: number; height: number };
@@ -38,41 +37,56 @@ export async function studioSelect(
   if (typeof handle !== "string" || !handle.trim()) {
     return toolFailure("invalid", "handle must be a non-empty string", "Call studio_look first.");
   }
+  if (!elementHandleMatchesProject(handle, deps.getProjectId())) {
+    return toolFailure(
+      "invalid",
+      "the handle belongs to a different project",
+      "Call studio_look in the active project.",
+    );
+  }
 
   // Three distinct failures, deliberately not collapsed: "the preview is not up
   // yet" is a wait, "no such element" is a stale handle, and "could not build a
   // selection" is an element Studio cannot drive. The agent's next move differs
   // for each.
-  const doc = deps.getPreviewDocument();
-  if (!doc) {
+  const resolved = await resolveLiveHandleSelection(
+    deps.getPreviewDocument,
+    handle,
+    deps.buildSelection,
+  );
+  if (resolved.status === "preview-unavailable") {
     return toolFailure(
       "blocked",
       "the preview is not mounted yet",
       "Wait for the composition to load, then retry.",
     );
   }
-
-  const element = resolveElementHandle(doc, handle);
-  if (!element) {
+  if (resolved.status === "not-found") {
     return toolFailure(
       "invalid",
       `no element matches handle ${handle}`,
       "The composition may have changed. Call studio_look for current handles.",
     );
   }
-
-  const selection = await deps.buildSelection(element);
-  if (!selection) {
+  if (resolved.status === "unsupported") {
     return toolFailure(
       "blocked",
       `${handle} resolved to an element Studio cannot select`,
       "Try a parent or child element from studio_look.",
     );
   }
+  if (resolved.status === "changed") {
+    return toolFailure(
+      "invalid",
+      "the target changed while it was resolving",
+      "Call studio_look again.",
+    );
+  }
 
+  const { selection } = resolved;
   deps.applySelection(selection);
   return toolOk<StudioSelectResult>({
-    handle: mintElementHandle(patchTargetAddress(selection)),
+    handle,
     label: selection.label,
     tagName: selection.tagName,
     box: selection.boundingBox,
@@ -132,8 +146,9 @@ export const STUDIO_SELECT_INPUT_SCHEMA = {
 export const STUDIO_SELECT_DESCRIPTION = [
   "Select an element in HyperFrames Studio, exactly as clicking it would:",
   "the human sees the same selection box and inspector.",
-  "Takes a handle from studio_look. Most editing tools act on the CURRENT selection,",
-  "so call this first, then the edit.",
+  "Call this before the first write to a target so the human sees the agent's intent.",
+  "Takes a handle from studio_look. Selection is visual context for the human;",
+  "element writes take their own explicit handle and do not require this tool first.",
   "Returns `ok: true` with the resulting selection, or `ok: false` with `kind`, `reason` and a `hint`.",
 ].join(" ");
 

package/src/webmcp/tools/targetedWriteTools.test.ts

@@ -0,0 +1,125 @@
+// @vitest-environment jsdom
+import { describe, expect, it, vi } from "vitest";
+import { mintElementHandle } from "../handles";
+import { previewDoc, selectionFor } from "../webmcpTestUtils";
+import {
+  studioAddAnimation,
+  studioAddKeyframe,
+  studioDeleteAnimation,
+  studioUpdateAnimation,
+  type AnimationToolDeps,
+} from "./animationTools";
+import { studioTransform, type ElementBox, type TransformToolDeps } from "./transformTools";
+
+function target() {
+  const doc = previewDoc('<div id="agent">Agent</div>');
+  const element = doc.getElementById("agent") as HTMLElement;
+  const handle = mintElementHandle({
+    projectId: "demo",
+    domId: "agent",
+    sourceFile: "index.html",
+    activeCompositionPath: "index.html",
+  });
+  if (!handle) throw new Error("expected handle");
+  const common = {
+    getPreviewDocument: () => doc,
+    getCompositionPath: () => "index.html",
+    getProjectId: () => "demo",
+    getWriteBlockedReason: () => null,
+    buildSelection: async (targetElement: HTMLElement) => selectionFor(targetElement),
+    applySelection: () => undefined,
+  };
+  return { common, element, handle };
+}
+
+function transformDeps(
+  common: ReturnType<typeof target>["common"],
+  box: ElementBox,
+  overrides: Partial<TransformToolDeps> = {},
+): TransformToolDeps {
+  return {
+    ...common,
+    readBox: () => ({ ...box }),
+    moveTo: async () => undefined,
+    resizeTo: async () => undefined,
+    rotateTo: async () => undefined,
+    ...overrides,
+  };
+}
+
+function animationDeps(
+  common: ReturnType<typeof target>["common"],
+  overrides: Partial<AnimationToolDeps> = {},
+): AnimationToolDeps {
+  return {
+    ...common,
+    getAnimationsForSelection: async () => [{ id: "anim-1" }],
+    readPlayhead: () => ({ currentTime: 2, duration: 10, isPlaying: false }),
+    addAnimation: async () => true,
+    updateAnimation: async () => true,
+    addKeyframe: async () => undefined,
+    deleteAnimation: async () => true,
+    ...overrides,
+  };
+}
+
+describe("targeted write actor families", () => {
+  it("passes the live handle selection to transform and every animation actor", async () => {
+    const { common, element, handle } = target();
+    const box = { x: 0, y: 0, width: 100, height: 50 };
+    const moveTo = vi.fn(async (_selection, next: { x: number; y: number }) => {
+      Object.assign(box, next);
+    });
+    const addAnimation = vi.fn();
+    const updateAnimation = vi.fn(async () => true);
+    const addKeyframe = vi.fn(async () => undefined);
+    const deleteAnimation = vi.fn();
+
+    await studioTransform(transformDeps(common, box, { moveTo }), { handle, x: 20, y: 30 });
+    const animations = animationDeps(common, {
+      addAnimation,
+      updateAnimation,
+      addKeyframe,
+      deleteAnimation,
+    });
+    await studioAddAnimation(animations, { handle, method: "to" });
+    await studioUpdateAnimation(animations, { handle, animationId: "anim-1", duration: 2 });
+    await studioAddKeyframe(animations, {
+      handle,
+      animationId: "anim-1",
+      percent: 50,
+      properties: { opacity: 0 },
+    });
+    await studioDeleteAnimation(animations, { handle, animationId: "anim-1" });
+
+    for (const actor of [moveTo, addAnimation, updateAnimation, addKeyframe, deleteAnimation]) {
+      expect(actor.mock.calls[0]?.[0]).toEqual(expect.objectContaining({ element }));
+    }
+  });
+
+  it("keeps mixed durable and void transform operations at dispatched", async () => {
+    const { common, handle } = target();
+    const box = { x: 0, y: 0, width: 100, height: 50 };
+    const result = await studioTransform(
+      transformDeps(common, box, {
+        resizeTo: async (_selection, next) => {
+          Object.assign(box, next);
+          return {
+            ok: true,
+            persistence: {
+              sourceFile: "index.html",
+              version: '"sha256:size"',
+              changed: true,
+            },
+          };
+        },
+        moveTo: async (_selection, next) => {
+          Object.assign(box, next);
+        },
+      }),
+      { handle, width: 200, height: 80, x: 20, y: 30 },
+    );
+
+    expect(result).toMatchObject({ ok: true, stage: "dispatched" });
+  });
+});