@hyperframes/studio 0.8.23 → 0.8.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.23",
+  "version": "0.8.25",
   "description": "",
   "repository": {
     "type": "git",
@@ -48,11 +48,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.23",
-    "@hyperframes/parsers": "0.8.23",
-    "@hyperframes/player": "0.8.23",
-    "@hyperframes/sdk": "0.8.23",
-    "@hyperframes/studio-server": "0.8.23"
+    "@hyperframes/parsers": "0.8.25",
+    "@hyperframes/core": "0.8.25",
+    "@hyperframes/player": "0.8.25",
+    "@hyperframes/studio-server": "0.8.25",
+    "@hyperframes/sdk": "0.8.25"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -69,7 +69,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.23"
+    "@hyperframes/producer": "0.8.25"
   },
   "peerDependencies": {
     "react": "19",
@@ -81,6 +81,7 @@
     "build": "vite build && tsup",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "test:webmcp-edit-loop": "node tests/e2e/webmcp-edit-loop.mjs",
     "test:timeline-virtualization": "TIMELINE_ROW_VIRTUALIZATION=on TIMELINE_ELEMENT_COUNT=50000 node tests/e2e/timeline-virtualization.mjs",
     "test:watch": "vitest",
     "report:sdk-cutover": "bun src/utils/sdkCutoverPolicy.report.ts",

package/src/components/editor/TopologyLens.test.tsx

@@ -0,0 +1,294 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { studioEditLifecycle, type StudioWriteResult } from "../../webmcp/writeCoordinator";
+import { TopologyLens } from "./TopologyLens";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const geometryMock = vi.hoisted(() => ({ measure: vi.fn() }));
+vi.mock("./topologyLensGeometry", () => ({
+  measureTopologyLensGeometry: geometryMock.measure,
+}));
+
+const target = { handle: "dom:target", sourceFile: "index.html" };
+let root: Root | null = null;
+let host: HTMLDivElement | null = null;
+let iframe: HTMLIFrameElement | null = null;
+
+function matchMedia(reducedMotion: boolean): typeof window.matchMedia {
+  return vi.fn().mockReturnValue({
+    matches: reducedMotion,
+    media: "(prefers-reduced-motion: reduce)",
+    onchange: null,
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    dispatchEvent: vi.fn(),
+  });
+}
+
+function mount(reducedMotion = false, strictMode = false): void {
+  window.matchMedia = matchMedia(reducedMotion);
+  host = document.createElement("div");
+  iframe = document.createElement("iframe");
+  document.body.append(host, iframe);
+  root = createRoot(host);
+  act(() => {
+    const lens = (
+      <TopologyLens iframeRef={{ current: iframe }} activeCompositionPath="index.html" />
+    );
+    root?.render(strictMode ? <React.StrictMode>{lens}</React.StrictMode> : lens);
+  });
+}
+
+function begin(): string {
+  let callId = "";
+  act(() => {
+    callId = studioEditLifecycle.begin("project-a", target, "set-text");
+  });
+  return callId;
+}
+
+function finish(
+  callId: string,
+  stage: "dispatched" | "saved" | "verified" | "failed",
+  changed = true,
+): void {
+  const result: StudioWriteResult<object> =
+    stage === "failed"
+      ? {
+          ok: false,
+          kind: "failed",
+          reason: "save failed",
+          stage,
+          target,
+          operation: "set-text",
+        }
+      : {
+          ok: true,
+          stage,
+          target,
+          operation: "set-text",
+          changed,
+          evidence:
+            stage === "dispatched"
+              ? { kind: "dispatch", followUp: "studio_inspect" }
+              : { kind: "content-version", sourceFile: "index.html", version: "v1" },
+        };
+  act(() => studioEditLifecycle.finish(callId, result));
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  geometryMock.measure.mockReset().mockReturnValue({
+    field: {
+      label: "section",
+      rect: { left: 5, top: 10, width: 320, height: 180, editScaleX: 1, editScaleY: 1 },
+    },
+    target: {
+      label: "h1",
+      rect: { left: 10, top: 20, width: 200, height: 100, editScaleX: 1, editScaleY: 1 },
+    },
+    contours: [
+      {
+        label: "p",
+        rect: { left: 20, top: 30, width: 80, height: 20, editScaleX: 1, editScaleY: 1 },
+      },
+      {
+        label: "aside",
+        rect: { left: 110, top: 30, width: 60, height: 50, editScaleX: 1, editScaleY: 1 },
+      },
+    ],
+  });
+});
+
+afterEach(() => {
+  if (root) act(() => root?.unmount());
+  act(() => vi.runOnlyPendingTimers());
+  root = null;
+  host = null;
+  iframe = null;
+  studioEditLifecycle.reset();
+  document.body.replaceChildren();
+  vi.useRealTimers();
+});
+
+describe("TopologyLens", () => {
+  it("reveals real contours for a new target and seals only a durable receipt", () => {
+    mount();
+    const callId = begin();
+
+    expect(host?.querySelector('[data-topology-lens="acquiring"]')).not.toBeNull();
+    expect(
+      host?.querySelector('[data-topology-field="true"][data-topology-node="section"]'),
+    ).not.toBeNull();
+    expect(host?.querySelector('[data-topology-target][data-topology-node="h1"]')).not.toBeNull();
+    expect(host?.querySelectorAll('[data-topology-contour="true"]')).toHaveLength(2);
+    expect(
+      [...(host?.querySelectorAll<HTMLElement>("[data-topology-contour]") ?? [])].map(
+        (element) => element.dataset.topologyNode,
+      ),
+    ).toEqual(["p", "aside"]);
+    expect(host?.querySelector('[data-topology-scan="true"]')).not.toBeNull();
+
+    finish(callId, "saved");
+    expect(host?.querySelector('[data-topology-lens="sealing"]')).not.toBeNull();
+    expect(
+      host
+        ?.querySelector('[data-topology-field][data-topology-phase="sealing"]')
+        ?.querySelector('[data-topology-seal="saved"]'),
+    ).not.toBeNull();
+    expect(host?.querySelector("[data-topology-target] [data-topology-seal]")).toBeNull();
+    expect(geometryMock.measure).toHaveBeenCalledTimes(2);
+
+    act(() => vi.advanceTimersByTime(240));
+    expect(host?.querySelector('[data-topology-lens="hidden"]')).not.toBeNull();
+    expect(studioEditLifecycle.getSnapshot()).toEqual({ phase: "idle" });
+  });
+
+  it("remeasures the post-write target before drawing the persistence seal", () => {
+    geometryMock.measure
+      .mockReturnValueOnce({
+        field: {
+          label: "section",
+          rect: { left: 5, top: 10, width: 300, height: 180, editScaleX: 1, editScaleY: 1 },
+        },
+        target: {
+          label: "h1",
+          rect: { left: 10, top: 20, width: 200, height: 100, editScaleX: 1, editScaleY: 1 },
+        },
+        contours: [],
+      })
+      .mockReturnValueOnce({
+        field: {
+          label: "section",
+          rect: { left: 50, top: 20, width: 360, height: 220, editScaleX: 1, editScaleY: 1 },
+        },
+        target: {
+          label: "h1",
+          rect: { left: 70, top: 40, width: 240, height: 120, editScaleX: 1, editScaleY: 1 },
+        },
+        contours: [],
+      });
+    mount();
+    const callId = begin();
+    expect(host?.querySelector<HTMLElement>("[data-topology-target]")?.style.left).toBe("10px");
+
+    finish(callId, "verified");
+
+    const sealedTarget = host?.querySelector<HTMLElement>("[data-topology-target]");
+    expect(sealedTarget?.style.left).toBe("70px");
+    expect(sealedTarget?.style.width).toBe("240px");
+    expect(host?.querySelector('[data-topology-seal="verified"]')).not.toBeNull();
+  });
+
+  it("skips acquisition when the coordinator identifies a repeated target", () => {
+    mount();
+    const firstCall = begin();
+    finish(firstCall, "saved");
+    act(() => vi.advanceTimersByTime(240));
+
+    begin();
+
+    expect(host?.querySelector('[data-topology-lens="localizing"]')).not.toBeNull();
+    expect(host?.querySelector('[data-topology-contour="true"]')).toBeNull();
+  });
+
+  it.each(["dispatched", "failed"] as const)("retracts %s without a seal", (stage) => {
+    mount();
+    const callId = begin();
+
+    finish(callId, stage);
+
+    expect(host?.querySelector('[data-topology-lens="localizing"]')).not.toBeNull();
+    expect(host?.querySelector("[data-topology-seal]")).toBeNull();
+    act(() => vi.advanceTimersByTime(180));
+    expect(host?.querySelector('[data-topology-lens="hidden"]')).not.toBeNull();
+    expect(studioEditLifecycle.getSnapshot()).toEqual({ phase: "idle" });
+  });
+
+  it.each(["saved", "verified"] as const)("retracts a %s no-op without a seal", (stage) => {
+    mount();
+    const callId = begin();
+
+    finish(callId, stage, false);
+
+    expect(host?.querySelector('[data-topology-lens="localizing"]')).not.toBeNull();
+    expect(host?.querySelector('[data-topology-terminal="no-change"]')).not.toBeNull();
+    expect(host?.querySelector("[data-topology-seal]")).toBeNull();
+    act(() => vi.advanceTimersByTime(180));
+    expect(host?.querySelector('[data-topology-lens="hidden"]')).not.toBeNull();
+  });
+
+  it("does not replay a terminal seal after the overlay remounts", () => {
+    mount();
+    const callId = begin();
+    finish(callId, "saved");
+    act(() => vi.advanceTimersByTime(240));
+    expect(studioEditLifecycle.getSnapshot()).toEqual({ phase: "idle" });
+
+    act(() => root?.unmount());
+    root = null;
+    host?.remove();
+    iframe?.remove();
+    mount();
+
+    expect(host?.querySelector('[data-topology-lens="hidden"]')).not.toBeNull();
+    expect(host?.querySelector("[data-topology-seal]")).toBeNull();
+  });
+
+  it("keeps an active invocation through StrictMode effect replay", () => {
+    const callId = begin();
+
+    mount(false, true);
+    act(() => vi.advanceTimersByTime(0));
+
+    expect(studioEditLifecycle.getSnapshot()).toMatchObject({
+      callId,
+      phase: "dispatching",
+    });
+    expect(host?.querySelector('[data-topology-lens="acquiring"]')).not.toBeNull();
+  });
+
+  it("clears on iframe reload and project switch", () => {
+    mount();
+    begin();
+
+    act(() => iframe?.dispatchEvent(new Event("load")));
+    expect(host?.querySelector('[data-topology-lens="hidden"]')).not.toBeNull();
+
+    begin();
+    act(() => studioEditLifecycle.activateProject("project-b"));
+    expect(host?.querySelector('[data-topology-lens="hidden"]')).not.toBeNull();
+  });
+
+  it("removes spatial travel in reduced motion while preserving target state", () => {
+    mount(true);
+    begin();
+
+    expect(host?.querySelector('[data-topology-lens="acquiring"]')).not.toBeNull();
+    expect(host?.querySelector('[data-topology-contour="true"]')).not.toBeNull();
+    expect(host?.querySelector('[data-topology-scan="true"]')).toBeNull();
+  });
+
+  it("cleans its timer and iframe listener on unmount", () => {
+    mount();
+    const removeListener = vi.spyOn(iframe!, "removeEventListener");
+    begin();
+    expect(vi.getTimerCount()).toBe(1);
+
+    act(() => root?.unmount());
+    root = null;
+
+    expect(vi.getTimerCount()).toBe(1);
+    expect(removeListener).toHaveBeenCalledWith("load", expect.any(Function));
+    expect(studioEditLifecycle.getSnapshot()).toMatchObject({ phase: "dispatching" });
+    act(() => vi.advanceTimersByTime(0));
+    expect(vi.getTimerCount()).toBe(0);
+    expect(studioEditLifecycle.getSnapshot()).toEqual({ phase: "idle" });
+  });
+});

