feat(studio): make agent edits visually legible

Author: miguel-heygen

CONCEPTS.md

@@ -20,7 +20,9 @@ The stage records the strongest fact actually proven. Completion of a request is
 
 ### Topology Lens
 
-The Topology Lens is Studio-only chrome that reveals the exact element an agent is inspecting or editing and reflects the write's receipt stage without becoming part of the composition output.
+The Topology Lens is Studio-only chrome that reveals the inspected source context, focuses the exact element an agent edits, and reflects the write's receipt stage without becoming part of the composition output.
+
+Its context field explains where the agent searched; its target focus proves what it chose. A persistence seal appears only when the receipt proves a durable write.
 
 ### Project Content Revision
 

docs/solutions/integration-issues/source-safe-proof-carrying-webmcp-edits.md

@@ -1,6 +1,7 @@
 ---
 title: Source-safe, proof-carrying WebMCP edits in Studio
 date: 2026-09-01
+last_updated: 2026-09-01
 category: integration-issues
 module: studio-webmcp
 problem_type: integration_issue
@@ -91,6 +92,14 @@ Receipts separate lifecycle from whether bytes changed:
 
 Fire-and-forget animation handlers remain `dispatched`. No-op saves preserve `changed: false`, and the Topology Lens does not show a success seal for them.
 
+### Visualize context and focus as different facts
+
+An agent edit has two spatial truths: the source boundary that explains where the agent searched, and the exact element that proves what it chose. The Topology Lens therefore measures both rectangles from the same source-scoped scene tree.
+
+During acquisition, the source field reveals first and labeled contours make the local topology legible. The exact target then receives the stronger focus border. During persistence, the complete HyperFrames mark resolves in the source field only after a durable receipt. The inspector and timeline remain unchanged because they do not own this transaction state.
+
+If the source boundary cannot be measured, the field falls back to the exact target rectangle. The target itself never falls back to an ancestor, because that would make a precise edit look broader than it was.
+
 ### Resolve animation state from the target
 
 Animation ownership and geometry routing use the explicit target's source file and element identity. The human selection cache is reusable only when it belongs to that exact live element. Raw JavaScript expressions are rejected at both the WebMCP input boundary and the server mutation boundary.
@@ -118,6 +127,7 @@ The Topology Lens is derived from the same receipt lifecycle, so its visual lang
 - Open a conflict breaker with work already queued and assert that queued work never starts.
 - Change project content during thumbnail generation and assert the generated pixels are not cached under the prior signature.
 - Capture Studio, the composition frame, and a thumbnail while the Topology Lens is active. Only Studio should contain it.
+- Capture acquisition and sealing after their first rendered frame. A state assertion can pass while clipping, stacking, or timing still makes the visual proof misleading.
 
 ## Related Issues
 

packages/studio/src/components/editor/TopologyLens.test.tsx

@@ -85,10 +85,23 @@ function finish(
 beforeEach(() => {
   vi.useFakeTimers();
   geometryMock.measure.mockReset().mockReturnValue({
-    target: { left: 10, top: 20, width: 200, height: 100, editScaleX: 1, editScaleY: 1 },
-    descendants: [
-      { left: 20, top: 30, width: 80, height: 20, editScaleX: 1, editScaleY: 1 },
-      { left: 110, top: 30, width: 60, height: 50, editScaleX: 1, editScaleY: 1 },
+    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 },
+      },
     ],
   });
 });
