@hyperframes/studio 0.8.24 → 0.8.26

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

@@ -8,6 +8,8 @@ import {
   previewDoc,
   previewElement,
   selectionFor,
+  selectionToolDeps,
+  sourceHandle,
 } from "../webmcpTestUtils";
 
 function animation(overrides: Partial<GsapAnimation> = {}): GsapAnimation {
@@ -25,11 +27,8 @@ function animation(overrides: Partial<GsapAnimation> = {}): GsapAnimation {
 
 function inspectDeps(overrides: Partial<InspectToolDeps> = {}): InspectToolDeps {
   return {
-    getPreviewDocument: () => null,
-    buildSelection: async (element) => selectionFor(element),
-    applySelection: () => undefined,
-    requestSeek: () => undefined,
-    readPlayhead: () => ({ currentTime: 0, duration: 10, isPlaying: false }),
+    ...selectionToolDeps(),
+    getProjectId: () => "project-a",
     getCurrentSelection: () => null,
     getGsapDiagnostics: () => ({
       animations: [],
@@ -41,6 +40,20 @@ function inspectDeps(overrides: Partial<InspectToolDeps> = {}): InspectToolDeps
 }
 
 describe("studioInspect", () => {
+  it("refuses a scoped handle from another project before inspecting", async () => {
+    const doc = previewDoc('<h1 id="headline">Ship it</h1>');
+
+    const result = await studioInspect(inspectDeps({ getPreviewDocument: () => doc }), {
+      handle: sourceHandle("headline", "project-b"),
+    });
+
+    expect(result).toMatchObject({
+      ok: false,
+      kind: "invalid",
+      reason: "the handle belongs to a different project",
+    });
+  });
+
   it("returns the resolved styles, not the authored ones", async () => {
     const element = previewElement('<h1 id="headline">Ship it</h1>', "headline");
     const selection = selectionFor(element);
@@ -173,6 +186,35 @@ describe("studioInspect", () => {
     expect(applySelection).not.toHaveBeenCalled();
   });
 
+  it("keeps a resolved source-safe handle instead of weakening it", async () => {
+    const doc = previewDoc(
+      '<main data-composition-id="root" data-composition-file="index.html"><h1 id="headline">A</h1></main>',
+    );
+    const handle = "dom:v1:index.html:index.html:headline";
+
+    const ok = expectOk<StudioInspectResult>(
+      await studioInspect(inspectDeps({ getPreviewDocument: () => doc }), { handle }),
+    );
+
+    expect(ok.handle).toBe(handle);
+  });
+
+  it("mints a source-safe handle for the current selection", async () => {
+    const element = previewElement('<h1 id="headline">A</h1>', "headline");
+    const current = selectionFor(element, { sourceFile: "compositions/hero.html" });
+
+    const ok = expectOk<StudioInspectResult>(
+      await studioInspect(
+        inspectDeps({
+          getCompositionPath: () => "index.html",
+          getCurrentSelection: () => current,
+        }),
+      ),
+    );
+
+    expect(ok.handle).toBe("dom:v2:project-a:index.html:compositions%2Fhero.html:headline");
+  });
+
   it("fails rather than returning an empty result when nothing is selected", async () => {
     const result = expectFailure(await studioInspect(inspectDeps()));
 

package/src/webmcp/tools/inspectTools.ts

@@ -14,7 +14,12 @@
 
 import type { GsapAnimation } from "@hyperframes/parsers/gsap-parser";
 import type { DomEditSelection } from "../../components/editor/domEditingTypes";
-import { mintElementHandle, patchTargetAddress, resolveElementHandle } from "../handles";
+import {
+  elementHandleMatchesProject,
+  mintElementHandle,
+  patchTargetAddress,
+  resolveLiveHandleSelection,
+} from "../handles";
 import { toolFailure, toolOk, type ToolResult } from "../toolResult";
 import type { SelectionToolDeps } from "./selectionTools";
 
@@ -94,10 +99,23 @@ function describeAnimation(animation: GsapAnimation): InspectAnimation {
   };
 }
 
+function getAnimationEditingBlock(
+  isCurrentSelection: boolean,
+  diagnostics: ReturnType<InspectToolDeps["getGsapDiagnostics"]>,
+): string | null {
+  if (!isCurrentSelection) return "animations are only readable for the current selection";
+  if (diagnostics.multipleTimelines) return "this composition has multiple GSAP timelines";
+  if (diagnostics.unsupportedTimelinePattern) {
+    return "this composition's timeline pattern is not editable by Studio";
+  }
+  return null;
+}
+
 function describe(
   selection: DomEditSelection,
   deps: InspectToolDeps,
   isCurrentSelection: boolean,
+  resolvedHandle?: string,
 ): ToolResult<StudioInspectResult> {
   const { capabilities } = selection;
   const gsap = deps.getGsapDiagnostics();
@@ -107,17 +125,18 @@ function describe(
   // which is worse than reporting none.
   const animations = isCurrentSelection ? gsap.animations.map(describeAnimation) : [];
 
-  let animationEditingBlocked: string | null = null;
-  if (!isCurrentSelection) {
-    animationEditingBlocked = "animations are only readable for the current selection";
-  } else if (gsap.multipleTimelines) {
-    animationEditingBlocked = "this composition has multiple GSAP timelines";
-  } else if (gsap.unsupportedTimelinePattern) {
-    animationEditingBlocked = "this composition's timeline pattern is not editable by Studio";
-  }
+  const animationEditingBlocked = getAnimationEditingBlock(isCurrentSelection, gsap);
 
   return toolOk<StudioInspectResult>({
-    handle: mintElementHandle(patchTargetAddress(selection)),
+    handle:
+      resolvedHandle ??
+      mintElementHandle(
+        patchTargetAddress(
+          selection,
+          deps.getCompositionPath() ?? "index.html",
+          deps.getProjectId(),
+        ),
+      ),
     label: selection.label,
     tagName: selection.tagName,
     sourceFile: selection.sourceFile,
@@ -165,25 +184,46 @@ export async function studioInspect(
     }
     return describe(current, deps, true);
   }
+  if (!elementHandleMatchesProject(input.handle, deps.getProjectId())) {
+    return toolFailure(
+      "invalid",
+      "the handle belongs to a different project",
+      "Call studio_look in the active project.",
+    );
+  }
 
-  const doc = deps.getPreviewDocument();
-  if (!doc) return toolFailure("blocked", "the preview is not mounted yet");
-
-  const element = resolveElementHandle(doc, input.handle);
-  if (!element) {
+  const resolved = await resolveLiveHandleSelection(
+    deps.getPreviewDocument,
+    input.handle,
+    deps.buildSelection,
+  );
+  if (resolved.status === "preview-unavailable") {
+    return toolFailure("blocked", "the preview is not mounted yet");
+  }
+  if (resolved.status === "not-found") {
     return toolFailure(
       "invalid",
       `no element matches handle ${input.handle}`,
       "Call studio_look for current handles.",
     );
   }
-
-  const selection = await deps.buildSelection(element);
-  if (!selection) {
+  if (resolved.status === "unsupported") {
     return toolFailure("blocked", `${input.handle} resolved to an element Studio cannot inspect`);
   }
+  if (resolved.status === "changed") {
+    return toolFailure(
+      "invalid",
+      "the target changed while it was resolving",
+      "Call studio_look again.",
+    );
+  }
 
-  return describe(selection, deps, current?.element === element);
+  return describe(
+    resolved.selection,
+    deps,
+    current?.element === resolved.selection.element,
+    input.handle,
+  );
 }
 
 export const STUDIO_INSPECT_INPUT_SCHEMA = {

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

@@ -2,7 +2,12 @@
 import { describe, expect, it } from "vitest";
 import type { DomEditSelection } from "../../components/editor/domEditingTypes";
 import type { TimelineElement } from "../../player/store/timelineElement";
-import { buildStudioLook, STUDIO_LOOK_INPUT_SCHEMA, type StudioLookSnapshot } from "./lookTools";
+import {
+  buildStudioLook,
+  collectStudioLookScene,
+  STUDIO_LOOK_INPUT_SCHEMA,
+  type StudioLookSnapshot,
+} from "./lookTools";
 
 function element(overrides: Partial<TimelineElement>): TimelineElement {
   return { id: "synthetic", tag: "div", start: 0, duration: 1, track: 0, ...overrides };
@@ -16,6 +21,7 @@ function snapshot(overrides: Partial<StudioLookSnapshot> = {}): StudioLookSnapsh
     duration: 10,
     isPlaying: false,
     elements: [],
+    scene: { status: "ready", items: [], drillInItem: null },
     selection: null,
     selectionAnimationCount: 0,
     history: { canUndo: true, canRedo: false, undoLabel: "Move layer", redoLabel: null },
@@ -84,90 +90,140 @@ describe("buildStudioLook", () => {
     const look = expectOk<{ elements: { handle: string | null; label: string | null }[] }>(
       buildStudioLook(
         snapshot({
-          elements: [
-            element({ hfId: "abc", label: "Headline" }),
-            element({ domId: "cta", label: "Button" }),
-            element({ selector: ".card", selectorIndex: 2, label: "Card" }),
-          ],
+          scene: {
+            status: "ready",
+            items: [
+              layer("Headline", { hfId: "abc" }),
+              layer("Button", { id: "cta" }),
+              layer("Card", { selector: ".card", selectorIndex: 2 }),
+            ],
+            drillInItem: null,
+          },
         }),
       ),
     );
 
-    expect(look.elements.map((e) => e.handle)).toEqual(["hf:abc", "dom:cta", "sel:.card#2"]);
+    expect(look.elements.map((e) => e.handle)).toEqual([
+      "hf:v2:demo:index.html:index.html:abc",
+      "dom:v2:demo:index.html:index.html:cta",
+      "sel:v2:demo:index.html:index.html:.card#2",
+    ]);
   });
 
-  it("reports an unaddressable element with a null handle rather than hiding it", () => {
-    const look = expectOk<{ elements: { handle: string | null }[]; elementCount: number }>(
-      buildStudioLook(snapshot({ elements: [element({ label: "Anonymous" })] })),
+  it("distinguishes an empty ready scene from a preview that is still loading", () => {
+    const ready = expectOk<{ sceneStatus: string; elements: unknown[]; elementCount: number }>(
+      buildStudioLook(snapshot()),
+    );
+    const loading = expectOk<{ sceneStatus: string; elements: unknown[]; elementCount: number }>(
+      buildStudioLook(snapshot({ scene: { status: "loading" } })),
     );
 
-    expect(look.elementCount).toBe(1);
-    expect(look.elements[0]?.handle).toBeNull();
+    expect(ready).toMatchObject({ sceneStatus: "ready", elements: [], elementCount: 0 });
+    expect(loading).toMatchObject({ sceneStatus: "loading", elements: [], elementCount: 0 });
   });
 
-  it("returns an empty list for an empty timeline, not a failure", () => {
-    const look = expectOk<{ elements: unknown[]; elementCount: number }>(
-      buildStudioLook(snapshot()),
-    );
-
-    expect(look.elements).toEqual([]);
-    expect(look.elementCount).toBe(0);
+  it("treats an about-blank iframe as loading and a mounted empty composition as ready", () => {
+    const blank = document.implementation.createHTMLDocument();
+    const mounted = document.implementation.createHTMLDocument();
+    mounted.body.innerHTML =
+      '<main data-composition-id="root" data-composition-file="index.html"></main>';
+
+    expect(collectStudioLookScene(blank, "index.html", null)).toEqual({ status: "loading" });
+    expect(collectStudioLookScene(mounted, "index.html", null)).toEqual({
+      status: "ready",
+      items: [],
+      drillInItem: null,
+    });
   });
 
   it("filters on label, tag and handle, case-insensitively", () => {
-    const elements = [
-      element({ hfId: "abc", label: "Headline", tag: "h1" }),
-      element({ domId: "cta", label: "Button", tag: "button" }),
+    const items = [
+      layer("Headline", { hfId: "abc", tagName: "h1" }),
+      layer("Button", { id: "cta", tagName: "button" }),
     ];
 
     const byLabel = expectOk<{ elements: { handle: string | null }[] }>(
-      buildStudioLook(snapshot({ elements }), { filter: "HEADLINE" }),
+      buildStudioLook(snapshot({ scene: { status: "ready", items, drillInItem: null } }), {
+        filter: "HEADLINE",
+      }),
     );
     const byTag = expectOk<{ elements: { handle: string | null }[] }>(
-      buildStudioLook(snapshot({ elements }), { filter: "button" }),
+      buildStudioLook(snapshot({ scene: { status: "ready", items, drillInItem: null } }), {
+        filter: "button",
+      }),
     );
     const byHandle = expectOk<{ elements: { handle: string | null }[] }>(
-      buildStudioLook(snapshot({ elements }), { filter: "hf:abc" }),
+      buildStudioLook(snapshot({ scene: { status: "ready", items, drillInItem: null } }), {
+        filter: "hf:v2:demo:index.html:index.html:abc",
+      }),
     );
 
-    expect(byLabel.elements.map((e) => e.handle)).toEqual(["hf:abc"]);
-    expect(byTag.elements.map((e) => e.handle)).toEqual(["dom:cta"]);
-    expect(byHandle.elements.map((e) => e.handle)).toEqual(["hf:abc"]);
+    expect(byLabel.elements.map((e) => e.handle)).toEqual(["hf:v2:demo:index.html:index.html:abc"]);
+    expect(byTag.elements.map((e) => e.handle)).toEqual(["dom:v2:demo:index.html:index.html:cta"]);
+    expect(byHandle.elements.map((e) => e.handle)).toEqual([
+      "hf:v2:demo:index.html:index.html:abc",
+    ]);
   });
 
   it("bounds a filter before normalizing it", () => {
     const boundedFilter = "x".repeat(128);
     const look = expectOk<{ elements: { handle: string | null }[] }>(
       buildStudioLook(
-        snapshot({ elements: [element({ domId: "bounded", label: boundedFilter })] }),
+        snapshot({
+          scene: {
+            status: "ready",
+            items: [layer(boundedFilter, { id: "bounded" })],
+            drillInItem: null,
+          },
+        }),
         { filter: `${boundedFilter}${"y".repeat(10_000)}` },
       ),
     );
 
-    expect(look.elements.map((entry) => entry.handle)).toEqual(["dom:bounded"]);
+    expect(look.elements.map((entry) => entry.handle)).toEqual([
+      "dom:v2:demo:index.html:index.html:bounded",
+    ]);
     expect(STUDIO_LOOK_INPUT_SCHEMA.properties.filter.maxLength).toBe(128);
   });
 
   it("keeps the true match count when the list is truncated", () => {
-    const elements = Array.from({ length: 5 }, (_, index) =>
-      element({ domId: `el-${index}`, label: "Card" }),
-    );
+    const items = Array.from({ length: 5 }, (_, index) => layer("Card", { id: `el-${index}` }));
 
-    const look = expectOk<{ elements: unknown[]; elementCount: number }>(
-      buildStudioLook(snapshot({ elements }), { limit: 2 }),
+    const look = expectOk<{ elements: unknown[]; elementCount: number; truncated: boolean }>(
+      buildStudioLook(snapshot({ scene: { status: "ready", items, drillInItem: null } }), {
+        filter: "card",
+        limit: 2,
+      }),
     );
 
     // A truncated list must not read as "that is all there is".
     expect(look.elements).toHaveLength(2);
     expect(look.elementCount).toBe(5);
+    expect(look.truncated).toBe(true);
+  });
+
+  it("preserves the 200-item default and maximum response bound", () => {
+    const items = Array.from({ length: 205 }, (_, index) =>
+      layer(`Layer ${index}`, { id: `el-${index}` }),
+    );
+
+    const look = expectOk<{ elements: unknown[]; elementCount: number; truncated: boolean }>(
+      buildStudioLook(snapshot({ scene: { status: "ready", items, drillInItem: null } })),
+    );
+
+    expect(look.elements).toHaveLength(200);
+    expect(look.elementCount).toBe(205);
+    expect(look.truncated).toBe(true);
   });
 
   it("clamps a nonsense limit instead of failing the call", () => {
-    const elements = [element({ domId: "a" }), element({ domId: "b" })];
+    const items = [layer("A", { id: "a" }), layer("B", { id: "b" })];
 
     for (const limit of [0, -3, 1.5, Number.NaN]) {
       const look = expectOk<{ elements: unknown[] }>(
-        buildStudioLook(snapshot({ elements }), { limit }),
+        buildStudioLook(snapshot({ scene: { status: "ready", items, drillInItem: null } }), {
+          limit,
+        }),
       );
       expect(look.elements).toHaveLength(2);
     }
@@ -178,7 +234,7 @@ describe("buildStudioLook", () => {
       selection: { handle: string | null; box: { width: number }; can: { editStyles: boolean } };
     }>(buildStudioLook(snapshot({ selection: selection() })));
 
-    expect(look.selection?.handle).toBe("hf:abc123");
+    expect(look.selection?.handle).toBe("hf:v2:demo:index.html:index.html:abc123");
     expect(look.selection?.box.width).toBe(880);
     expect(look.selection?.can.editStyles).toBe(true);
   });
@@ -222,4 +278,95 @@ describe("buildStudioLook", () => {
     expect(look).not.toHaveProperty("canWrite");
     expect(look).not.toHaveProperty("writeBlockedReason");
   });
+
+  it("returns DOM preorder with source-safe parents, DOM-only descendants, and optional timeline timing", () => {
+    const doc = sceneDoc();
+    const scene = collectStudioLookScene(doc, "index.html", null);
+    const look = expectOk<{
+      elements: Array<{
+        handle: string;
+        parentHandle: string | null;
+        depth: number;
+        sourceFile: string;
+        timeline: { start: number } | null;
+      }>;
+    }>(
+      buildStudioLook(
+        snapshot({
+          scene,
+          elements: [
+            element({ domId: "shell", sourceFile: "index.html", start: 2 }),
+            element({ domId: "duplicate", sourceFile: "compositions/nested.html", start: 4 }),
+          ],
+        }),
+      ),
+    );
+
+    expect(look.elements.map(({ sourceFile, depth }) => [sourceFile, depth])).toEqual([
+      ["index.html", 0],
+      ["index.html", 1],
+      ["index.html", 1],
+      ["compositions/nested.html", 1],
+      ["compositions/nested.html", 2],
+    ]);
+    expect(look.elements[1]?.parentHandle).toBe(look.elements[0]?.handle);
+    expect(look.elements[4]?.parentHandle).toBe(look.elements[3]?.handle);
+    expect(look.elements[2]?.timeline).toBeNull();
+    expect(look.elements[4]?.timeline?.start).toBe(4);
+    expect(look.elements[1]?.handle).not.toBe(look.elements[4]?.handle);
+  });
+
+  it("reports the current drill-in group separately without narrowing the whole scene", () => {
+    const doc = sceneDoc();
+    const group = doc.getElementById("nested-parent") as HTMLElement;
+    const look = expectOk<{
+      drillIn: { handle: string; label: string } | null;
+      elements: unknown[];
+    }>(buildStudioLook(snapshot({ scene: collectStudioLookScene(doc, "index.html", group) })));
+
+    expect(look.elements).toHaveLength(5);
+    expect(look.drillIn?.handle).toContain("nested-parent");
+  });
 });
+
+function layer(
+  label: string,
+  overrides: Partial<{
+    id: string;
+    hfId: string;
+    selector: string;
+    selectorIndex: number;
+    sourceFile: string;
+    tagName: string;
+    depth: number;
+    childCount: number;
+  }> = {},
+) {
+  const element = document.createElement(overrides.tagName ?? "div");
+  return {
+    key: label,
+    element,
+    label,
+    tagName: overrides.tagName ?? "div",
+    depth: overrides.depth ?? 0,
+    childCount: overrides.childCount ?? 0,
+    sourceFile: overrides.sourceFile ?? "index.html",
+    ...overrides,
+  };
+}
+
+function sceneDoc(): Document {
+  const doc = document.implementation.createHTMLDocument();
+  doc.body.innerHTML = `<main data-composition-id="root" data-composition-file="index.html">
+    <section id="shell">
+      <span id="duplicate">root duplicate</span>
+      <em class="dom-only">no timeline</em>
+      <div data-composition-id="nested" data-composition-file="compositions/nested.html">
+        <section id="nested-parent" data-hf-group>
+          <span id="duplicate">nested duplicate</span>
+        </section>
+      </div>
+    </section>
+  </main>`;
+  return doc;
+}