package/src/components/editor/TopologyLens.tsx

@@ -0,0 +1,206 @@
+import {
+  useEffect,
+  useLayoutEffect,
+  useReducer,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  type CSSProperties,
+  type RefObject,
+} from "react";
+import { studioEditLifecycle } from "../../webmcp/writeCoordinator";
+import { HyperframesMark } from "../ui/HyperframesMark";
+import { measureTopologyLensGeometry, type TopologyLensGeometry } from "./topologyLensGeometry";
+import { reduceTopologyLens, type TopologyLensState } from "./topologyLensState";
+
+const ACQUISITION_MS = 240;
+const TERMINAL_RETRACT_MS = 180;
+const SEAL_MS = 240;
+
+interface TopologyLensProps {
+  iframeRef: RefObject<HTMLIFrameElement | null>;
+  activeCompositionPath: string | null;
+}
+
+interface MeasuredLens {
+  callId: string;
+  geometry: TopologyLensGeometry;
+}
+
+function rectStyle(rect: TopologyLensGeometry["target"]["rect"]): CSSProperties {
+  return { left: rect.left, top: rect.top, width: rect.width, height: rect.height };
+}
+
+function getReducedMotion(): boolean {
+  return window.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false;
+}
+
+function subscribeReducedMotion(listener: () => void): () => void {
+  const query = window.matchMedia?.("(prefers-reduced-motion: reduce)");
+  if (!query) return () => undefined;
+  query.addEventListener("change", listener);
+  return () => query.removeEventListener("change", listener);
+}
+
+function useTopologyLensState(): TopologyLensState {
+  const lifecycle = useSyncExternalStore(
+    studioEditLifecycle.subscribe,
+    studioEditLifecycle.getSnapshot,
+    studioEditLifecycle.getSnapshot,
+  );
+  const [state, dispatch] = useReducer(
+    reduceTopologyLens,
+    lifecycle,
+    (initialLifecycle): TopologyLensState =>
+      reduceTopologyLens({ phase: "hidden" }, { type: "lifecycle", value: initialLifecycle }),
+  );
+
+  useEffect(() => dispatch({ type: "lifecycle", value: lifecycle }), [lifecycle]);
+  useEffect(() => {
+    if (state.phase === "hidden") return;
+    const delay =
+      state.phase === "acquiring"
+        ? ACQUISITION_MS
+        : state.phase === "sealing"
+          ? SEAL_MS
+          : state.terminal
+            ? TERMINAL_RETRACT_MS
+            : null;
+    if (delay === null) return;
+    const timeout = window.setTimeout(() => {
+      if (state.phase === "acquiring") {
+        dispatch({ type: "acquisition-elapsed", callId: state.callId });
+        return;
+      }
+      studioEditLifecycle.dismiss(state.callId);
+    }, delay);
+    return () => window.clearTimeout(timeout);
+  }, [state]);
+
+  return state;
+}
+
+/** Studio-parent chrome driven by the same invocation and receipt as WebMCP. */
+export function TopologyLens({ iframeRef, activeCompositionPath }: TopologyLensProps) {
+  const overlayRef = useRef<HTMLDivElement | null>(null);
+  const state = useTopologyLensState();
+  const reducedMotion = useSyncExternalStore(subscribeReducedMotion, getReducedMotion, () => false);
+  const [measured, setMeasured] = useState<MeasuredLens | null>(null);
+  const callId = state.phase === "hidden" ? null : state.callId;
+  const handle = state.phase === "hidden" ? null : state.target.handle;
+  const phase = state.phase;
+  const ownedCallIdRef = useRef(callId);
+  const pendingUnmountDismissRef = useRef<number | null>(null);
+  ownedCallIdRef.current = callId;
+
+  useLayoutEffect(() => {
+    if (!callId || !handle) {
+      setMeasured(null);
+      return;
+    }
+    const overlay = overlayRef.current;
+    const iframe = iframeRef.current;
+    if (!overlay || !iframe) {
+      setMeasured(null);
+      return;
+    }
+    const geometry = measureTopologyLensGeometry({
+      overlay,
+      iframe,
+      activeCompositionPath,
+      handle,
+    });
+    setMeasured(geometry ? { callId, geometry } : null);
+  }, [activeCompositionPath, callId, handle, iframeRef, phase]);
+
+  useEffect(() => {
+    const iframe = iframeRef.current;
+    if (!iframe || !callId) return;
+    const dismiss = () => studioEditLifecycle.dismiss(callId);
+    iframe.addEventListener("load", dismiss);
+    return () => iframe.removeEventListener("load", dismiss);
+  }, [callId, iframeRef]);
+
+  useEffect(() => {
+    if (pendingUnmountDismissRef.current !== null) {
+      window.clearTimeout(pendingUnmountDismissRef.current);
+      pendingUnmountDismissRef.current = null;
+    }
+    return () => {
+      const ownedCallId = ownedCallIdRef.current;
+      if (!ownedCallId) return;
+      pendingUnmountDismissRef.current = window.setTimeout(() => {
+        pendingUnmountDismissRef.current = null;
+        studioEditLifecycle.dismiss(ownedCallId);
+      }, 0);
+    };
+  }, []);
+
+  const geometry = measured?.callId === callId ? measured.geometry : null;
+  const visible = state.phase !== "hidden" && geometry;
+  return (
+    <div
+      ref={overlayRef}
+      aria-hidden="true"
+      data-topology-lens={visible ? state.phase : "hidden"}
+      className="pointer-events-none absolute inset-0 z-[58] overflow-hidden"
+    >
+      {visible && (
+        <>
+          {(state.phase === "acquiring" || state.phase === "sealing") && (
+            <div
+              data-topology-field="true"
+              data-topology-node={geometry.field.label}
+              data-topology-phase={state.phase}
+              className="hf-topology-field pointer-events-none absolute overflow-hidden rounded-md"
+              style={rectStyle(geometry.field.rect)}
+            >
+              {state.phase === "sealing" && (
+                <HyperframesMark
+                  data-topology-seal={state.receiptStage}
+                  className="hf-topology-seal absolute right-2 top-2 h-7 w-11 overflow-visible"
+                  viewBox="0 18 100 64"
+                />
+              )}
+            </div>
+          )}
+          {(state.phase === "acquiring" || state.phase === "sealing") && (
+            <>
+              {geometry.contours.map(({ label, rect }, index) => (
+                <div
+                  key={index}
+                  data-topology-contour="true"
+                  data-topology-node={label}
+                  className="hf-topology-contour pointer-events-none absolute z-[1] rounded"
+                  style={{
+                    ...rectStyle(rect),
+                    animationDelay: `${Math.min(index, 5) * 28}ms`,
+                  }}
+                />
+              ))}
+              {!reducedMotion && (
+                <div
+                  data-topology-scan="true"
+                  className="pointer-events-none absolute z-[2] overflow-hidden rounded"
+                  style={rectStyle(geometry.field.rect)}
+                >
+                  <div className="hf-topology-scan absolute inset-y-0 left-0 w-1/4" />
+                </div>
+              )}
+            </>
+          )}
+          <div
+            data-topology-target="true"
+            data-topology-node={geometry.target.label}
+            data-topology-phase={state.phase}
+            data-topology-terminal={
+              state.phase === "localizing" ? (state.terminal ?? undefined) : undefined
+            }
+            className="hf-topology-target pointer-events-none absolute z-[3] rounded-md"
+            style={rectStyle(geometry.target.rect)}
+          />
+        </>
+      )}
+    </div>
+  );
+}