@@ -110,12 +123,26 @@ describe("TopologyLens", () => {
     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-seal="saved"]')).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));
@@ -126,12 +153,26 @@ describe("TopologyLens", () => {
   it("remeasures the post-write target before drawing the persistence seal", () => {
     geometryMock.measure
       .mockReturnValueOnce({
-        target: { left: 10, top: 20, width: 200, height: 100, editScaleX: 1, editScaleY: 1 },
-        descendants: [],
+        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({
-        target: { left: 70, top: 40, width: 240, height: 120, editScaleX: 1, editScaleY: 1 },
-        descendants: [],
+        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();

packages/studio/src/components/editor/TopologyLens.tsx

@@ -27,7 +27,7 @@ interface MeasuredLens {
   geometry: TopologyLensGeometry;
 }
 
-function rectStyle(rect: TopologyLensGeometry["target"]): CSSProperties {
+function rectStyle(rect: TopologyLensGeometry["target"]["rect"]): CSSProperties {
   return { left: rect.left, top: rect.top, width: rect.width, height: rect.height };
 }
 
@@ -147,24 +147,42 @@ export function TopologyLens({ iframeRef, activeCompositionPath }: TopologyLensP
     >
       {visible && (
         <>
-          {state.phase === "acquiring" && (
+          {(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.descendants.map((rect, index) => (
+              {geometry.contours.map(({ label, rect }, index) => (
                 <div
                   key={index}
                   data-topology-contour="true"
-                  className="hf-topology-contour pointer-events-none absolute rounded"
+                  data-topology-node={label}
+                  className="hf-topology-contour pointer-events-none absolute z-[1] rounded"
                   style={{
                     ...rectStyle(rect),
-                    animationDelay: `${Math.min(index, 8) * 8}ms`,
+                    animationDelay: `${Math.min(index, 5) * 28}ms`,
                   }}
                 />
               ))}
               {!reducedMotion && (
                 <div
                   data-topology-scan="true"
-                  className="pointer-events-none absolute overflow-hidden rounded"
-                  style={rectStyle(geometry.target)}
+                  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>
@@ -173,21 +191,14 @@ export function TopologyLens({ iframeRef, activeCompositionPath }: TopologyLensP
           )}
           <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 rounded-md"
-            style={rectStyle(geometry.target)}
-          >
-            {state.phase === "sealing" && (
-              <HyperframesMark
-                data-topology-seal={state.receiptStage}
-                className="hf-topology-seal absolute right-1.5 top-1.5 h-5 w-8 overflow-visible"
-                viewBox="0 18 100 64"
-              />
-            )}
-          </div>
+            className="hf-topology-target pointer-events-none absolute z-[3] rounded-md"
+            style={rectStyle(geometry.target.rect)}
+          />
         </>
       )}
     </div>

packages/studio/src/components/editor/topologyLensGeometry.test.ts

@@ -6,13 +6,15 @@ import { previewDoc } from "../../webmcp/webmcpTestUtils";
 import { resolveTopologyLensElements } from "./topologyLensGeometry";
 
 describe("Topology Lens scene geometry", () => {
-  it("uses the source-safe Studio scene preorder and excludes unrelated branches", () => {
+  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">
-          <div id="duplicate"><strong id="nested-child">nested</strong></div>
-          <aside id="unrelated">outside target</aside>
+          <article id="nested-context">
+            <div id="duplicate"><strong id="nested-child">nested</strong></div>
+            <aside id="unrelated">outside target</aside>
+          </article>
         </section>
       </main>
     `);
@@ -26,7 +28,10 @@ describe("Topology Lens scene geometry", () => {
     const resolved = resolveTopologyLensElements(doc, "index.html", handle);
 
     expect(resolved?.target.textContent).toBe("nested");
-    expect(resolved?.descendants.map((element) => element.id)).toEqual(["nested-child"]);
+    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", () => {

packages/studio/src/components/editor/topologyLensGeometry.ts

@@ -1,10 +1,48 @@
 import { resolveElementHandle } from "../../webmcp/handles";
 import { collectStudioLookScene } from "../../webmcp/tools/lookTools";
+import type { DomEditLayerItem } from "./domEditingTypes";
 import { toVisibleOverlayRects, type OverlayRect } from "./domEditOverlayGeometry";
 
+export interface TopologyLensNode {
+  label: string;
+  rect: OverlayRect;
+}
+
 export interface TopologyLensGeometry {
-  target: OverlayRect;
-  descendants: OverlayRect[];
+  field: TopologyLensNode;
+  target: TopologyLensNode;
+  contours: TopologyLensNode[];
+}
+
+function findSourceContextIndex(items: readonly DomEditLayerItem[], targetIndex: number): number {
+  const target = items[targetIndex]!;
+  let contextIndex = targetIndex;
+  let parentDepth = target.depth - 1;
+  for (let index = targetIndex - 1; index >= 0 && parentDepth >= 0; index--) {
+    const item = items[index]!;
+    if (item.depth !== parentDepth) continue;
+    if (item.sourceFile !== target.sourceFile) break;
+    contextIndex = index;
+    parentDepth -= 1;
+  }
+  return contextIndex;
+}
+
+function collectSourceContours(
+  items: readonly DomEditLayerItem[],
+  contextIndex: number,
+  target: DomEditLayerItem,
+): HTMLElement[] {
+  const context = items[contextIndex]!;
+  const contours: HTMLElement[] = [];
+  for (let index = contextIndex + 1; index < items.length; index++) {
+    const item = items[index]!;
+    if (item.depth <= context.depth) break;
+    if (item.sourceFile === target.sourceFile && item.element !== target.element) {
+      contours.push(item.element);
+    }
+  }
+  return contours;
 }
 
 /**
@@ -16,22 +54,29 @@ export function resolveTopologyLensElements(
   doc: Document,
   activeCompositionPath: string | null,
   handle: string,
-): { target: HTMLElement; descendants: HTMLElement[] } | null {
+): { context: HTMLElement; target: HTMLElement; contours: HTMLElement[] } | null {
   const target = resolveElementHandle(doc, handle);
   if (!target) return null;
   const scene = collectStudioLookScene(doc, activeCompositionPath, null);
   if (scene.status === "loading") return null;
   const targetIndex = scene.items.findIndex((item) => item.element === target);
-  if (targetIndex < 0) return { target, descendants: [] };
-
-  const targetDepth = scene.items[targetIndex]!.depth;
-  const descendants: HTMLElement[] = [];
-  for (let index = targetIndex + 1; index < scene.items.length; index++) {
-    const item = scene.items[index]!;
-    if (item.depth <= targetDepth) break;
-    descendants.push(item.element);
-  }
-  return { target, descendants };
+  if (targetIndex < 0) return { context: target, target, contours: [] };
+
+  const targetItem = scene.items[targetIndex]!;
+  const contextIndex = findSourceContextIndex(scene.items, targetIndex);
+  const contextItem = scene.items[contextIndex]!;
+  const sourceContext = target.closest<HTMLElement>(
+    "[data-composition-file], [data-composition-src]",
+  );
+  return {
+    context: sourceContext ?? contextItem.element,
+    target,
+    contours: collectSourceContours(scene.items, contextIndex, targetItem),
+  };
+}
+
+function isRenderableRect(rect: OverlayRect | null | undefined): rect is OverlayRect {
+  return Boolean(rect && rect.width > 0 && rect.height > 0);
 }
 
 export function measureTopologyLensGeometry(input: {
@@ -44,16 +89,31 @@ export function measureTopologyLensGeometry(input: {
   if (!doc) return null;
   const elements = resolveTopologyLensElements(doc, input.activeCompositionPath, input.handle);
   if (!elements) return null;
-  const measured = toVisibleOverlayRects(input.overlay, input.iframe, [
-    elements.target,
-    ...elements.descendants,
-  ]);
-  const target = measured[0];
-  if (!target || target.width <= 0 || target.height <= 0) return null;
+  const sharedField = elements.context === elements.target;
+  const measured = toVisibleOverlayRects(
+    input.overlay,
+    input.iframe,
+    sharedField
+      ? [elements.target, ...elements.contours]
+      : [elements.context, elements.target, ...elements.contours],
+  );
+  const target = measured[sharedField ? 0 : 1];
+  if (!isRenderableRect(target)) return null;
+  const measuredField = measured[0];
+  const fieldUsesContext = !sharedField && isRenderableRect(measuredField);
+  const contourOffset = sharedField ? 1 : 2;
   return {
-    target,
-    descendants: measured
-      .slice(1)
-      .filter((rect): rect is OverlayRect => Boolean(rect && rect.width > 0 && rect.height > 0)),
+    field: {
+      label: (fieldUsesContext ? elements.context : elements.target).tagName.toLowerCase(),
+      rect: fieldUsesContext ? measuredField : target,
+    },
+    target: { label: elements.target.tagName.toLowerCase(), rect: target },
+    contours: measured
+      .slice(contourOffset)
+      .map((rect, index) => ({
+        label: elements.contours[index]!.tagName.toLowerCase(),
+        rect,
+      }))
+      .filter((item): item is TopologyLensNode => isRenderableRect(item.rect)),
   };
 }