package/src/components/editor/domEditOverlayGeometry.ts

@@ -107,6 +107,20 @@ export function toVisibleOverlayRect(
   return rect ? { ...rect, ...hugRectForElement(rect, element) } : null;
 }
 
+/** Batch transient chrome through one shared iframe-to-overlay coordinate basis. */
+export function toVisibleOverlayRects(
+  overlayEl: HTMLDivElement,
+  iframe: HTMLIFrameElement,
+  elements: readonly HTMLElement[],
+): Array<OverlayRect | null> {
+  const scale = computeOverlayRootScale(overlayEl, iframe, iframe.contentDocument);
+  if (!scale) return elements.map(() => null);
+  return elements.map((element) => {
+    const rect = toOverlayRect(overlayEl, iframe, element, scale);
+    return rect ? { ...rect, ...hugRectForElement(rect, element) } : null;
+  });
+}
+
 /**
  * getComputedStyle(element).transform decomposed into a DOMMatrix, read ONCE.
  * Shared by orientedOverlayRect's rotation gate and elementCornerOverlayPoints

package/src/components/editor/domEditOverlayGeometryBatch.test.ts

@@ -0,0 +1,18 @@
+// @vitest-environment happy-dom
+
+import { expect, it, vi } from "vitest";
+import { toVisibleOverlayRects } from "./domEditOverlayGeometry";
+
+it("does not fall back to per-element basis reads when the shared basis is unavailable", () => {
+  const overlay = document.createElement("div");
+  const iframe = document.createElement("iframe");
+  document.body.append(overlay, iframe);
+  const doc = iframe.contentDocument;
+  if (!doc) throw new Error("expected iframe document");
+  doc.body.innerHTML = '<main data-composition-id="root"><div id="target"></div></main>';
+  const target = doc.getElementById("target") as HTMLElement;
+  const targetRead = vi.spyOn(target, "getBoundingClientRect");
+
+  expect(toVisibleOverlayRects(overlay, iframe, [target])).toEqual([null]);
+  expect(targetRead).not.toHaveBeenCalled();
+});

package/src/components/editor/domEditingLayers.test.ts

@@ -126,6 +126,15 @@ describe("resolveDomEditSelection — data-hf-group capture", () => {
     expect(selection?.selector).toBe('[data-hf-group="Group 1"]');
   });
 
+  it("resolves an explicit agent target without promoting it to the group", async () => {
+    const { parent, child } = buildNestedGroups();
+    const selection = await resolveDomEditSelection(child, { ...opts, exactTarget: true });
+    document.body.removeChild(parent);
+
+    expect(selection?.element).toBe(child);
+    expect(selection?.id).toBe("child");
+  });
+
   it("selects the next nested group when drilled into the outer group", async () => {
     const { parent, outer, inner, child } = buildNestedGroups();
     const selection = await resolveDomEditSelection(child, { ...opts, activeGroupElement: outer });

package/src/components/editor/domEditingLayers.ts

@@ -281,10 +281,6 @@ export function resolveDomEditCapabilities(args: {
   ).capabilities;
 }
 
-// ─── Element label ────────────────────────────────────────────────────────────
-
-// ─── Source probe ────────────────────────────────────────────────────────────
-
 async function probeSourceElement(
   projectId: string,
   sourceFile: string,
@@ -310,17 +306,21 @@ async function probeSourceElement(
   }
 }
 
-// ─── Selection resolution ────────────────────────────────────────────────────
-
 // fallow-ignore-next-line complexity
 export async function resolveDomEditSelection(
   startEl: HTMLElement | null,
-  options: DomEditContextOptions & { projectId?: string | null; skipSourceProbe?: boolean },
+  options: DomEditContextOptions & {
+    projectId?: string | null;
+    skipSourceProbe?: boolean;
+    exactTarget?: boolean;
+  },
 ): Promise<DomEditSelection | null> {
   if (!startEl) return null;
   const doc = startEl.ownerDocument;
 
-  let capture = resolveGroupCapture(startEl, options.activeGroupElement ?? null);
+  let capture = options.exactTarget
+    ? ({ kind: "unit", element: startEl } as const)
+    : resolveGroupCapture(startEl, options.activeGroupElement ?? null);
   if (capture.kind === "out-of-scope") {
     // Drill-in is non-sticky: clicking/hovering OUTSIDE the drilled-into group
     // exits it and resolves the target normally, rather than selecting nothing

package/src/components/editor/topologyLensGeometry.test.ts

@@ -0,0 +1,44 @@
+// @vitest-environment jsdom
+
+import { describe, expect, it } from "vitest";
+import { mintElementHandle } from "../../webmcp/handles";
+import { previewDoc } from "../../webmcp/webmcpTestUtils";
+import { resolveTopologyLensElements } from "./topologyLensGeometry";
+
+describe("Topology Lens scene geometry", () => {
+  it("reveals the nearest same-source context while preserving the exact target", () => {
+    const doc = previewDoc(`
+      <main data-composition-id="root" data-composition-file="index.html">
+        <section id="duplicate"><span id="root-child">root</span></section>
+        <section data-composition-id="nested" data-composition-file="compositions/nested.html">
+          <article id="nested-context">
+            <div id="duplicate"><strong id="nested-child">nested</strong></div>
+            <aside id="unrelated">outside target</aside>
+          </article>
+        </section>
+      </main>
+    `);
+    const handle = mintElementHandle({
+      domId: "duplicate",
+      sourceFile: "compositions/nested.html",
+      activeCompositionPath: "index.html",
+    });
+    if (!handle) throw new Error("expected source-safe handle");
+
+    const resolved = resolveTopologyLensElements(doc, "index.html", handle);
+
+    expect(resolved?.target.textContent).toBe("nested");
+    expect(resolved?.context.getAttribute("data-composition-file")).toBe(
+      "compositions/nested.html",
+    );
+    expect(resolved?.contours.map((element) => element.id)).toEqual(["nested-child", "unrelated"]);
+  });
+
+  it("returns no geometry for a stale handle", () => {
+    const doc = previewDoc(
+      '<main data-composition-id="root" data-composition-file="index.html"></main>',
+    );
+
+    expect(resolveTopologyLensElements(doc, "index.html", "dom:missing")).toBeNull();
+  });
+});