From 41cb576256fc0f801c15fd686640b4c3337657d0 Mon Sep 17 00:00:00 2001
From: Ljy-0827 <liujunyao0827@gmail.com>
Date: Thu, 20 Aug 2026 15:14:41 +0800
Subject: [PATCH 1/5] feat(vom): function refactor

---
 .../src/tools/__tests__/observation.test.ts   |  10 +-
 apps/extension/src/tools/observation.ts       | 955 ++++--------------
 .../tools/vom/__tests__/frame-capture.test.ts |  63 ++
 .../vom/__tests__/semantic-graph.test.ts      | 215 ++++
 apps/extension/src/tools/vom/capture.ts       |   8 +-
 apps/extension/src/tools/vom/frame-capture.ts |  46 +-
 .../src/tools/vom/semantic-graph/build.ts     | 154 +++
 .../src/tools/vom/semantic-graph/index.ts     |  26 +
 .../src/tools/vom/semantic-graph/project.ts   | 242 +++++
 .../src/tools/vom/semantic-graph/resolve.ts   | 527 ++++++++++
 .../src/tools/vom/semantic-graph/types.ts     |  69 ++
 packages/vom/src/render.ts                    |   5 +-
 packages/vom/src/types.ts                     |   2 +
 13 files changed, 1525 insertions(+), 797 deletions(-)
 create mode 100644 apps/extension/src/tools/vom/__tests__/semantic-graph.test.ts
 create mode 100644 apps/extension/src/tools/vom/semantic-graph/build.ts
 create mode 100644 apps/extension/src/tools/vom/semantic-graph/index.ts
 create mode 100644 apps/extension/src/tools/vom/semantic-graph/project.ts
 create mode 100644 apps/extension/src/tools/vom/semantic-graph/resolve.ts
 create mode 100644 apps/extension/src/tools/vom/semantic-graph/types.ts

diff --git a/apps/extension/src/tools/__tests__/observation.test.ts b/apps/extension/src/tools/__tests__/observation.test.ts
index bd8200bb..a560f3e4 100644
--- a/apps/extension/src/tools/__tests__/observation.test.ts
+++ b/apps/extension/src/tools/__tests__/observation.test.ts
@@ -1656,7 +1656,7 @@ describe("buildVomScene", () => {
 
     const scene = buildVomScene(axNodes, captured);
     expect(scene.nodes.find((n) => n.id === 20)).toEqual(
-      expect.objectContaining({ id: 20, role: "generic", cursor: "pointer" }),
+      expect.objectContaining({ id: 20, role: "button", name: "close", cursor: "pointer" }),
     );
     const rendered = renderVom(scene);
     expect(rendered.text).toContain('@e1 button "close"');
@@ -1732,7 +1732,7 @@ describe("buildVomScene", () => {
     };
 
     const scene = buildVomScene(axNodes, captured);
-    expect(scene.nodes.find((n) => n.id === 20)?.role).toBe("generic");
+    expect(scene.nodes.find((n) => n.id === 20)).toBeUndefined();
     expect(scene.nodes.find((n) => n.id === 30)?.role).toBe("link");
   });
 
@@ -1801,9 +1801,9 @@ describe("buildVomScene", () => {
 
     const scene = buildVomScene(axNodes, captured);
     expect(scene.nodes.find((n) => n.id === 20)).toEqual(
-      expect.objectContaining({ id: 20, role: "generic", attrs: { "aria-label": "收藏" } }),
+      expect.objectContaining({ id: 20, role: "button", attrs: { "aria-label": "收藏" } }),
     );
-    expect(scene.nodes.find((n) => n.id === 30)?.role).toBe("generic");
+    expect(scene.nodes.find((n) => n.id === 30)).toBeUndefined();
     const rendered = renderVom(scene);
     expect(rendered.text).toContain('@e1 button "收藏"');
     expect(rendered.refs.map(({ ref, backendNodeId }) => ({ ref, backendNodeId }))).toEqual([
@@ -2131,7 +2131,7 @@ describe("buildVomScene", () => {
     });
 
     expect(scene.surfaces).toEqual([
-      { triggerId: 21, triggerAction: "hover", subItems: ["My profile", "Sign out"] },
+      { triggerId: 20, triggerAction: "hover", subItems: ["My profile", "Sign out"] },
     ]);
     expect(renderVom(scene).text).toContain(
       '@e1 button "image" [hover first: My profile | Sign out]',
diff --git a/apps/extension/src/tools/observation.ts b/apps/extension/src/tools/observation.ts
index f25d97b3..ed290d96 100644
--- a/apps/extension/src/tools/observation.ts
+++ b/apps/extension/src/tools/observation.ts
@@ -58,6 +58,8 @@ import {
   type CaptureVomObservationResult,
   projectRecordSafeObservation,
 } from "./vom/record-safe-observation";
+import type { FrameDocument } from "./vom/frame-document";
+import { buildSemanticVomScene, type SemanticAxNode } from "./vom/semantic-graph";
 
 // ---------------------------------------------------------------------------
 // Shared helpers (legacy aliases — observation.ts kept exporting these
@@ -374,316 +376,17 @@ export async function handleScreenshot(
 export type CdpRunner = SharedCdpRunner;
 
 /** Subset of CDP `AXNode` we care about — see `Accessibility.AXNode`. */
-export interface CdpAxNode {
-  nodeId: string;
-  frameId?: string;
-  parentId?: string;
-  backendDOMNodeId?: number;
-  ignored?: boolean;
-  role?: { type: string; value?: string };
-  name?: { type: string; value?: string };
-  description?: { value?: string };
-  value?: { value?: string | number | boolean };
-  properties?: Array<{ name?: string; value?: { value?: string | number | boolean } }>;
-  childIds?: string[];
-}
-
-function axValue(field?: { value?: string | number | boolean }): string | undefined {
-  const value = field?.value;
-  return value === undefined ? undefined : String(value);
-}
-
-function axString(field?: { value?: string | number | boolean }): string | undefined {
-  const value = axValue(field)?.replace(/\s+/g, " ").trim();
-  return value ? value : undefined;
-}
+export type CdpAxNode = SemanticAxNode;
 
 function normalizeTag(tag: string | undefined): string {
   return tag?.toLowerCase() ?? "";
 }
 
-function isModalSignal(
-  axNode: CdpAxNode | undefined,
-  capturedNode: CapturedNode | undefined,
-): boolean {
-  const role = axString(axNode?.role)?.toLowerCase();
-  if (role === "dialog" || role === "alertdialog") return true;
-  if (normalizeTag(capturedNode?.tag) === "dialog") return true;
-
-  const attrs = capturedNode?.attrs ?? {};
-  return (attrs["aria-modal"] ?? "").toLowerCase() === "true" || attrs.role === "dialog";
-}
-
-function isSensitive(capturedNode: CapturedNode | undefined): boolean {
-  const attrs = capturedNode?.attrs ?? {};
-  const type = (attrs.type ?? "").toLowerCase();
-  if (type === "password") return true;
-  const autocomplete = (attrs.autocomplete ?? "").toLowerCase();
-  return (
-    autocomplete.startsWith("cc-") ||
-    autocomplete === "one-time-code" ||
-    autocomplete === "current-password" ||
-    autocomplete === "new-password"
-  );
-}
-
-interface AxNodeSignals {
-  hasPopup: boolean;
-  expanded: boolean;
-  selected: boolean;
-  controls: string;
-  sensitive: boolean;
-  aggregatedText?: string;
-}
-
-const AX_TEXT_AGGREGATE_ROLES = new Set([
-  "paragraph",
-  "listitem",
-  "term",
-  "definition",
-  "cell",
-  "gridcell",
-  "caption",
-  "figcaption",
-  "blockquote",
-  "note",
-  "status",
-  "log",
-  "generic",
-  "section",
-]);
-const AX_TEXT_LEAF_ROLES = new Set(["inlinetextbox", "statictext", "text"]);
-const AX_TEXT_STOP_ROLES = new Set([
-  "button",
-  "link",
-  "combobox",
-  "listbox",
-  "menuitem",
-  "menuitemcheckbox",
-  "menuitemradio",
-  "option",
-  "radio",
-  "checkbox",
-  "textbox",
-  "searchbox",
-  "spinbutton",
-  "slider",
-  "switch",
-  "tab",
-  "treeitem",
-  "columnheader",
-  "rowheader",
-]);
-const SENSITIVE_AX_INPUT_TYPES = new Set([
-  "password",
-  "credit-card",
-  "one-time-code",
-  "current-password",
-  "new-password",
-]);
-
-function axPropertyString(axNode: CdpAxNode, name: string): string | undefined {
-  const prop = axNode.properties?.find((item) => item.name === name);
-  return axString(prop?.value);
-}
-
-function axSiblingLabel(axNode: CdpAxNode, axById: Map<string, CdpAxNode>): string | undefined {
-  const parent = axNode.parentId ? axById.get(axNode.parentId) : undefined;
-  const siblings = parent?.childIds ?? [];
-  const index = siblings.indexOf(axNode.nodeId);
-  if (index <= 0) return undefined;
-
-  for (let i = index - 1; i >= Math.max(0, index - 4); i -= 1) {
-    const sibling = axById.get(siblings[i]);
-    if (!sibling) continue;
-    const role = axString(sibling.role)?.toLowerCase() ?? "";
-    if (AX_TEXT_STOP_ROLES.has(role)) break;
-    if (!["statictext", "labeltext", "text", "generic"].includes(role)) continue;
-    const label = cleanAttr(axString(sibling.name) ?? axString(sibling.value))?.replace(
-      /[：:]\s*$/,
-      "",
-    );
-    if (label && label.length <= 40) return label;
-  }
-  return undefined;
-}
-
-function buildAxSignals(axNodes: CdpAxNode[]): Map<string, AxNodeSignals> {
-  const axByNodeId = new Map(axNodes.map((node) => [node.nodeId, node]));
-  const virtualText = new Map<string, string>();
-  for (const node of axNodes) {
-    if (typeof node.backendDOMNodeId === "number") continue;
-    const role = axString(node.role)?.toLowerCase() ?? "";
-    const name = axString(node.name);
-    if (name && AX_TEXT_LEAF_ROLES.has(role)) virtualText.set(node.nodeId, name);
-  }
-
-  const collectLeafText = (nodeId: string, depth: number): string[] => {
-    if (depth > 8) return [];
-    const node = axByNodeId.get(nodeId);
-    if (!node) return [];
-    const parts: string[] = [];
-    for (const childId of node.childIds ?? []) {
-      const vtext = virtualText.get(childId);
-      if (vtext) {
-        parts.push(vtext);
-        continue;
-      }
-      const child = axByNodeId.get(childId);
-      if (!child) continue;
-      const childRole = axString(child.role)?.toLowerCase() ?? "";
-      if (AX_TEXT_LEAF_ROLES.has(childRole)) continue;
-      if (AX_TEXT_STOP_ROLES.has(childRole)) continue;
-      const childName = axString(child.name);
-      if (childName && !AX_TEXT_AGGREGATE_ROLES.has(childRole)) {
-        parts.push(childName);
-      } else {
-        parts.push(...collectLeafText(childId, depth + 1));
-      }
-    }
-    return parts;
-  };
-
-  const signals = new Map<string, AxNodeSignals>();
-  for (const node of axNodes) {
-    const role = axString(node.role)?.toLowerCase() ?? "";
-    const expanded = axPropertyString(node, "expanded") === "true";
-    const selected = axPropertyString(node, "selected") === "true";
-    const controls = axPropertyString(node, "controls") ?? "";
-    const hasPopupValue = axPropertyString(node, "hasPopup") ?? "";
-    const inputType = axPropertyString(node, "inputType") ?? "";
-    let aggregatedText: string | undefined;
-    if (AX_TEXT_AGGREGATE_ROLES.has(role) && !axString(node.name)) {
-      aggregatedText = cleanAttr(collectLeafText(node.nodeId, 0).join(" "));
-    }
-    signals.set(node.nodeId, {
-      hasPopup: hasPopupValue !== "" && hasPopupValue !== "false",
-      expanded,
-      selected,
-      controls,
-      sensitive: SENSITIVE_AX_INPUT_TYPES.has(inputType),
-      aggregatedText,
-    });
-  }
-  return signals;
-}
-
-function findAxAncestor<T>(
-  axNode: CdpAxNode,
-  axById: Map<string, CdpAxNode>,
-  select: (node: CdpAxNode) => T | undefined,
-): T | undefined {
-  let parentId = axNode.parentId;
-  while (parentId) {
-    const parent = axById.get(parentId);
-    if (!parent) break;
-    const hit = select(parent);
-    if (hit !== undefined) return hit;
-    parentId = parent.parentId;
-  }
-  return undefined;
-}
-
-function nearestBackendParent(axNode: CdpAxNode, axById: Map<string, CdpAxNode>): number | null {
-  return (
-    findAxAncestor(axNode, axById, (parent) =>
-      typeof parent.backendDOMNodeId === "number" ? parent.backendDOMNodeId : undefined,
-    ) ?? null
-  );
-}
-
-const IFRAME_RENDERABLE_TAGS = new Set(["input", "button", "a", "select", "textarea"]);
-
-function iframeRoleFor(node: CapturedNode): string | undefined {
-  const tag = normalizeTag(node.tag);
-  if (tag === "input" || tag === "textarea") return "textbox";
-  if (tag === "button") return "button";
-  if (tag === "a") return "link";
-  if (tag === "select") return "combobox";
-  return undefined;
-}
-
-function iframeNameFor(node: CapturedNode): string | undefined {
-  const tag = normalizeTag(node.tag);
-  const ariaLabel = node.attrs["aria-label"]?.replace(/\s+/g, " ").trim();
-  if (ariaLabel) return ariaLabel;
-
-  const text = node.textContent?.replace(/\s+/g, " ").trim();
-  if (text) return text;
-
-  if (tag === "input" || tag === "textarea") {
-    const placeholder = node.attrs.placeholder?.replace(/\s+/g, " ").trim();
-    if (placeholder) return placeholder;
-  }
-
-  const id = node.attrs.id?.replace(/\s+/g, " ").trim();
-  return id ? id : undefined;
-}
-
-function isRenderableIframeControl(node: CapturedNode): boolean {
-  const tag = normalizeTag(node.tag);
-  if (!IFRAME_RENDERABLE_TAGS.has(tag)) return false;
-  if (!node.localRect && !node.rect) return false;
-  if (node.pointerEvents === "none") return false;
-  if ((node.attrs.type ?? "").toLowerCase() === "hidden") return false;
-
-  const name = iframeNameFor(node);
-  return tag !== "a" || name !== undefined;
-}
-
-function normalizedControlType(node: VomNode | CapturedNode): string {
-  const attrs = node.attrs ?? {};
-  const tag = normalizeTag(node.tag);
-  if (tag === "input") return (attrs.type ?? "text").toLowerCase();
-  if ("sensitive" in node && node.sensitive) return "password";
-  return tag;
-}
-
-function sameLogicalIframeControl(existing: VomNode, candidate: CapturedNode, iframeId: number) {
-  const role = iframeRoleFor(candidate);
-  const name = cleanAttr(iframeNameFor(candidate));
-  if (!role || !name) return false;
-  if ((existing.role ?? "").toLowerCase() !== role) return false;
-  if (cleanAttr(existing.name) !== name) return false;
-
-  const candidateType = normalizedControlType(candidate);
-  const existingType = normalizedControlType(existing);
-  if (candidateType !== existingType) return false;
-
-  return (
-    existing.parentId === iframeId ||
-    existing.domParentId === iframeId ||
-    existing.domAncestorIds?.includes(iframeId) === true
-  );
-}
-
-function hasEquivalentIframeControl(
-  nodes: VomNode[],
-  candidate: CapturedNode,
-  iframeId: number,
-): boolean {
-  return nodes.some((node) => sameLogicalIframeControl(node, candidate, iframeId));
-}
-
-function capturedIframeNameFor(node: CapturedNode): string | undefined {
-  const ariaLabel = node.attrs["aria-label"]?.replace(/\s+/g, " ").trim();
-  if (ariaLabel) return ariaLabel;
-
-  const title = node.attrs.title?.replace(/\s+/g, " ").trim();
-  if (title) return title;
-
-  const id = node.attrs.id?.replace(/\s+/g, " ").trim();
-  return id ? id : undefined;
-}
-
 function cleanAttr(value: string | undefined): string | undefined {
   const trimmed = value?.replace(/\s+/g, " ").trim();
   return trimmed ? trimmed : undefined;
 }
 
-const FORM_CONTROL_TAGS = new Set(["input", "textarea", "select"]);
-
-const NATIVE_CONTROL_TAGS = new Set(["button", "input", "select", "textarea"]);
 const ACTIVE_SCOPE_MAX_BLOCKS = 8;
 const ACTIVE_SCOPE_MAX_LINES = 40;
 const ACTIVE_SCOPE_MAX_LINE_LENGTH = 160;
@@ -701,264 +404,11 @@ function buildCapturedChildren(capturedNodes: CapturedNode[]): Map<number, Captu
   return children;
 }
 
-function capturedDomAncestorIds(
-  node: CapturedNode,
-  capturedByBackendId: Map<number, CapturedNode>,
-): number[] {
-  const ancestors: number[] = [];
-  let parentId = node.parentBackendNodeId;
-  let guard = 0;
-  while (parentId !== null && guard < capturedByBackendId.size) {
-    ancestors.push(parentId);
-    parentId = capturedByBackendId.get(parentId)?.parentBackendNodeId ?? null;
-    guard += 1;
-  }
-  return ancestors;
-}
-
-function capturedHasNativeDescendant(
-  node: CapturedNode,
-  childrenByParentId: Map<number, CapturedNode[]>,
-): boolean {
-  const stack = [...(childrenByParentId.get(node.backendNodeId) ?? [])];
-  while (stack.length > 0) {
-    const child = stack.pop() as CapturedNode;
-    if (NATIVE_CONTROL_TAGS.has(normalizeTag(child.tag))) return true;
-    stack.push(...(childrenByParentId.get(child.backendNodeId) ?? []));
-  }
-  return false;
-}
-
-function capturedInsideNative(
-  node: CapturedNode,
-  capturedByBackendId: Map<number, CapturedNode>,
-): boolean {
-  let parentId = node.parentBackendNodeId;
-  let guard = 0;
-  while (parentId !== null && guard < capturedByBackendId.size) {
-    const parent = capturedByBackendId.get(parentId);
-    if (!parent) break;
-    if (NATIVE_CONTROL_TAGS.has(normalizeTag(parent.tag))) return true;
-    parentId = parent.parentBackendNodeId;
-    guard += 1;
-  }
-  return false;
-}
-
-function nearbyTextFor(
-  node: CapturedNode,
-  childrenByParentId: Map<number, CapturedNode[]>,
-): string | undefined {
-  if (node.parentBackendNodeId === null) return undefined;
-  const siblings = childrenByParentId.get(node.parentBackendNodeId) ?? [];
-  const index = siblings.findIndex((sibling) => sibling.backendNodeId === node.backendNodeId);
-  if (index < 0) return undefined;
-
-  const labels: string[] = [];
-  for (const sibling of siblings.slice(Math.max(0, index - 3), index)) {
-    const text = cleanAttr(sibling.textContent);
-    if (text) labels.push(text);
-  }
-  for (const sibling of siblings.slice(index + 1, index + 4)) {
-    const text = cleanAttr(sibling.textContent);
-    if (text) labels.push(text);
-  }
-  return labels.length > 0 ? labels.join(" ") : undefined;
-}
-
-function previousSiblingTextFor(
-  node: CapturedNode,
-  childrenByParentId: Map<number, CapturedNode[]>,
-): string | undefined {
-  if (node.parentBackendNodeId === null) return undefined;
-  const siblings = childrenByParentId.get(node.parentBackendNodeId) ?? [];
-  const index = siblings.findIndex((sibling) => sibling.backendNodeId === node.backendNodeId);
-  if (index <= 0) return undefined;
-
-  for (let i = index - 1; i >= Math.max(0, index - 4); i -= 1) {
-    const sibling = siblings[i];
-    if (["input", "textarea", "select", "button", "a"].includes(normalizeTag(sibling.tag))) break;
-    const text = cleanAttr(sibling.textContent)?.replace(/[：:]\s*$/, "");
-    if (text && text.length <= 40) return text;
-  }
-  return undefined;
-}
-
 interface VomNodeDomSignals {
   capturedByBackendId: Map<number, CapturedNode>;
   childrenByParentId: Map<number, CapturedNode[]>;
 }
 
-function applyCapturedSignals(
-  node: VomNode,
-  capturedNode: CapturedNode | undefined,
-  signals: VomNodeDomSignals,
-): VomNode {
-  if (!capturedNode) return node;
-  const attrs =
-    node.sensitive && Object.prototype.hasOwnProperty.call(capturedNode.attrs, "value")
-      ? Object.fromEntries(
-          Object.entries(capturedNode.attrs).filter(([name]) => name.toLowerCase() !== "value"),
-        )
-      : capturedNode.attrs;
-  const text = cleanAttr(capturedNode.textContent);
-  const nearbyText = nearbyTextFor(capturedNode, signals.childrenByParentId);
-  const placeholder = cleanAttr(capturedNode.formPlaceholder) ?? cleanAttr(attrs.placeholder);
-  return {
-    ...node,
-    domParentId: capturedNode.parentBackendNodeId,
-    domAncestorIds: capturedDomAncestorIds(capturedNode, signals.capturedByBackendId),
-    cursor: capturedNode.cursor,
-    attrs,
-    ...(text ? { text } : {}),
-    ...(nearbyText ? { nearbyText } : {}),
-    ...(placeholder ? { placeholder } : {}),
-    disabled:
-      Object.prototype.hasOwnProperty.call(attrs, "disabled") ||
-      (attrs["aria-disabled"] ?? "").toLowerCase() === "true",
-    inert: Object.prototype.hasOwnProperty.call(attrs, "inert"),
-    hasNativeDescendant: capturedHasNativeDescendant(capturedNode, signals.childrenByParentId),
-    insideNative: capturedInsideNative(capturedNode, signals.capturedByBackendId),
-  };
-}
-
-function inputStateFor(
-  capturedNode: CapturedNode | undefined,
-  value: string | undefined,
-): VomNode["inputState"] {
-  if (!capturedNode || !FORM_CONTROL_TAGS.has(normalizeTag(capturedNode.tag))) return undefined;
-  if (capturedNode.formState) return capturedNode.formState;
-  const formValue = capturedNode.formValue;
-  if (formValue !== undefined) {
-    if (formValue === "") return "empty";
-    if (formValue === (capturedNode.formDefaultValue ?? "")) return "default";
-    return "filled";
-  }
-  return value === undefined || value === "" ? "empty" : "filled";
-}
-
-/**
- * Name for a native form control. VOM models the *perceived* viewport
- * (spec §1): an empty field displays its placeholder, so when the field has
- * no value we prefer the placeholder over an accessible name that pages
- * frequently pollute by wrapping the `<input>` in a `<label>` that also
- * holds prefixes/buttons (e.g. xiaohongshu's "+86" / "获取验证码"). Filled
- * fields keep the accessible name and surface their value separately.
- */
-function formControlName(
-  captured: CapturedNode | undefined,
-  axName: string | undefined,
-  axSiblingName: string | undefined,
-  signals: VomNodeDomSignals,
-): string | undefined {
-  const ariaLabel = cleanAttr(captured?.attrs["aria-label"]);
-  const title = cleanAttr(captured?.attrs.title);
-  const placeholder =
-    cleanAttr(captured?.formPlaceholder) ?? cleanAttr(captured?.attrs.placeholder);
-  const nearbyLabel = captured
-    ? previousSiblingTextFor(captured, signals.childrenByParentId)
-    : undefined;
-  return ariaLabel ?? title ?? axName ?? axSiblingName ?? nearbyLabel ?? placeholder;
-}
-
-function vomNodeFromCaptured(
-  capturedNode: CapturedNode,
-  parentId: number | null,
-  signals: VomNodeDomSignals,
-): VomNode {
-  const sensitive = isSensitive(capturedNode);
-  const value = sensitive ? undefined : capturedNode.formValue;
-  const tag = normalizeTag(capturedNode.tag);
-  const node = applyCapturedSignals(
-    {
-      id: capturedNode.backendNodeId,
-      parentId,
-      tag,
-      rect: capturedNode.rect,
-      paintOrder: capturedNode.paintOrder,
-      position: capturedNode.position || "static",
-      pointerEvents: capturedNode.pointerEvents || "auto",
-      modal: isModalSignal(undefined, capturedNode),
-      sensitive,
-      inputState: inputStateFor(capturedNode, value),
-      ...(value !== undefined ? { value } : {}),
-    },
-    capturedNode,
-    signals,
-  );
-  if (tag === "iframe") {
-    node.role = "Iframe";
-    const name = capturedIframeNameFor(capturedNode);
-    if (name) node.name = name;
-  }
-  return node;
-}
-
-function axVomNode(
-  axNode: CdpAxNode,
-  capturedNode: CapturedNode | undefined,
-  axById: Map<string, CdpAxNode>,
-  signals: VomNodeDomSignals,
-  axSignals: Map<string, AxNodeSignals>,
-): VomNode {
-  const role = axString(axNode.role);
-  const capturedValue = capturedNode?.formValue;
-  const sourceValue = capturedValue ?? axValue(axNode.value);
-  const signalsForNode = axSignals.get(axNode.nodeId);
-  const sensitive = isSensitive(capturedNode) || signalsForNode?.sensitive === true;
-  const value = sensitive ? undefined : sourceValue;
-  const inputState =
-    inputStateFor(capturedNode, sourceValue) ??
-    (sensitive && ["textbox", "searchbox"].includes(role?.toLowerCase() ?? "")
-      ? sourceValue === undefined || sourceValue === ""
-        ? "empty"
-        : "filled"
-      : undefined);
-  let name = FORM_CONTROL_TAGS.has(normalizeTag(capturedNode?.tag))
-    ? formControlName(capturedNode, axString(axNode.name), axSiblingLabel(axNode, axById), signals)
-    : (axString(axNode.name) ?? signalsForNode?.aggregatedText);
-  if (name && signalsForNode?.hasPopup) {
-    name = signalsForNode.expanded ? `${name} [expanded]` : `${name} [has-submenu]`;
-  }
-  const node: VomNode = {
-    id: axNode.backendDOMNodeId as number,
-    parentId: nearestBackendParent(axNode, axById),
-    tag: normalizeTag(capturedNode?.tag),
-    rect: capturedNode?.rect ?? null,
-    paintOrder: capturedNode?.paintOrder ?? 0,
-    position: capturedNode?.position || "static",
-    pointerEvents: capturedNode?.pointerEvents || "auto",
-    modal: isModalSignal(axNode, capturedNode),
-    sensitive,
-    inputState,
-  };
-  if (role) node.role = role;
-  if (name) node.name = name;
-  if (value !== undefined) node.value = value;
-  const enriched = applyCapturedSignals(node, capturedNode, signals);
-  if (signalsForNode?.selected && !enriched.attrs?.["aria-selected"]) {
-    enriched.attrs = { ...(enriched.attrs ?? {}), "aria-selected": "true" };
-  }
-  if (signalsForNode?.expanded && !enriched.attrs?.["aria-expanded"]) {
-    enriched.attrs = { ...(enriched.attrs ?? {}), "aria-expanded": "true" };
-  }
-  if (signalsForNode?.controls && !enriched.attrs?.["aria-controls"]) {
-    enriched.attrs = { ...(enriched.attrs ?? {}), "aria-controls": signalsForNode.controls };
-  }
-  return enriched;
-}
-
-function iframeSignals(iframeNodes: CapturedNode[]): VomNodeDomSignals {
-  const capturedByBackendId = new Map<number, CapturedNode>();
-  for (const node of iframeNodes) {
-    capturedByBackendId.set(node.backendNodeId, node);
-  }
-  return {
-    capturedByBackendId,
-    childrenByParentId: buildCapturedChildren(iframeNodes),
-  };
-}
-
 function capturedOnlySignals(capturedNodes: CapturedNode[]): VomNodeDomSignals {
   const capturedByBackendId = new Map<number, CapturedNode>();
   for (const node of capturedNodes) {
@@ -1104,28 +554,45 @@ function findSurfaceTriggerNode(
   triggerPoint?: { x: number; y: number },
 ): VomNode | undefined {
   const renderedById = new Map(nodes.map((node) => [node.id, node]));
-  const exact = renderedById.get(triggerBackendNodeId);
+  const renderedByBackendId = new Map(
+    nodes.flatMap((node) =>
+      node.backendNodeId === undefined ? [] : ([[node.backendNodeId, node]] as const),
+    ),
+  );
+  const exact =
+    renderedByBackendId.get(triggerBackendNodeId) ?? renderedById.get(triggerBackendNodeId);
   if (exact && isSurfaceAttachableNode(exact)) return exact;
 
+  const isCapturedDescendant = (backendNodeId: number): boolean => {
+    let current = signals.capturedByBackendId.get(backendNodeId);
+    const seen = new Set<number>();
+    while (current?.parentBackendNodeId !== null && current?.parentBackendNodeId !== undefined) {
+      if (current.parentBackendNodeId === triggerBackendNodeId) return true;
+      if (seen.has(current.parentBackendNodeId)) break;
+      seen.add(current.parentBackendNodeId);
+      current = signals.capturedByBackendId.get(current.parentBackendNodeId);
+    }
+    return false;
+  };
   const domDescendant = nodes.find(
     (node) =>
       isSurfaceAttachableNode(node) &&
-      (node.domParentId === triggerBackendNodeId ||
-        node.domAncestorIds?.includes(triggerBackendNodeId) === true),
+      node.backendNodeId !== undefined &&
+      isCapturedDescendant(node.backendNodeId),
   );
   if (domDescendant) return domDescendant;
 
   const queue = [...(signals.childrenByParentId.get(triggerBackendNodeId) ?? [])];
   while (queue.length > 0) {
     const child = queue.shift() as CapturedNode;
-    const rendered = renderedById.get(child.backendNodeId);
+    const rendered = renderedByBackendId.get(child.backendNodeId);
     if (rendered && isSurfaceAttachableNode(rendered)) return rendered;
     queue.push(...(signals.childrenByParentId.get(child.backendNodeId) ?? []));
   }
 
   let current = signals.capturedByBackendId.get(triggerBackendNodeId);
   while (current?.parentBackendNodeId !== null && current?.parentBackendNodeId !== undefined) {
-    const parent = renderedById.get(current.parentBackendNodeId);
+    const parent = renderedByBackendId.get(current.parentBackendNodeId);
     if (parent && isSurfaceAttachableNode(parent)) return parent;
     current = signals.capturedByBackendId.get(current.parentBackendNodeId);
   }
@@ -1149,7 +616,11 @@ function findSurfaceNodeByPoint(
   let best: { node: VomNode; score: number } | undefined;
   for (const node of nodes) {
     if (!isSurfaceAttachableNode(node)) continue;
-    const rect = node.rect ?? signals.capturedByBackendId.get(node.id)?.rect;
+    const rect =
+      node.rect ??
+      (node.backendNodeId === undefined
+        ? undefined
+        : signals.capturedByBackendId.get(node.backendNodeId)?.rect);
     if (!rect) continue;
     const contains =
       point.x >= rect.x &&
@@ -1168,234 +639,181 @@ function findSurfaceNodeByPoint(
   return best?.node;
 }
 
-function axNodeInOverlaySubtree(
-  axNode: CdpAxNode,
-  axById: Map<string, CdpAxNode>,
-  excludedBackendNodeIds: Set<number>,
-): boolean {
-  if (
-    typeof axNode.backendDOMNodeId === "number" &&
-    excludedBackendNodeIds.has(axNode.backendDOMNodeId)
-  ) {
-    return true;
-  }
-  return (
-    findAxAncestor(axNode, axById, (parent) => {
-      const parentBackendId = parent.backendDOMNodeId;
-      return typeof parentBackendId === "number" && excludedBackendNodeIds.has(parentBackendId)
-        ? true
-        : undefined;
-    }) === true
-  );
-}
-
 export interface BuildVomSceneOptions {
   pageUrl?: string;
 }
 
 export type VomFrameDocument = CapturedFrameDocument<CdpAxNode>;
 
-function externalHrefHost(
-  href: string | undefined,
-  pageUrl: string | undefined,
-): string | undefined {
-  if (!href || !pageUrl) return undefined;
-  try {
-    const page = new URL(pageUrl);
-    const target = new URL(href, page);
-    return target.origin !== page.origin ? target.hostname : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-export function buildVomScene(
+function legacyFrameDocuments(
   axNodes: CdpAxNode[],
   captured: CapturedViewModel,
-  options: BuildVomSceneOptions = {},
-): VomScene {
-  const signals = capturedOnlySignals(captured.nodes);
-  const { capturedByBackendId } = signals;
-  const axSignals = buildAxSignals(axNodes);
-
-  const axById = new Map<string, CdpAxNode>();
-  for (const node of axNodes) {
-    axById.set(node.nodeId, node);
-  }
-
-  const excludedBackendNodeIds = captured.excludedBackendNodeIds;
-  const seenBackendIds = new Set<number>();
-  const nodes: VomNode[] = [];
-
-  for (const axNode of axNodes) {
-    if (axNode.ignored || typeof axNode.backendDOMNodeId !== "number") continue;
-    if (axNodeInOverlaySubtree(axNode, axById, excludedBackendNodeIds)) continue;
-
-    const capturedNode = capturedByBackendId.get(axNode.backendDOMNodeId);
-    const role = axString(axNode.role);
-    const vomNode = axVomNode(axNode, capturedNode, axById, signals, axSignals);
-
-    // For link nodes, attach external hostname so the renderer can annotate it.
-    // Relative hrefs and same-origin hrefs are omitted to avoid noise.
-    if (role?.toLowerCase() === "link") {
-      const hrefHost = externalHrefHost(capturedNode?.attrs.href, options.pageUrl);
-      if (hrefHost) vomNode.href = hrefHost;
+  pageUrl?: string,
+  rootTarget: VomFrameDocument["target"] = { tabId: 0 },
+): VomFrameDocument[] {
+  const rootFrameId = captured.rootFrameId ?? "root";
+  const documents: VomFrameDocument[] = [
+    {
+      frameId: rootFrameId,
+      contextScopeId: rootFrameId,
+      target: rootTarget,
+      ...(pageUrl ? { url: pageUrl } : {}),
+      axNodes: [],
+      domNodes: captured.nodes.map((node) => ({ ...node, frameId: node.frameId ?? rootFrameId })),
+    },
+  ];
+  const pending = [...captured.iframeNodes.entries()];
+  let progress = true;
+  let nextSyntheticFrame = 1;
+  while (pending.length > 0 && progress) {
+    progress = false;
+    for (let index = pending.length - 1; index >= 0; index -= 1) {
+      const [ownerBackendNodeId, domNodes] = pending[index];
+      const parent = documents.find((document) =>
+        document.domNodes.some((node) => node.backendNodeId === ownerBackendNodeId),
+      );
+      if (!parent) continue;
+      const frameId =
+        domNodes.find((node) => node.frameId)?.frameId ?? `legacy-frame-${nextSyntheticFrame++}`;
+      documents.push({
+        frameId,
+        parentFrameId: parent.frameId,
+        ownerBackendNodeId,
+        contextScopeId: frameId,
+        target: parent.target,
+        axNodes: [],
+        domNodes: domNodes.map((node) => ({ ...node, frameId: node.frameId ?? frameId })),
+      });
+      pending.splice(index, 1);
+      progress = true;
     }
-
-    seenBackendIds.add(axNode.backendDOMNodeId);
-    nodes.push(vomNode);
   }
 
-  for (const capturedNode of captured.nodes) {
-    if (seenBackendIds.has(capturedNode.backendNodeId)) continue;
-    if (excludedBackendNodeIds.has(capturedNode.backendNodeId)) continue;
-    seenBackendIds.add(capturedNode.backendNodeId);
-    nodes.push(vomNodeFromCaptured(capturedNode, capturedNode.parentBackendNodeId, signals));
+  const documentByFrameId = new Map(documents.map((document) => [document.frameId, document]));
+  const backendFrame = new Map<number, string>();
+  const childFrameByOwner = new Map<number, string>();
+  for (const document of documents) {
+    if (document.ownerBackendNodeId !== undefined) {
+      childFrameByOwner.set(document.ownerBackendNodeId, document.frameId);
+    }
+    for (const node of document.domNodes) backendFrame.set(node.backendNodeId, document.frameId);
   }
-
-  for (const [iframeBackendId, iframeNodes] of captured.iframeNodes) {
-    const signals = iframeSignals(iframeNodes);
-    for (const iframeNode of iframeNodes) {
-      if (
-        seenBackendIds.has(iframeNode.backendNodeId) ||
-        excludedBackendNodeIds.has(iframeNode.backendNodeId) ||
-        !isRenderableIframeControl(iframeNode) ||
-        hasEquivalentIframeControl(nodes, iframeNode, iframeBackendId)
-      ) {
-        continue;
+  const axById = new Map(axNodes.map((node) => [node.nodeId, node]));
+  const ownership = new Map<string, string>();
+  const resolving = new Set<string>();
+  const frameForAx = (node: CdpAxNode): string => {
+    const cached = ownership.get(node.nodeId);
+    if (cached) return cached;
+    let frameId: string | undefined;
+    if (node.frameId && documentByFrameId.has(node.frameId)) frameId = node.frameId;
+    if (!frameId && typeof node.backendDOMNodeId === "number") {
+      frameId = backendFrame.get(node.backendDOMNodeId);
+    }
+    if (!frameId && node.parentId && !resolving.has(node.nodeId)) {
+      const parent = axById.get(node.parentId);
+      if (parent) {
+        frameId =
+          typeof parent.backendDOMNodeId === "number"
+            ? childFrameByOwner.get(parent.backendDOMNodeId)
+            : undefined;
+        if (!frameId) {
+          resolving.add(node.nodeId);
+          frameId = frameForAx(parent);
+          resolving.delete(node.nodeId);
+        }
       }
-      const role = iframeRoleFor(iframeNode);
-      const name = iframeNameFor(iframeNode);
-      if (!role || (!name && normalizeTag(iframeNode.tag) === "a")) continue;
-
-      seenBackendIds.add(iframeNode.backendNodeId);
-      const vomNode: VomNode = {
-        ...vomNodeFromCaptured(iframeNode, iframeBackendId, signals),
-        role,
-      };
-      if (name) vomNode.name = name;
-      nodes.push(vomNode);
     }
+    frameId ??= rootFrameId;
+    ownership.set(node.nodeId, frameId);
+    return frameId;
+  };
+  for (const node of axNodes) frameForAx(node);
+  for (const node of axNodes) {
+    const frameId = ownership.get(node.nodeId) ?? rootFrameId;
+    const document = documentByFrameId.get(frameId) ?? documents[0];
+    document.axNodes.push({
+      ...node,
+      frameId,
+      ...(node.parentId && ownership.get(node.parentId) === frameId
+        ? { parentId: node.parentId }
+        : { parentId: undefined }),
+      ...(node.childIds
+        ? { childIds: node.childIds.filter((childId) => ownership.get(childId) === frameId) }
+        : {}),
+    });
   }
+  return documents;
+}
 
-  const activeScopeBlocks = buildActiveScopeBlocks(nodes, signals);
-  const surfaces = buildConditionalSurfaces(nodes, captured);
+function withLegacyBackendIds(scene: VomScene): VomScene {
+  const used = new Set<number>();
+  const idMap = new Map<number, number>();
+  let nextVirtualId = -1;
+  for (const node of scene.nodes) {
+    const preferred = node.backendNodeId;
+    const id = preferred !== undefined && !used.has(preferred) ? preferred : nextVirtualId--;
+    used.add(id);
+    idMap.set(node.id, id);
+  }
   return {
-    viewport: captured.viewport,
-    nodes,
-    ...(surfaces.length > 0 ? { surfaces } : {}),
-    ...(activeScopeBlocks.length > 0 ? { activeScopeBlocks } : {}),
+    ...scene,
+    nodes: scene.nodes.map((node) => ({
+      ...node,
+      id: idMap.get(node.id) as number,
+      parentId: node.parentId === null ? null : (idMap.get(node.parentId) ?? null),
+      ...(node.domParentId !== undefined
+        ? { domParentId: node.domParentId === null ? null : (idMap.get(node.domParentId) ?? null) }
+        : {}),
+      ...(node.domAncestorIds
+        ? { domAncestorIds: node.domAncestorIds.flatMap((id) => idMap.get(id) ?? []) }
+        : {}),
+    })),
+    ...(scene.surfaces
+      ? {
+          surfaces: scene.surfaces.map((surface) => ({
+            ...surface,
+            triggerId: idMap.get(surface.triggerId) ?? surface.triggerId,
+          })),
+        }
+      : {}),
+    ...(scene.activeScopeBlocks
+      ? {
+          activeScopeBlocks: scene.activeScopeBlocks.map((block) => ({
+            ...block,
+            triggerId: idMap.get(block.triggerId) ?? block.triggerId,
+          })),
+        }
+      : {}),
   };
 }
 
-export function buildFrameVomScene(
-  documents: VomFrameDocument[],
+export function buildVomScene(
+  axNodes: CdpAxNode[],
   captured: CapturedViewModel,
   options: BuildVomSceneOptions = {},
 ): VomScene {
-  const documentByFrameId = new Map(documents.map((document) => [document.frameId, document]));
-  const rootFrameId =
-    captured.rootFrameId ?? documents.find((document) => !document.parentFrameId)?.frameId;
-  const orderedFrameIds = [
-    ...(rootFrameId ? [rootFrameId] : []),
-    ...documents.map((document) => document.frameId),
-  ].filter((frameId, index, all) => all.indexOf(frameId) === index);
-
-  const localScenes = new Map<string, VomScene>();
-  for (const frameId of orderedFrameIds) {
-    const document = documentByFrameId.get(frameId);
-    if (!document) continue;
-    localScenes.set(
-      frameId,
-      buildVomScene(
-        document.axNodes,
-        {
-          viewport: captured.viewport,
-          nodes: document.domNodes,
-          iframeNodes: new Map(),
-          surfaceProbes: frameId === rootFrameId ? captured.surfaceProbes : [],
-          excludedBackendNodeIds:
-            frameId === rootFrameId ? captured.excludedBackendNodeIds : new Set(),
-        },
-        { pageUrl: document.url ?? options.pageUrl },
-      ),
-    );
-  }
-
-  const sceneIdByFrameAndBackend = new Map<string, number>();
-  let nextSceneId = 1;
-  for (const [frameId, scene] of localScenes) {
-    for (const node of scene.nodes) {
-      sceneIdByFrameAndBackend.set(`${frameId}:${node.id}`, nextSceneId);
-      nextSceneId += 1;
-    }
-  }
-
-  const nodes: VomNode[] = [];
-  const surfaces: CondSurface[] = [];
-  const activeScopeBlocks: ActiveScopeBlock[] = [];
-
-  for (const [frameId, scene] of localScenes) {
-    const document = documentByFrameId.get(frameId);
-    const ownerBackendNodeId = document?.ownerBackendNodeId;
-    const parentFrameId = document?.parentFrameId;
-    const ownerSceneId =
-      ownerBackendNodeId !== undefined && parentFrameId
-        ? sceneIdByFrameAndBackend.get(`${parentFrameId}:${ownerBackendNodeId}`)
-        : undefined;
-    if (frameId !== rootFrameId && ownerSceneId === undefined) continue;
-
-    const suppressedRoots = new Set(
-      frameId === rootFrameId
-        ? []
-        : scene.nodes
-            .filter(
-              (node) =>
-                node.parentId === null &&
-                ["rootwebarea", "webarea"].includes(node.role?.toLowerCase() ?? ""),
-            )
-            .map((node) => node.id),
-    );
-
-    for (const node of scene.nodes) {
-      if (suppressedRoots.has(node.id)) continue;
-      const sceneNodeId = sceneIdByFrameAndBackend.get(`${frameId}:${node.id}`) as number;
-      let parentId =
-        node.parentId !== null
-          ? sceneIdByFrameAndBackend.get(`${frameId}:${node.parentId}`)
-          : ownerSceneId;
-      if (node.parentId !== null && suppressedRoots.has(node.parentId)) parentId = ownerSceneId;
-      const remapId = (id: number) => sceneIdByFrameAndBackend.get(`${frameId}:${id}`);
-      nodes.push({
-        ...node,
-        id: sceneNodeId,
-        backendNodeId: node.id,
-        frameId,
-        contextScopeId: document?.contextScopeId ?? frameId,
-        parentId: parentId ?? null,
-        ...(node.domParentId !== undefined
-          ? { domParentId: node.domParentId === null ? null : (remapId(node.domParentId) ?? null) }
-          : {}),
-        ...(node.domAncestorIds
-          ? { domAncestorIds: node.domAncestorIds.flatMap((id) => remapId(id) ?? []) }
-          : {}),
-      });
-    }
-
-    for (const surface of scene.surfaces ?? []) {
-      const triggerId = sceneIdByFrameAndBackend.get(`${frameId}:${surface.triggerId}`);
-      if (triggerId !== undefined) surfaces.push({ ...surface, triggerId });
-    }
-    for (const block of scene.activeScopeBlocks ?? []) {
-      const triggerId = sceneIdByFrameAndBackend.get(`${frameId}:${block.triggerId}`);
-      if (triggerId !== undefined) activeScopeBlocks.push({ ...block, triggerId });
-    }
-  }
+  return withLegacyBackendIds(
+    buildFrameVomScene(legacyFrameDocuments(axNodes, captured, options.pageUrl), captured, options),
+  );
+}
 
-  return {
+export function buildFrameVomScene(
+  documents: VomFrameDocument[],
+  captured: CapturedViewModel,
+  _options: BuildVomSceneOptions = {},
+): VomScene {
+  const scene = buildSemanticVomScene({
+    documents: documents as FrameDocument<SemanticAxNode>[],
     viewport: captured.viewport,
-    nodes,
-    ...(rootFrameId ? { rootFrameId } : {}),
+    rootFrameId: captured.rootFrameId,
+    excludedBackendNodeIds: captured.excludedBackendNodeIds,
+  });
+  const rootDocument = documents.find((document) => document.frameId === scene.rootFrameId);
+  const signals = capturedOnlySignals(rootDocument?.domNodes ?? captured.nodes);
+  const activeScopeBlocks = buildActiveScopeBlocks(scene.nodes, signals);
+  const surfaces = buildConditionalSurfaces(scene.nodes, captured);
+  return {
+    ...scene,
     ...(surfaces.length > 0 ? { surfaces } : {}),
     ...(activeScopeBlocks.length > 0 ? { activeScopeBlocks } : {}),
   };
@@ -1605,10 +1023,11 @@ export async function captureVomObservation(
   throwIfAborted(options.signal, "observation");
   const documents = await captureFrameData<CdpAxNode>(cdp, tabId, captured, options.signal);
   throwIfAborted(options.signal, "observation");
-  const scene =
-    captured.rootFrameId && captured.frameNodes?.size
-      ? buildFrameVomScene(documents, captured, { pageUrl: url })
-      : buildVomScene(documents[0]?.axNodes ?? [], captured, { pageUrl: url });
+  const normalizedDocuments =
+    documents.length === 1 && captured.iframeNodes.size > 0
+      ? legacyFrameDocuments(documents[0].axNodes, captured, url, documents[0].target)
+      : documents;
+  const scene = buildFrameVomScene(normalizedDocuments, captured, { pageUrl: url });
   const rendered = renderVom(scene, {
     maxDepth: options.maxDepth,
     maxTokens: options.maxTokens,
@@ -1617,8 +1036,8 @@ export async function captureVomObservation(
   });
   throwIfAborted(options.signal, "observation");
   return projectRecordSafeObservation({
-    rootFrameId: captured.rootFrameId ?? documents[0]?.frameId ?? "root",
-    frameDocuments: documents,
+    rootFrameId: captured.rootFrameId ?? normalizedDocuments[0]?.frameId ?? "root",
+    frameDocuments: normalizedDocuments,
     rendered,
     surfaceProbes: captured.surfaceProbes,
   });
diff --git a/apps/extension/src/tools/vom/__tests__/frame-capture.test.ts b/apps/extension/src/tools/vom/__tests__/frame-capture.test.ts
index c7f66354..6bbd2240 100644
--- a/apps/extension/src/tools/vom/__tests__/frame-capture.test.ts
+++ b/apps/extension/src/tools/vom/__tests__/frame-capture.test.ts
@@ -132,4 +132,67 @@ describe("captureFrameData", () => {
       ]),
     );
   });
+
+  it("keeps OOPIF semantics when viewport projection is unavailable", async () => {
+    const owner = { ...ownerNode(10, 50), rect: null, localRect: null };
+    const captured: CapturedViewModel = {
+      nodes: [owner],
+      viewport: { width: 1000, height: 800 },
+      iframeNodes: new Map(),
+      frameNodes: new Map([["main", [owner]]]),
+      rootFrameId: "main",
+      excludedBackendNodeIds: new Set(),
+    };
+    const cdp: CdpRunner = {
+      send: vi.fn(async (_tabId, method) => {
+        if (method === "Accessibility.enable") return {};
+        if (method === "Accessibility.getFullAXTree") return { nodes: [] };
+        if (method === "DOM.getBoxModel") throw new Error("owner geometry unavailable");
+        if (method === "Page.getLayoutMetrics") {
+          return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 } };
+        }
+        throw new Error(`unexpected root ${method}`);
+      }) as CdpRunner["send"],
+      sendToTarget: vi.fn(async (_target, method) => {
+        if (method === "Page.getLayoutMetrics") throw new Error("viewport unavailable");
+        if (method === "DOMSnapshot.enable" || method === "Accessibility.enable") return {};
+        if (method === "DOMSnapshot.captureSnapshot") return childSnapshot("child", 101);
+        if (method === "Accessibility.getFullAXTree") {
+          return {
+            nodes: [
+              {
+                nodeId: "button",
+                backendDOMNodeId: 101,
+                role: { type: "role", value: "button" },
+                name: { type: "computedString", value: "Continue" },
+              },
+            ],
+          };
+        }
+        throw new Error(`unexpected ${method}`);
+      }) as unknown as NonNullable<CdpRunner["sendToTarget"]>,
+      getFrameGraph: vi.fn(async () => ({
+        rootFrameId: "main",
+        frames: [
+          { frameId: "main", target: { tabId: 4 } },
+          {
+            frameId: "child",
+            parentFrameId: "main",
+            ownerBackendNodeId: 10,
+            target: { tabId: 4, sessionId: "child-session" },
+          },
+        ],
+      })),
+    };
+
+    const documents = await captureFrameData(cdp, 4, captured);
+    const childDocument = documents.find((document) => document.frameId === "child");
+
+    expect(childDocument?.axNodes).toEqual([
+      expect.objectContaining({ backendDOMNodeId: 101, frameId: "child" }),
+    ]);
+    expect(childDocument?.domNodes.find((node) => node.backendNodeId === 101)).toEqual(
+      expect.objectContaining({ rect: null, localRect: { x: 10, y: 20, w: 100, h: 40 } }),
+    );
+  });
 });
diff --git a/apps/extension/src/tools/vom/__tests__/semantic-graph.test.ts b/apps/extension/src/tools/vom/__tests__/semantic-graph.test.ts
new file mode 100644
index 00000000..eb9d6560
--- /dev/null
+++ b/apps/extension/src/tools/vom/__tests__/semantic-graph.test.ts
@@ -0,0 +1,215 @@
+import { isVomReferenceNode, renderVom } from "@browser-skill/vom";
+import { describe, expect, it } from "vitest";
+import type { CapturedNode } from "../capture";
+import type { FrameDocument } from "../frame-document";
+import { buildSemanticVomScene, type SemanticAxNode } from "../semantic-graph";
+
+function dom(
+  backendNodeId: number,
+  parentBackendNodeId: number | null,
+  tag: string,
+  attrs: Record<string, string> = {},
+  textContent?: string,
+): CapturedNode {
+  return {
+    backendNodeId,
+    parentBackendNodeId,
+    tag,
+    attrs,
+    rect: { x: 0, y: 0, w: 100, h: 30 },
+    paintOrder: backendNodeId,
+    position: "static",
+    pointerEvents: "auto",
+    ...(textContent ? { textContent } : {}),
+  };
+}
+
+function document(
+  frameId: string,
+  axNodes: SemanticAxNode[],
+  domNodes: CapturedNode[],
+  frame?: Pick<FrameDocument<SemanticAxNode>, "parentFrameId" | "ownerBackendNodeId">,
+): FrameDocument<SemanticAxNode> {
+  return {
+    frameId,
+    contextScopeId: frameId,
+    target: { tabId: 1 },
+    axNodes,
+    domNodes,
+    ...frame,
+  };
+}
+
+describe("semantic VOM graph", () => {
+  it("preserves backend-less AX structure without making it referenceable", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["toolbar"],
+            },
+            {
+              nodeId: "toolbar",
+              parentId: "root",
+              role: { type: "role", value: "toolbar" },
+              name: { type: "computedString", value: "Formatting" },
+              childIds: ["bold", "italic"],
+            },
+            {
+              nodeId: "bold",
+              parentId: "toolbar",
+              backendDOMNodeId: 2,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Bold" },
+            },
+            {
+              nodeId: "italic",
+              parentId: "toolbar",
+              backendDOMNodeId: 3,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Italic" },
+            },
+          ],
+          [dom(1, null, "body"), dom(2, 1, "button"), dom(3, 1, "button")],
+        ),
+      ],
+    });
+
+    const toolbar = scene.nodes.find((node) => node.role === "toolbar");
+    const buttons = scene.nodes.filter((node) => node.role === "button");
+    expect(toolbar).toEqual(expect.objectContaining({ name: "Formatting", referenceable: false }));
+    expect(buttons.map((node) => node.parentId)).toEqual([toolbar?.id, toolbar?.id]);
+    expect(toolbar && isVomReferenceNode(toolbar)).toBe(false);
+    expect(renderVom(scene).refs.map((ref) => ref.backendNodeId)).toEqual([2, 3]);
+  });
+
+  it("resolves missing AX names through one DOM naming pipeline", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["labelled", "titled", "text"],
+            },
+            {
+              nodeId: "labelled",
+              parentId: "root",
+              backendDOMNodeId: 2,
+              role: { type: "role", value: "button" },
+            },
+            {
+              nodeId: "titled",
+              parentId: "root",
+              backendDOMNodeId: 3,
+              role: { type: "role", value: "button" },
+            },
+            {
+              nodeId: "text",
+              parentId: "root",
+              backendDOMNodeId: 4,
+              role: { type: "role", value: "button" },
+            },
+          ],
+          [
+            dom(1, null, "body"),
+            dom(2, 1, "button", { "aria-label": "Add row" }),
+            dom(3, 1, "button", { title: "Settings" }),
+            dom(4, 1, "button"),
+            dom(5, 4, "span", {}, "Save"),
+          ],
+        ),
+      ],
+    });
+
+    expect(scene.nodes.filter((node) => node.role === "button").map((node) => node.name)).toEqual([
+      "Add row",
+      "Settings",
+      "Save",
+    ]);
+  });
+
+  it("isolates equal backend node ids in sibling frames", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 1000, height: 800 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["owner-a", "owner-b"],
+            },
+            {
+              nodeId: "owner-a",
+              parentId: "root",
+              backendDOMNodeId: 10,
+              role: { type: "role", value: "Iframe" },
+            },
+            {
+              nodeId: "owner-b",
+              parentId: "root",
+              backendDOMNodeId: 20,
+              role: { type: "role", value: "Iframe" },
+            },
+          ],
+          [dom(1, null, "body"), dom(10, 1, "iframe"), dom(20, 1, "iframe")],
+        ),
+        document(
+          "frame-a",
+          [
+            {
+              nodeId: "button-a",
+              backendDOMNodeId: 5,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Accept" },
+            },
+          ],
+          [dom(5, null, "button")],
+          { parentFrameId: "main", ownerBackendNodeId: 10 },
+        ),
+        document(
+          "frame-b",
+          [
+            {
+              nodeId: "button-b",
+              backendDOMNodeId: 5,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Decline" },
+            },
+          ],
+          [dom(5, null, "button")],
+          { parentFrameId: "main", ownerBackendNodeId: 20 },
+        ),
+      ],
+    });
+
+    const frameButtons = scene.nodes.filter((node) => node.backendNodeId === 5);
+    const owners = new Map(
+      scene.nodes
+        .filter((node) => node.backendNodeId === 10 || node.backendNodeId === 20)
+        .map((node) => [node.backendNodeId, node.id]),
+    );
+    expect(frameButtons.map((node) => node.frameId)).toEqual(["frame-a", "frame-b"]);
+    expect(frameButtons.map((node) => node.parentId)).toEqual([owners.get(10), owners.get(20)]);
+    expect(renderVom(scene).refs.map((ref) => [ref.frameId, ref.backendNodeId])).toEqual([
+      ["frame-a", 5],
+      ["frame-b", 5],
+    ]);
+  });
+});
diff --git a/apps/extension/src/tools/vom/capture.ts b/apps/extension/src/tools/vom/capture.ts
index 806abdfc..d713d902 100644
--- a/apps/extension/src/tools/vom/capture.ts
+++ b/apps/extension/src/tools/vom/capture.ts
@@ -1020,7 +1020,13 @@ export async function captureViewModel(
   options: CaptureViewModelOptions = {},
 ): Promise<CapturedViewModel> {
   throwIfAborted(options.signal);
-  const metrics = await cdp.send<LayoutMetricsReply>(tabId, "Page.getLayoutMetrics", {});
+  let metrics: LayoutMetricsReply = {};
+  try {
+    metrics = await cdp.send<LayoutMetricsReply>(tabId, "Page.getLayoutMetrics", {});
+  } catch (error) {
+    if (isAbortError(error)) throw error;
+    console.debug("[bsk capture] layout metrics unavailable", error);
+  }
   throwIfAborted(options.signal);
   const dpr = devicePixelRatio(metrics);
   const vpSrc = metrics.cssLayoutViewport ?? metrics.layoutViewport ?? {};
diff --git a/apps/extension/src/tools/vom/frame-capture.ts b/apps/extension/src/tools/vom/frame-capture.ts
index aef97ed1..d643a7bc 100644
--- a/apps/extension/src/tools/vom/frame-capture.ts
+++ b/apps/extension/src/tools/vom/frame-capture.ts
@@ -33,25 +33,19 @@ async function discoverFrameGraph(cdp: CdpRunner, tabId: number): Promise<CdpFra
 
 function transformFrameNodes(
   nodes: CapturedNode[],
-  projection: GeometryProjection,
+  projection: GeometryProjection | null,
 ): CapturedNode[] {
   return nodes.map((node) => ({
     ...node,
-    rect: (() => {
-      const bounds = projectRectToViewport(node.rect, projection);
-      return bounds ? { x: bounds.x, y: bounds.y, w: bounds.width, h: bounds.height } : null;
-    })(),
+    rect: projection
+      ? (() => {
+          const bounds = projectRectToViewport(node.rect, projection);
+          return bounds ? { x: bounds.x, y: bounds.y, w: bounds.width, h: bounds.height } : null;
+        })()
+      : null,
   }));
 }
 
-function frameOwnerNode(captured: CapturedViewModel, frame: CdpFrame): CapturedNode | undefined {
-  if (frame.ownerBackendNodeId === undefined) return undefined;
-  const parentNodes = frame.parentFrameId
-    ? captured.frameNodes?.get(frame.parentFrameId)
-    : captured.nodes;
-  return parentNodes?.find((node) => node.backendNodeId === frame.ownerBackendNodeId);
-}
-
 async function captureMissingFrameDocuments(
   cdp: CdpRunner,
   tabId: number,
@@ -65,14 +59,20 @@ async function captureMissingFrameDocuments(
 
   for (const frame of graph.frames) {
     if (!frame.target.sessionId || captured.frameNodes.has(frame.frameId)) continue;
-    const owner = frameOwnerNode(captured, frame);
-    if (!owner?.rect || frame.ownerBackendNodeId === undefined) continue;
     try {
       const child = await captureViewModel(cdpRunnerForTarget(cdp, frame.target), tabId, {
         signal,
       });
-      const projection = await resolveFrameProjection(cdp, graph, frame.frameId);
-      if (!projection) continue;
+      let projection: GeometryProjection | null = null;
+      try {
+        projection = await resolveFrameProjection(cdp, graph, frame.frameId);
+      } catch (err) {
+        if (isAbortError(err)) throw err;
+        console.debug("[bsk observation] child frame geometry projection failed", {
+          frameId: frame.frameId,
+          err,
+        });
+      }
       const rootFrameId = child.rootFrameId ?? frame.frameId;
       const childFrames = child.frameNodes ?? new Map<string, CapturedNode[]>();
       if (!childFrames.has(rootFrameId)) childFrames.set(rootFrameId, child.nodes);
@@ -85,11 +85,13 @@ async function captureMissingFrameDocuments(
       for (const [childFrameId, nodes] of childFrames) {
         captured.frameNodes.set(childFrameId, transformFrameNodes(nodes, projection));
       }
-      captured.iframeNodes.set(
-        frame.ownerBackendNodeId,
-        captured.frameNodes.get(frame.frameId) ?? [],
-      );
-      captured.frameOwnerBackendNodeIds.set(frame.frameId, frame.ownerBackendNodeId);
+      if (frame.ownerBackendNodeId !== undefined) {
+        captured.iframeNodes.set(
+          frame.ownerBackendNodeId,
+          captured.frameNodes.get(frame.frameId) ?? [],
+        );
+        captured.frameOwnerBackendNodeIds.set(frame.frameId, frame.ownerBackendNodeId);
+      }
       if (frame.parentFrameId) captured.frameParentIds.set(frame.frameId, frame.parentFrameId);
       for (const [childFrameId, ownerBackendNodeId] of child.frameOwnerBackendNodeIds ?? []) {
         captured.frameOwnerBackendNodeIds.set(childFrameId, ownerBackendNodeId);
diff --git a/apps/extension/src/tools/vom/semantic-graph/build.ts b/apps/extension/src/tools/vom/semantic-graph/build.ts
new file mode 100644
index 00000000..c1530bd7
--- /dev/null
+++ b/apps/extension/src/tools/vom/semantic-graph/build.ts
@@ -0,0 +1,154 @@
+import type { Viewport } from "@browser-skill/vom";
+import type { FrameDocument } from "../frame-document";
+import {
+  frameAxKey,
+  frameBackendKey,
+  type SemanticAxNode,
+  type SemanticFrame,
+  type SemanticGraph,
+  type SemanticGraphNode,
+  type SemanticNodeId,
+} from "./types";
+
+export interface BuildSemanticGraphInput {
+  documents: FrameDocument<SemanticAxNode>[];
+  viewport: Viewport;
+  rootFrameId?: string;
+  excludedBackendNodeIds?: ReadonlySet<number>;
+}
+
+function domNodeId(frameId: string, backendNodeId: number): SemanticNodeId {
+  return JSON.stringify([frameId, "dom", backendNodeId]);
+}
+
+function axNodeId(frameId: string, nodeId: string): SemanticNodeId {
+  return JSON.stringify([frameId, "ax", nodeId]);
+}
+
+export function buildSemanticGraph(input: BuildSemanticGraphInput): SemanticGraph {
+  const rootFrameId =
+    input.rootFrameId ??
+    input.documents.find((document) => !document.parentFrameId)?.frameId ??
+    input.documents[0]?.frameId ??
+    "root";
+  const frames = new Map<string, SemanticFrame>();
+  const nodes = new Map<SemanticNodeId, SemanticGraphNode>();
+  const nodeIdsByFrame = new Map<string, SemanticNodeId[]>();
+  const nodeByFrameBackend = new Map<string, SemanticNodeId>();
+  const nodeByFrameAx = new Map<string, SemanticNodeId>();
+
+  for (const [frameOrder, document] of input.documents.entries()) {
+    frames.set(document.frameId, {
+      frameId: document.frameId,
+      ...(document.parentFrameId ? { parentFrameId: document.parentFrameId } : {}),
+      ...(document.ownerBackendNodeId !== undefined
+        ? { ownerBackendNodeId: document.ownerBackendNodeId }
+        : {}),
+      contextScopeId: document.contextScopeId,
+      target: document.target,
+      ...(document.url ? { url: document.url } : {}),
+      order: frameOrder,
+    });
+
+    const frameNodeIds: SemanticNodeId[] = [];
+    nodeIdsByFrame.set(document.frameId, frameNodeIds);
+    for (const [index, dom] of document.domNodes.entries()) {
+      const id = domNodeId(document.frameId, dom.backendNodeId);
+      const node: SemanticGraphNode = {
+        id,
+        frameId: document.frameId,
+        backendNodeId: dom.backendNodeId,
+        dom,
+        sourceOrder: index,
+        excluded:
+          document.frameId === rootFrameId &&
+          input.excludedBackendNodeIds?.has(dom.backendNodeId) === true,
+      };
+      nodes.set(id, node);
+      frameNodeIds.push(id);
+      nodeByFrameBackend.set(frameBackendKey(document.frameId, dom.backendNodeId), id);
+    }
+
+    for (const [index, ax] of document.axNodes.entries()) {
+      const joinedId =
+        typeof ax.backendDOMNodeId === "number"
+          ? nodeByFrameBackend.get(frameBackendKey(document.frameId, ax.backendDOMNodeId))
+          : undefined;
+      const id = joinedId ?? axNodeId(document.frameId, ax.nodeId);
+      const existing = nodes.get(id);
+      if (existing) {
+        existing.ax = ax;
+        existing.axNodeId = ax.nodeId;
+      } else {
+        nodes.set(id, {
+          id,
+          frameId: document.frameId,
+          ...(typeof ax.backendDOMNodeId === "number"
+            ? { backendNodeId: ax.backendDOMNodeId }
+            : {}),
+          axNodeId: ax.nodeId,
+          ax,
+          sourceOrder: document.domNodes.length + index,
+          excluded:
+            document.frameId === rootFrameId &&
+            typeof ax.backendDOMNodeId === "number" &&
+            input.excludedBackendNodeIds?.has(ax.backendDOMNodeId) === true,
+        });
+        frameNodeIds.push(id);
+      }
+      nodeByFrameAx.set(frameAxKey(document.frameId, ax.nodeId), id);
+    }
+  }
+
+  for (const document of input.documents) {
+    for (const dom of document.domNodes) {
+      const id = nodeByFrameBackend.get(frameBackendKey(document.frameId, dom.backendNodeId));
+      const node = id ? nodes.get(id) : undefined;
+      if (!node || dom.parentBackendNodeId === null) continue;
+      node.domParentId = nodeByFrameBackend.get(
+        frameBackendKey(document.frameId, dom.parentBackendNodeId),
+      );
+    }
+    for (const ax of document.axNodes) {
+      const id = nodeByFrameAx.get(frameAxKey(document.frameId, ax.nodeId));
+      const node = id ? nodes.get(id) : undefined;
+      if (!node || !ax.parentId) continue;
+      node.axParentId = nodeByFrameAx.get(frameAxKey(document.frameId, ax.parentId));
+    }
+  }
+
+  const axChildren = new Map<SemanticNodeId, SemanticNodeId[]>();
+  const excludedQueue: SemanticNodeId[] = [];
+  for (const node of nodes.values()) {
+    if (node.axParentId) {
+      const children = axChildren.get(node.axParentId) ?? [];
+      children.push(node.id);
+      axChildren.set(node.axParentId, children);
+    }
+    if (node.excluded) excludedQueue.push(node.id);
+  }
+  for (let index = 0; index < excludedQueue.length; index += 1) {
+    for (const childId of axChildren.get(excludedQueue[index]) ?? []) {
+      const child = nodes.get(childId);
+      if (!child || child.excluded) continue;
+      child.excluded = true;
+      excludedQueue.push(childId);
+    }
+  }
+
+  for (const frame of frames.values()) {
+    if (!frame.parentFrameId || frame.ownerBackendNodeId === undefined) continue;
+    frame.ownerNodeId = nodeByFrameBackend.get(
+      frameBackendKey(frame.parentFrameId, frame.ownerBackendNodeId),
+    );
+  }
+
+  return {
+    viewport: input.viewport,
+    rootFrameId,
+    frames,
+    nodes,
+    nodeIdsByFrame,
+    nodeByFrameBackend,
+  };
+}
diff --git a/apps/extension/src/tools/vom/semantic-graph/index.ts b/apps/extension/src/tools/vom/semantic-graph/index.ts
new file mode 100644
index 00000000..211cad17
--- /dev/null
+++ b/apps/extension/src/tools/vom/semantic-graph/index.ts
@@ -0,0 +1,26 @@
+import type { Viewport, VomScene } from "@browser-skill/vom";
+import type { FrameDocument } from "../frame-document";
+import { buildSemanticGraph } from "./build";
+import { projectSemanticGraph } from "./project";
+import { resolveSemanticGraph } from "./resolve";
+import type { SemanticAxNode } from "./types";
+
+export type { SemanticAxNode } from "./types";
+
+export function buildSemanticVomScene(input: {
+  documents: FrameDocument<SemanticAxNode>[];
+  viewport: Viewport;
+  rootFrameId?: string;
+  excludedBackendNodeIds?: ReadonlySet<number>;
+}): VomScene {
+  return projectSemanticGraph(
+    resolveSemanticGraph(
+      buildSemanticGraph({
+        documents: input.documents,
+        viewport: input.viewport,
+        rootFrameId: input.rootFrameId,
+        excludedBackendNodeIds: input.excludedBackendNodeIds,
+      }),
+    ),
+  );
+}
diff --git a/apps/extension/src/tools/vom/semantic-graph/project.ts b/apps/extension/src/tools/vom/semantic-graph/project.ts
new file mode 100644
index 00000000..fe5ef279
--- /dev/null
+++ b/apps/extension/src/tools/vom/semantic-graph/project.ts
@@ -0,0 +1,242 @@
+import {
+  applyVomInteractionRecovery,
+  isVomReferenceNode,
+  type VomNode,
+  type VomScene,
+} from "@browser-skill/vom";
+import type { ResolvedSemanticGraph, ResolvedSemanticNode, SemanticNodeId } from "./types";
+
+const TRANSPARENT_ROLES = new Set(["", "generic", "none", "presentation", "inlinetextbox"]);
+
+function connectedFrameIds(graph: ResolvedSemanticGraph): Set<string> {
+  const connected = new Set<string>([graph.rootFrameId]);
+  const childrenByParent = new Map<string, string[]>();
+  for (const frame of graph.frames.values()) {
+    if (!frame.parentFrameId) continue;
+    const children = childrenByParent.get(frame.parentFrameId) ?? [];
+    children.push(frame.frameId);
+    childrenByParent.set(frame.parentFrameId, children);
+  }
+  const queue = [graph.rootFrameId];
+  for (let index = 0; index < queue.length; index += 1) {
+    for (const frameId of childrenByParent.get(queue[index]) ?? []) {
+      if (connected.has(frameId)) continue;
+      const frame = graph.frames.get(frameId);
+      if (!frame?.ownerNodeId) continue;
+      const owner = graph.nodes.get(frame.ownerNodeId);
+      if (!owner || owner.excluded) continue;
+      connected.add(frame.frameId);
+      queue.push(frame.frameId);
+    }
+  }
+  return connected;
+}
+
+function semanticParentId(
+  graph: ResolvedSemanticGraph,
+  node: ResolvedSemanticNode,
+): SemanticNodeId | undefined {
+  let localParent = node.axParentId ?? node.domParentId;
+  if (node.axParentId && node.domParentId && node.axParentId !== node.domParentId) {
+    const axParent = graph.nodes.get(node.axParentId);
+    const axParentRole = axParent?.vom.role?.toLowerCase() ?? "";
+    const axParentIsRoot = axParentRole === "rootwebarea" || axParentRole === "webarea";
+    const axParentIsStructural =
+      !TRANSPARENT_ROLES.has(axParentRole) ||
+      Boolean(
+        axParent?.vom.name ||
+          axParent?.vom.text ||
+          (axParent ? hasMeaningfulRelations(axParent) : false),
+      );
+    localParent = !axParentIsRoot && axParentIsStructural ? node.axParentId : node.domParentId;
+  }
+  if (localParent) return localParent;
+  if (node.frameId === graph.rootFrameId) return undefined;
+  return graph.frames.get(node.frameId)?.ownerNodeId;
+}
+
+function isChildDocumentRoot(graph: ResolvedSemanticGraph, node: ResolvedSemanticNode): boolean {
+  if (node.frameId === graph.rootFrameId) return false;
+  if (semanticParentId(graph, node) !== graph.frames.get(node.frameId)?.ownerNodeId) return false;
+  const role = node.vom.role?.toLowerCase() ?? "";
+  return role === "rootwebarea" || role === "webarea";
+}
+
+function hasMeaningfulRelations(node: ResolvedSemanticNode): boolean {
+  const attrs = node.vom.attrs ?? {};
+  return ["aria-controls", "aria-labelledby", "aria-owns", "aria-describedby"].some((name) =>
+    attrs[name]?.trim(),
+  );
+}
+
+function shouldKeepNode(
+  graph: ResolvedSemanticGraph,
+  node: ResolvedSemanticNode,
+  recovered: VomNode,
+): boolean {
+  if (node.excluded || isChildDocumentRoot(graph, node)) return false;
+  if (node.ax?.ignored) return false;
+  const role = recovered.role?.toLowerCase() ?? "";
+  if (!TRANSPARENT_ROLES.has(role)) return true;
+  return Boolean(
+    recovered.name ||
+      recovered.text ||
+      recovered.value ||
+      recovered.placeholder ||
+      hasMeaningfulRelations(node) ||
+      (recovered.rect && ["fixed", "sticky"].includes(recovered.position)),
+  );
+}
+
+function redundantSourceNodes(
+  graph: ResolvedSemanticGraph,
+  nodes: ResolvedSemanticNode[],
+): Set<SemanticNodeId> {
+  const byKey = new Map<string, ResolvedSemanticNode[]>();
+  for (const node of nodes) {
+    const name = node.vom.name?.trim().toLowerCase() ?? "";
+    if (!name || !isVomReferenceNode({ ...node.vom, id: 0, parentId: null, referenceable: true })) {
+      continue;
+    }
+    const key = `${node.frameId}\u0000${semanticParentId(graph, node) ?? ""}\u0000${node.vom.role?.toLowerCase() ?? ""}\u0000${name}\u0000${node.vom.sensitive === true}`;
+    const matches = byKey.get(key) ?? [];
+    matches.push(node);
+    byKey.set(key, matches);
+  }
+  const duplicates = new Set<SemanticNodeId>();
+  for (const matches of byKey.values()) {
+    const axOnly = matches.filter((node) => node.ax && !node.dom);
+    const domOnly = matches.filter((node) => node.dom && !node.ax);
+    if (matches.length === 2 && axOnly.length === 1 && domOnly.length === 1) {
+      duplicates.add(domOnly[0].id);
+    }
+  }
+  return duplicates;
+}
+
+function nearestKeptParent(
+  graph: ResolvedSemanticGraph,
+  nodeId: SemanticNodeId,
+  kept: ReadonlySet<SemanticNodeId>,
+  memo: Map<SemanticNodeId, SemanticNodeId | undefined>,
+): SemanticNodeId | undefined {
+  if (memo.has(nodeId)) return memo.get(nodeId);
+  let current = semanticParentId(graph, graph.nodes.get(nodeId) as ResolvedSemanticNode);
+  const seen = new Set<SemanticNodeId>();
+  const path: SemanticNodeId[] = [];
+  let result: SemanticNodeId | undefined;
+  while (current && !seen.has(current)) {
+    if (kept.has(current)) {
+      result = current;
+      break;
+    }
+    if (memo.has(current)) {
+      result = memo.get(current);
+      break;
+    }
+    seen.add(current);
+    path.push(current);
+    const parent = graph.nodes.get(current);
+    current = parent ? semanticParentId(graph, parent) : undefined;
+  }
+  memo.set(nodeId, result);
+  for (const id of path) memo.set(id, result);
+  return result;
+}
+
+function domAncestors(
+  graph: ResolvedSemanticGraph,
+  node: ResolvedSemanticNode,
+  numericId: ReadonlyMap<SemanticNodeId, number>,
+): number[] {
+  const ancestors: number[] = [];
+  const seen = new Set<SemanticNodeId>();
+  let current = node.domParentId;
+  while (current && !seen.has(current)) {
+    seen.add(current);
+    const id = numericId.get(current);
+    if (id !== undefined) ancestors.push(id);
+    current = graph.nodes.get(current)?.domParentId;
+  }
+  return ancestors;
+}
+
+export function projectSemanticGraph(graph: ResolvedSemanticGraph): VomScene {
+  const frameOwnerIds = new Set(
+    [...graph.frames.values()].flatMap((frame) => frame.ownerNodeId ?? []),
+  );
+  const connectedFrames = connectedFrameIds(graph);
+  const orderedNodes = [...graph.frames.values()]
+    .filter((frame) => connectedFrames.has(frame.frameId))
+    .sort((a, b) => a.order - b.order)
+    .flatMap((frame) =>
+      (graph.nodeIdsByFrame.get(frame.frameId) ?? [])
+        .map((id) => graph.nodes.get(id))
+        .filter((node): node is ResolvedSemanticNode => node !== undefined)
+        .sort((a, b) => a.sourceOrder - b.sourceOrder),
+    );
+
+  const provisionalNumericId = new Map<SemanticNodeId, number>();
+  orderedNodes.forEach((node, index) => provisionalNumericId.set(node.id, index + 1));
+  const provisionalNodes: VomNode[] = orderedNodes.map((node) => ({
+    ...node.vom,
+    id: provisionalNumericId.get(node.id) as number,
+    parentId: (() => {
+      const parent = semanticParentId(graph, node);
+      return parent ? (provisionalNumericId.get(parent) ?? null) : null;
+    })(),
+    ...(node.backendNodeId !== undefined ? { backendNodeId: node.backendNodeId } : {}),
+    frameId: node.frameId,
+    contextScopeId: graph.frames.get(node.frameId)?.contextScopeId ?? node.frameId,
+    referenceable: node.referenceable,
+  }));
+  const recoveredById = new Map(
+    applyVomInteractionRecovery(provisionalNodes).map((node) => [node.id, node]),
+  );
+  const duplicates = redundantSourceNodes(graph, orderedNodes);
+  const kept = new Set<SemanticNodeId>();
+  for (const node of orderedNodes) {
+    if (duplicates.has(node.id)) continue;
+    const id = provisionalNumericId.get(node.id) as number;
+    const recovered = recoveredById.get(id) as VomNode;
+    if ((!node.excluded && frameOwnerIds.has(node.id)) || shouldKeepNode(graph, node, recovered)) {
+      kept.add(node.id);
+    }
+  }
+
+  const numericId = new Map<SemanticNodeId, number>();
+  let nextId = 1;
+  for (const node of orderedNodes) {
+    if (!kept.has(node.id)) continue;
+    numericId.set(node.id, nextId);
+    nextId += 1;
+  }
+
+  const nodes: VomNode[] = [];
+  const keptParentMemo = new Map<SemanticNodeId, SemanticNodeId | undefined>();
+  for (const node of orderedNodes) {
+    const id = numericId.get(node.id);
+    if (id === undefined) continue;
+    const provisional = recoveredById.get(provisionalNumericId.get(node.id) as number) as VomNode;
+    const parent = nearestKeptParent(graph, node.id, kept, keptParentMemo);
+    const domParent = node.domParentId ? numericId.get(node.domParentId) : undefined;
+    nodes.push({
+      ...provisional,
+      id,
+      parentId: parent ? (numericId.get(parent) ?? null) : null,
+      ...(node.backendNodeId !== undefined ? { backendNodeId: node.backendNodeId } : {}),
+      ...(node.dom
+        ? {
+            domParentId: node.domParentId === undefined ? null : (domParent ?? null),
+            domAncestorIds: domAncestors(graph, node, numericId),
+          }
+        : {}),
+    });
+  }
+
+  return {
+    viewport: graph.viewport,
+    nodes,
+    rootFrameId: graph.rootFrameId,
+  };
+}
diff --git a/apps/extension/src/tools/vom/semantic-graph/resolve.ts b/apps/extension/src/tools/vom/semantic-graph/resolve.ts
new file mode 100644
index 00000000..9a3b7617
--- /dev/null
+++ b/apps/extension/src/tools/vom/semantic-graph/resolve.ts
@@ -0,0 +1,527 @@
+import type { VomNode } from "@browser-skill/vom";
+import type {
+  ResolvedSemanticGraph,
+  ResolvedSemanticNode,
+  SemanticAxNode,
+  SemanticGraph,
+  SemanticGraphNode,
+  SemanticNodeId,
+} from "./types";
+
+const FORM_TAGS = new Set(["input", "textarea", "select"]);
+const NATIVE_CONTROL_TAGS = new Set(["button", "input", "select", "textarea"]);
+const TEXT_AX_ROLES = new Set(["statictext", "inlinetextbox", "labeltext", "text"]);
+const INTERACTIVE_ROLES = new Set([
+  "button",
+  "checkbox",
+  "combobox",
+  "link",
+  "listbox",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "option",
+  "radio",
+  "searchbox",
+  "slider",
+  "spinbutton",
+  "switch",
+  "tab",
+  "textbox",
+  "treeitem",
+]);
+const SENSITIVE_INPUT_TYPES = new Set([
+  "password",
+  "credit-card",
+  "one-time-code",
+  "current-password",
+  "new-password",
+]);
+
+function clean(value: string | undefined): string | undefined {
+  const normalized = value?.replace(/\s+/g, " ").trim();
+  return normalized || undefined;
+}
+
+function axValue(field?: { value?: string | number | boolean }): string | undefined {
+  return field?.value === undefined ? undefined : clean(String(field.value));
+}
+
+function axProperty(node: SemanticAxNode | undefined, name: string): string | undefined {
+  return axValue(node?.properties?.find((property) => property.name === name)?.value);
+}
+
+function normalizeRole(value: string | undefined): string | undefined {
+  const role = clean(value)?.toLowerCase();
+  return role || undefined;
+}
+
+function nativeRole(tag: string, attrs: Record<string, string>): string | undefined {
+  const explicit = normalizeRole(attrs.role);
+  if (explicit) return explicit;
+  if (tag === "button") return "button";
+  if (tag === "textarea") return "textbox";
+  if (tag === "select") return attrs.multiple === undefined ? "combobox" : "listbox";
+  if (tag === "a" && attrs.href) return "link";
+  if (tag === "iframe") return "Iframe";
+  if (tag === "dialog") return "dialog";
+  if (tag === "img") return "img";
+  if (tag === "table") return "table";
+  if (tag === "tr") return "row";
+  if (tag === "th") return "columnheader";
+  if (tag === "td") return "cell";
+  if (tag === "ul" || tag === "ol") return "list";
+  if (tag === "li") return "listitem";
+  if (/^h[1-6]$/.test(tag)) return "heading";
+  if (tag === "nav") return "navigation";
+  if (tag === "main") return "main";
+  if (tag === "form") return "form";
+  if (tag === "input") {
+    const type = (attrs.type ?? "text").toLowerCase();
+    if (type === "hidden") return undefined;
+    if (type === "checkbox") return "checkbox";
+    if (type === "radio") return "radio";
+    if (type === "range") return "slider";
+    if (type === "number") return "spinbutton";
+    if (type === "search") return "searchbox";
+    if (["button", "submit", "reset", "image"].includes(type)) return "button";
+    return "textbox";
+  }
+  return undefined;
+}
+
+function resolvedRole(node: SemanticGraphNode): string | undefined {
+  const rawAxRole = clean(axValue(node.ax?.role));
+  const axRole = normalizeRole(rawAxRole);
+  const domRole = nativeRole(node.dom?.tag.toLowerCase() ?? "", node.dom?.attrs ?? {});
+  if (!axRole || ["generic", "none", "presentation"].includes(axRole)) {
+    return domRole ?? rawAxRole;
+  }
+  return rawAxRole;
+}
+
+function sensitive(node: SemanticGraphNode): boolean {
+  const attrs = node.dom?.attrs ?? {};
+  const type = (attrs.type ?? "").toLowerCase();
+  const autocomplete = (attrs.autocomplete ?? "").toLowerCase();
+  return (
+    type === "password" ||
+    autocomplete.startsWith("cc-") ||
+    SENSITIVE_INPUT_TYPES.has(autocomplete) ||
+    SENSITIVE_INPUT_TYPES.has(axProperty(node.ax, "inputType") ?? "")
+  );
+}
+
+function inputState(
+  node: SemanticGraphNode,
+  role: string | undefined,
+  value: string | undefined,
+  isSensitive: boolean,
+): VomNode["inputState"] {
+  if (node.dom?.formState) return node.dom.formState;
+  const tag = node.dom?.tag.toLowerCase() ?? "";
+  if (!FORM_TAGS.has(tag) && !["textbox", "searchbox"].includes(role ?? "")) return undefined;
+  if (isSensitive) return value ? "filled" : "empty";
+  if (node.dom?.formValue !== undefined) {
+    if (node.dom.formValue === "") return "empty";
+    return node.dom.formValue === (node.dom.formDefaultValue ?? "") ? "default" : "filled";
+  }
+  return value ? "filled" : "empty";
+}
+
+function externalHrefHost(
+  href: string | undefined,
+  pageUrl: string | undefined,
+): string | undefined {
+  if (!href || !pageUrl) return undefined;
+  try {
+    const page = new URL(pageUrl);
+    const target = new URL(href, page);
+    return target.origin === page.origin ? undefined : target.hostname;
+  } catch {
+    return undefined;
+  }
+}
+
+function iconKeyword(value: string | undefined): string | undefined {
+  const token = clean(value)
+    ?.split(/[#/.\s:_-]+/)
+    .filter(Boolean)
+    .pop();
+  return token && /^[a-z][a-z0-9_-]{1,32}$/i.test(token) ? token.toLowerCase() : undefined;
+}
+
+interface ResolveIndexes {
+  domChildren: Map<SemanticNodeId, SemanticNodeId[]>;
+  axChildren: Map<SemanticNodeId, SemanticNodeId[]>;
+  domIdIndex: Map<string, SemanticNodeId>;
+  labelForIndex: Map<string, SemanticNodeId[]>;
+  domText: (nodeId: SemanticNodeId) => string | undefined;
+  axText: (nodeId: SemanticNodeId) => string | undefined;
+  hasNativeDescendant: (nodeId: SemanticNodeId) => boolean;
+}
+
+function buildIndexes(graph: SemanticGraph): ResolveIndexes {
+  const domChildren = new Map<SemanticNodeId, SemanticNodeId[]>();
+  const axChildren = new Map<SemanticNodeId, SemanticNodeId[]>();
+  const domIdIndex = new Map<string, SemanticNodeId>();
+  const labelForIndex = new Map<string, SemanticNodeId[]>();
+  for (const node of graph.nodes.values()) {
+    if (node.domParentId) {
+      const children = domChildren.get(node.domParentId) ?? [];
+      children.push(node.id);
+      domChildren.set(node.domParentId, children);
+    }
+    if (node.axParentId) {
+      const children = axChildren.get(node.axParentId) ?? [];
+      children.push(node.id);
+      axChildren.set(node.axParentId, children);
+    }
+    const id = clean(node.dom?.attrs.id);
+    if (id) domIdIndex.set(`${node.frameId}\u0000${id}`, node.id);
+    const targetId = clean(node.dom?.attrs.for);
+    if (node.dom?.tag.toLowerCase() === "label" && targetId) {
+      const key = `${node.frameId}\u0000${targetId}`;
+      const labels = labelForIndex.get(key) ?? [];
+      labels.push(node.id);
+      labelForIndex.set(key, labels);
+    }
+  }
+
+  for (const [parentId, children] of axChildren) {
+    const order = graph.nodes.get(parentId)?.ax?.childIds ?? [];
+    const orderByAxId = new Map(order.map((nodeId, index) => [nodeId, index]));
+    children.sort((a, b) => {
+      const aIndex = orderByAxId.get(graph.nodes.get(a)?.axNodeId ?? "") ?? -1;
+      const bIndex = orderByAxId.get(graph.nodes.get(b)?.axNodeId ?? "") ?? -1;
+      return (
+        (aIndex < 0 ? Number.MAX_SAFE_INTEGER : aIndex) -
+        (bIndex < 0 ? Number.MAX_SAFE_INTEGER : bIndex)
+      );
+    });
+  }
+
+  const textMemo = new Map<SemanticNodeId, string | undefined>();
+  const resolvingText = new Set<SemanticNodeId>();
+  const domText = (nodeId: SemanticNodeId): string | undefined => {
+    if (textMemo.has(nodeId)) return textMemo.get(nodeId);
+    if (resolvingText.has(nodeId)) return undefined;
+    resolvingText.add(nodeId);
+    const node = graph.nodes.get(nodeId);
+    const parts: string[] = [];
+    const own = clean(node?.dom?.textContent);
+    if (own) parts.push(own);
+    for (const childId of domChildren.get(nodeId) ?? []) {
+      const child = graph.nodes.get(childId);
+      const childRole = child
+        ? nativeRole(child.dom?.tag.toLowerCase() ?? "", child.dom?.attrs ?? {})
+        : undefined;
+      if (childRole && INTERACTIVE_ROLES.has(childRole.toLowerCase())) continue;
+      const childText = domText(childId);
+      if (childText) parts.push(childText);
+      if (parts.join(" ").length >= 240) break;
+    }
+    resolvingText.delete(nodeId);
+    const result = clean(parts.join(" ").slice(0, 240));
+    textMemo.set(nodeId, result);
+    return result;
+  };
+
+  const axTextMemo = new Map<SemanticNodeId, string | undefined>();
+  const resolvingAxText = new Set<SemanticNodeId>();
+  const axText = (nodeId: SemanticNodeId): string | undefined => {
+    if (axTextMemo.has(nodeId)) return axTextMemo.get(nodeId);
+    if (resolvingAxText.has(nodeId)) return undefined;
+    resolvingAxText.add(nodeId);
+    const node = graph.nodes.get(nodeId);
+    const role = normalizeRole(axValue(node?.ax?.role)) ?? "";
+    const parts: string[] = [];
+    if (TEXT_AX_ROLES.has(role)) {
+      const own = clean(axValue(node?.ax?.name) ?? axValue(node?.ax?.value));
+      if (own) parts.push(own);
+    }
+    for (const childId of axChildren.get(nodeId) ?? []) {
+      const child = graph.nodes.get(childId);
+      const childRole = normalizeRole(axValue(child?.ax?.role)) ?? "";
+      if (INTERACTIVE_ROLES.has(childRole)) continue;
+      const childText = axText(childId);
+      if (childText) parts.push(childText);
+      if (parts.join(" ").length >= 240) break;
+    }
+    resolvingAxText.delete(nodeId);
+    const result = clean(parts.join(" ").slice(0, 240));
+    axTextMemo.set(nodeId, result);
+    return result;
+  };
+
+  const nativeMemo = new Map<SemanticNodeId, boolean>();
+  const hasNativeDescendant = (nodeId: SemanticNodeId): boolean => {
+    const cached = nativeMemo.get(nodeId);
+    if (cached !== undefined) return cached;
+    nativeMemo.set(nodeId, false);
+    for (const childId of domChildren.get(nodeId) ?? []) {
+      const child = graph.nodes.get(childId);
+      const childRole =
+        normalizeRole(axValue(child?.ax?.role)) ??
+        (child
+          ? nativeRole(child.dom?.tag.toLowerCase() ?? "", child.dom?.attrs ?? {})
+          : undefined);
+      if (
+        (child?.dom && NATIVE_CONTROL_TAGS.has(child.dom.tag.toLowerCase())) ||
+        INTERACTIVE_ROLES.has(childRole ?? "") ||
+        hasNativeDescendant(childId)
+      ) {
+        nativeMemo.set(nodeId, true);
+        return true;
+      }
+    }
+    return false;
+  };
+
+  return {
+    domChildren,
+    axChildren,
+    domIdIndex,
+    labelForIndex,
+    domText,
+    axText,
+    hasNativeDescendant,
+  };
+}
+
+function ariaLabelledText(node: SemanticGraphNode, indexes: ResolveIndexes): string | undefined {
+  const ids = (node.dom?.attrs["aria-labelledby"] ?? "").split(/\s+/).filter(Boolean);
+  const parts = ids.flatMap((id) => {
+    const target = indexes.domIdIndex.get(`${node.frameId}\u0000${id}`);
+    return target ? (indexes.domText(target) ?? []) : [];
+  });
+  return clean(parts.join(" "));
+}
+
+function nativeLabelText(
+  node: SemanticGraphNode,
+  graph: SemanticGraph,
+  indexes: ResolveIndexes,
+): string | undefined {
+  const id = clean(node.dom?.attrs.id);
+  if (id) {
+    const labels = indexes.labelForIndex.get(`${node.frameId}\u0000${id}`) ?? [];
+    const explicit = clean(
+      labels
+        .map((labelId) => indexes.domText(labelId))
+        .filter(Boolean)
+        .join(" "),
+    );
+    if (explicit) return explicit;
+  }
+  let parentId = node.domParentId;
+  let guard = 0;
+  while (parentId && guard <= graph.nodes.size) {
+    const parent = graph.nodes.get(parentId);
+    if (!parent) break;
+    if (parent.dom?.tag.toLowerCase() === "label") return indexes.domText(parentId);
+    parentId = parent.domParentId;
+    guard += 1;
+  }
+  return undefined;
+}
+
+function precedingAxText(
+  node: SemanticGraphNode,
+  graph: SemanticGraph,
+  indexes: ResolveIndexes,
+): string | undefined {
+  if (!node.axParentId) return undefined;
+  const siblings = indexes.axChildren.get(node.axParentId) ?? [];
+  const index = siblings.indexOf(node.id);
+  for (let offset = 1; offset <= 4 && index - offset >= 0; offset += 1) {
+    const sibling = graph.nodes.get(siblings[index - offset]);
+    const role = normalizeRole(axValue(sibling?.ax?.role)) ?? "";
+    if (INTERACTIVE_ROLES.has(role)) break;
+    if (!TEXT_AX_ROLES.has(role) && role !== "generic") continue;
+    const text = clean(axValue(sibling?.ax?.name) ?? axValue(sibling?.ax?.value))?.replace(
+      /[：:]\s*$/,
+      "",
+    );
+    if (text && text.length <= 80) return text;
+  }
+  return undefined;
+}
+
+function precedingDomText(
+  node: SemanticGraphNode,
+  graph: SemanticGraph,
+  indexes: ResolveIndexes,
+): string | undefined {
+  if (!node.domParentId) return undefined;
+  const siblings = indexes.domChildren.get(node.domParentId) ?? [];
+  const index = siblings.indexOf(node.id);
+  for (let offset = 1; offset <= 4 && index - offset >= 0; offset += 1) {
+    const sibling = graph.nodes.get(siblings[index - offset]);
+    const siblingRole = sibling
+      ? nativeRole(sibling.dom?.tag.toLowerCase() ?? "", sibling.dom?.attrs ?? {})
+      : undefined;
+    if (siblingRole && INTERACTIVE_ROLES.has(siblingRole.toLowerCase())) break;
+    const text = indexes.domText(siblings[index - offset])?.replace(/[：:]\s*$/, "");
+    if (text && text.length <= 80) return text;
+  }
+  return undefined;
+}
+
+function iconHint(
+  nodeId: SemanticNodeId,
+  graph: SemanticGraph,
+  indexes: ResolveIndexes,
+  depth = 0,
+): string | undefined {
+  if (depth > 3) return undefined;
+  for (const childId of indexes.domChildren.get(nodeId) ?? []) {
+    const child = graph.nodes.get(childId);
+    const attrs = child?.dom?.attrs ?? {};
+    const hint =
+      iconKeyword(attrs["aria-label"]) ??
+      iconKeyword(attrs.title) ??
+      iconKeyword(attrs.href) ??
+      iconKeyword(attrs["xlink:href"]) ??
+      iconKeyword(axValue(child?.ax?.name)) ??
+      iconKeyword(attrs.class) ??
+      iconKeyword(child?.dom?.textContent);
+    if (hint) return hint;
+    const nested = iconHint(childId, graph, indexes, depth + 1);
+    if (nested) return nested;
+  }
+  return undefined;
+}
+
+function resolvedName(
+  node: SemanticGraphNode,
+  role: string | undefined,
+  graph: SemanticGraph,
+  indexes: ResolveIndexes,
+): string | undefined {
+  const attrs = node.dom?.attrs ?? {};
+  const formControl = FORM_TAGS.has(node.dom?.tag.toLowerCase() ?? "");
+  const descendantText = indexes.domText(node.id);
+  const canUseIconHint =
+    !indexes.hasNativeDescendant(node.id) &&
+    (INTERACTIVE_ROLES.has(role?.toLowerCase() ?? "") ||
+      node.dom?.cursor === "pointer" ||
+      attrs.onclick !== undefined ||
+      attrs.tabindex !== undefined);
+  const candidates = [
+    axValue(node.ax?.name),
+    indexes.axText(node.id),
+    ariaLabelledText(node, indexes),
+    clean(attrs["aria-label"]),
+    nativeLabelText(node, graph, indexes),
+    clean(attrs.title),
+    clean(attrs.alt),
+    descendantText,
+    formControl ? precedingAxText(node, graph, indexes) : undefined,
+    formControl ? precedingDomText(node, graph, indexes) : undefined,
+    formControl ? clean(node.dom?.formPlaceholder ?? attrs.placeholder) : undefined,
+    canUseIconHint ? iconHint(node.id, graph, indexes) : undefined,
+  ];
+  let name = candidates.find((candidate) => candidate !== undefined);
+  const hasPopup = axProperty(node.ax, "hasPopup");
+  if (name && hasPopup && hasPopup !== "false") {
+    name =
+      axProperty(node.ax, "expanded") === "true" ? `${name} [expanded]` : `${name} [has-submenu]`;
+  }
+  if (!name && role?.toLowerCase() === "iframe") return clean(attrs.id);
+  return name;
+}
+
+function insideNative(node: SemanticGraphNode, graph: SemanticGraph): boolean {
+  let parentId = node.domParentId;
+  let guard = 0;
+  while (parentId && guard <= graph.nodes.size) {
+    const parent = graph.nodes.get(parentId);
+    if (!parent) break;
+    if (parent.dom && NATIVE_CONTROL_TAGS.has(parent.dom.tag.toLowerCase())) return true;
+    parentId = parent.domParentId;
+    guard += 1;
+  }
+  return false;
+}
+
+function nearbyText(
+  node: SemanticGraphNode,
+  graph: SemanticGraph,
+  indexes: ResolveIndexes,
+): string | undefined {
+  if (!node.domParentId) return undefined;
+  const siblings = indexes.domChildren.get(node.domParentId) ?? [];
+  const index = siblings.indexOf(node.id);
+  if (index < 0) return undefined;
+  const texts = siblings
+    .slice(Math.max(0, index - 3), index + 4)
+    .filter((id) => id !== node.id)
+    .flatMap((id) => indexes.domText(id) ?? [])
+    .slice(0, 3);
+  return clean(texts.join(" "));
+}
+
+export function resolveSemanticGraph(graph: SemanticGraph): ResolvedSemanticGraph {
+  const indexes = buildIndexes(graph);
+  const nodes = new Map<SemanticNodeId, ResolvedSemanticNode>();
+  for (const node of graph.nodes.values()) {
+    const role = resolvedRole(node);
+    const name = resolvedName(node, role, graph, indexes);
+    const isSensitive = sensitive(node);
+    const sourceValue = node.dom?.formValue ?? axValue(node.ax?.value);
+    const value = isSensitive ? undefined : sourceValue;
+    const attrs = { ...(node.dom?.attrs ?? {}) };
+    if (isSensitive) delete attrs.value;
+    const frame = graph.frames.get(node.frameId);
+    const tag = node.dom?.tag.toLowerCase() ?? "";
+    const vom: ResolvedSemanticNode["vom"] = {
+      tag,
+      rect: node.dom?.rect ?? null,
+      paintOrder: node.dom?.paintOrder ?? 0,
+      position: node.dom?.position || "static",
+      pointerEvents: node.dom?.pointerEvents || "auto",
+      ...(node.dom?.cursor ? { cursor: node.dom.cursor } : {}),
+      ...(role ? { role } : {}),
+      ...(name ? { name } : {}),
+      ...(value !== undefined ? { value } : {}),
+      ...(clean(node.dom?.formPlaceholder ?? attrs.placeholder)
+        ? { placeholder: clean(node.dom?.formPlaceholder ?? attrs.placeholder) }
+        : {}),
+      attrs,
+      ...(clean(node.dom?.textContent) ? { text: clean(node.dom?.textContent) } : {}),
+      ...(nearbyText(node, graph, indexes) ? { nearbyText: nearbyText(node, graph, indexes) } : {}),
+      inputState: inputState(node, role, sourceValue, isSensitive),
+      sensitive: isSensitive,
+      modal:
+        ["dialog", "alertdialog"].includes(role?.toLowerCase() ?? "") ||
+        tag === "dialog" ||
+        (attrs["aria-modal"] ?? "").toLowerCase() === "true",
+      disabled:
+        Object.prototype.hasOwnProperty.call(attrs, "disabled") ||
+        (attrs["aria-disabled"] ?? "").toLowerCase() === "true",
+      inert: Object.prototype.hasOwnProperty.call(attrs, "inert"),
+      hasNativeDescendant: indexes.hasNativeDescendant(node.id),
+      insideNative: insideNative(node, graph),
+      ...(role?.toLowerCase() === "link" ? { href: externalHrefHost(attrs.href, frame?.url) } : {}),
+    };
+    const selected = axProperty(node.ax, "selected");
+    const expanded = axProperty(node.ax, "expanded");
+    const controls = axProperty(node.ax, "controls");
+    if (selected === "true" && !vom.attrs?.["aria-selected"]) {
+      vom.attrs = { ...(vom.attrs ?? {}), "aria-selected": "true" };
+    }
+    if (expanded === "true" && !vom.attrs?.["aria-expanded"]) {
+      vom.attrs = { ...(vom.attrs ?? {}), "aria-expanded": "true" };
+    }
+    if (controls && !vom.attrs?.["aria-controls"]) {
+      vom.attrs = { ...(vom.attrs ?? {}), "aria-controls": controls };
+    }
+    nodes.set(node.id, {
+      ...node,
+      vom,
+      referenceable: node.backendNodeId !== undefined,
+    });
+  }
+  return { ...graph, nodes };
+}
diff --git a/apps/extension/src/tools/vom/semantic-graph/types.ts b/apps/extension/src/tools/vom/semantic-graph/types.ts
new file mode 100644
index 00000000..3cb098b9
--- /dev/null
+++ b/apps/extension/src/tools/vom/semantic-graph/types.ts
@@ -0,0 +1,69 @@
+import type { Viewport, VomNode } from "@browser-skill/vom";
+import type { CdpTarget } from "@/browser-driver/frame-graph";
+import type { CapturedNode } from "../capture";
+
+export interface SemanticAxNode {
+  nodeId: string;
+  frameId?: string;
+  parentId?: string;
+  backendDOMNodeId?: number;
+  ignored?: boolean;
+  role?: { type: string; value?: string };
+  name?: { type: string; value?: string };
+  description?: { value?: string };
+  value?: { value?: string | number | boolean };
+  properties?: Array<{ name?: string; value?: { value?: string | number | boolean } }>;
+  childIds?: string[];
+}
+
+export type SemanticNodeId = string;
+
+export interface SemanticFrame {
+  frameId: string;
+  parentFrameId?: string;
+  ownerBackendNodeId?: number;
+  ownerNodeId?: SemanticNodeId;
+  contextScopeId: string;
+  target: CdpTarget;
+  url?: string;
+  order: number;
+}
+
+export interface SemanticGraphNode {
+  id: SemanticNodeId;
+  frameId: string;
+  backendNodeId?: number;
+  axNodeId?: string;
+  ax?: SemanticAxNode;
+  dom?: CapturedNode;
+  axParentId?: SemanticNodeId;
+  domParentId?: SemanticNodeId;
+  sourceOrder: number;
+  excluded: boolean;
+}
+
+export interface SemanticGraph {
+  viewport: Viewport;
+  rootFrameId: string;
+  frames: Map<string, SemanticFrame>;
+  nodes: Map<SemanticNodeId, SemanticGraphNode>;
+  nodeIdsByFrame: Map<string, SemanticNodeId[]>;
+  nodeByFrameBackend: Map<string, SemanticNodeId>;
+}
+
+export interface ResolvedSemanticNode extends SemanticGraphNode {
+  vom: Omit<VomNode, "id" | "parentId" | "backendNodeId" | "frameId" | "contextScopeId">;
+  referenceable: boolean;
+}
+
+export interface ResolvedSemanticGraph extends Omit<SemanticGraph, "nodes"> {
+  nodes: Map<SemanticNodeId, ResolvedSemanticNode>;
+}
+
+export function frameBackendKey(frameId: string, backendNodeId: number): string {
+  return `${frameId}\u0000${backendNodeId}`;
+}
+
+export function frameAxKey(frameId: string, axNodeId: string): string {
+  return `${frameId}\u0000${axNodeId}`;
+}
diff --git a/packages/vom/src/render.ts b/packages/vom/src/render.ts
index c5f76fdf..d20c7851 100644
--- a/packages/vom/src/render.ts
+++ b/packages/vom/src/render.ts
@@ -199,7 +199,10 @@ function shouldRender(node: VomNode): boolean {
 }
 
 export function isVomReferenceNode(node: VomNode): boolean {
-  return INTERACTIVE_ROLES.has(normalizedRole(node)) || isUrlBearingStructuralAction(node);
+  return (
+    node.referenceable !== false &&
+    (INTERACTIVE_ROLES.has(normalizedRole(node)) || isUrlBearingStructuralAction(node))
+  );
 }
 
 function hasRecoveryHandler(node: VomNode): boolean {
diff --git a/packages/vom/src/types.ts b/packages/vom/src/types.ts
index 187091bb..fe35016b 100644
--- a/packages/vom/src/types.ts
+++ b/packages/vom/src/types.ts
@@ -24,6 +24,8 @@ export interface VomNode {
   backendNodeId?: number;
   frameId?: string;
   contextScopeId?: string;
+  /** False for semantic-only nodes that cannot be addressed through CDP. */
+  referenceable?: boolean;
 
   role?: string;
   name?: string;

From b5062ac19b61f5937d5acf8b2a2619c0c174c4f4 Mon Sep 17 00:00:00 2001
From: Ljy-0827 <liujunyao0827@gmail.com>
Date: Thu, 20 Aug 2026 16:13:20 +0800
Subject: [PATCH 2/5] feat(vom): fix name lost

---
 apps/extension/src/tools/observation.ts       |  34 +-
 .../vom/__tests__/name-enrichment.test.ts     | 161 +++++++
 .../vom/__tests__/semantic-graph.test.ts      | 333 +++++++++++++
 apps/extension/src/tools/vom/capture.ts       |  35 +-
 .../src/tools/vom/hover-perception.ts         |  37 ++
 .../src/tools/vom/name-enrichment.ts          | 294 ++++++++++++
 .../src/tools/vom/semantic-graph/index.ts     |  57 ++-
 .../tools/vom/semantic-graph/name-evidence.ts |  34 ++
 .../src/tools/vom/semantic-graph/project.ts   | 203 +-------
 .../src/tools/vom/semantic-graph/resolve.ts   | 114 +++--
 .../src/tools/vom/semantic-graph/structure.ts | 436 ++++++++++++++++++
 .../src/tools/vom/semantic-graph/types.ts     |  16 +
 packages/vom/src/__tests__/render.test.ts     |  78 ++++
 packages/vom/src/index.ts                     |   7 +-
 packages/vom/src/render.ts                    |  53 ++-
 15 files changed, 1588 insertions(+), 304 deletions(-)
 create mode 100644 apps/extension/src/tools/vom/__tests__/name-enrichment.test.ts
 create mode 100644 apps/extension/src/tools/vom/hover-perception.ts
 create mode 100644 apps/extension/src/tools/vom/name-enrichment.ts
 create mode 100644 apps/extension/src/tools/vom/semantic-graph/name-evidence.ts
 create mode 100644 apps/extension/src/tools/vom/semantic-graph/structure.ts

diff --git a/apps/extension/src/tools/observation.ts b/apps/extension/src/tools/observation.ts
index ed290d96..aa1a6a53 100644
--- a/apps/extension/src/tools/observation.ts
+++ b/apps/extension/src/tools/observation.ts
@@ -59,7 +59,15 @@ import {
   projectRecordSafeObservation,
 } from "./vom/record-safe-observation";
 import type { FrameDocument } from "./vom/frame-document";
-import { buildSemanticVomScene, type SemanticAxNode } from "./vom/semantic-graph";
+import { probeTooltipNames } from "./vom/name-enrichment";
+import {
+  buildSemanticGraph,
+  buildSemanticVomScene,
+  normalizeSemanticStructure,
+  projectSemanticGraph,
+  resolveSemanticGraph,
+  type SemanticAxNode,
+} from "./vom/semantic-graph";
 
 // ---------------------------------------------------------------------------
 // Shared helpers (legacy aliases — observation.ts kept exporting these
@@ -641,6 +649,7 @@ function findSurfaceNodeByPoint(
 
 export interface BuildVomSceneOptions {
   pageUrl?: string;
+  supplementalNames?: ReadonlyMap<string, string>;
 }
 
 export type VomFrameDocument = CapturedFrameDocument<CdpAxNode>;
@@ -800,13 +809,14 @@ export function buildVomScene(
 export function buildFrameVomScene(
   documents: VomFrameDocument[],
   captured: CapturedViewModel,
-  _options: BuildVomSceneOptions = {},
+  options: BuildVomSceneOptions = {},
 ): VomScene {
   const scene = buildSemanticVomScene({
     documents: documents as FrameDocument<SemanticAxNode>[],
     viewport: captured.viewport,
     rootFrameId: captured.rootFrameId,
     excludedBackendNodeIds: captured.excludedBackendNodeIds,
+    supplementalNames: options.supplementalNames,
   });
   const rootDocument = documents.find((document) => document.frameId === scene.rootFrameId);
   const signals = capturedOnlySignals(rootDocument?.domNodes ?? captured.nodes);
@@ -1027,7 +1037,25 @@ export async function captureVomObservation(
     documents.length === 1 && captured.iframeNodes.size > 0
       ? legacyFrameDocuments(documents[0].axNodes, captured, url, documents[0].target)
       : documents;
-  const scene = buildFrameVomScene(normalizedDocuments, captured, { pageUrl: url });
+  const semanticGraph = buildSemanticGraph({
+    documents: normalizedDocuments as FrameDocument<SemanticAxNode>[],
+    viewport: captured.viewport,
+    rootFrameId: captured.rootFrameId,
+    excludedBackendNodeIds: captured.excludedBackendNodeIds,
+  });
+  const staticSemantics = resolveSemanticGraph(semanticGraph, { identifierFallback: false });
+  const tooltipNames = options.conditionalSurfaceProbe
+    ? await probeTooltipNames(cdp, tabId, normalizedDocuments, staticSemantics, {
+        signal: options.signal,
+        hoverProbeBypassOverlay: options.hoverProbeBypassOverlay,
+      })
+    : new Map<string, string>();
+  throwIfAborted(options.signal, "observation");
+  const scene = projectSemanticGraph(
+    normalizeSemanticStructure(
+      resolveSemanticGraph(semanticGraph, { supplementalNames: tooltipNames }),
+    ),
+  );
   const rendered = renderVom(scene, {
     maxDepth: options.maxDepth,
     maxTokens: options.maxTokens,
diff --git a/apps/extension/src/tools/vom/__tests__/name-enrichment.test.ts b/apps/extension/src/tools/vom/__tests__/name-enrichment.test.ts
new file mode 100644
index 00000000..5165ff8c
--- /dev/null
+++ b/apps/extension/src/tools/vom/__tests__/name-enrichment.test.ts
@@ -0,0 +1,161 @@
+import { describe, expect, it, vi } from "vitest";
+import type { CdpTarget } from "@/browser-driver/frame-graph";
+import type { CdpRunner } from "../../shared";
+import type { CapturedNode } from "../capture";
+import type { FrameDocument, FrameOwnedAxNode } from "../frame-document";
+import { probeTooltipNames } from "../name-enrichment";
+import { buildSemanticGraph, resolveSemanticGraph } from "../semantic-graph";
+import { stableIdentifierName } from "../semantic-graph/name-evidence";
+import { frameBackendKey } from "../semantic-graph/types";
+
+function document(
+  target: CdpTarget,
+  backendNodeId: number,
+  accessibleName?: string,
+  frameId = "child",
+  x = 10,
+): FrameDocument<FrameOwnedAxNode> {
+  const node: CapturedNode = {
+    backendNodeId,
+    parentBackendNodeId: null,
+    frameId,
+    tag: "button",
+    attrs: {
+      id: "toolInsertRecord",
+      "data-test-id": "toolInsertRecord",
+      ...(accessibleName ? { "aria-label": accessibleName } : {}),
+    },
+    rect: { x, y: 20, w: 40, h: 30 },
+    localRect: { x: 2, y: 3, w: 40, h: 30 },
+    paintOrder: 1,
+    position: "static",
+    pointerEvents: "auto",
+    cursor: "pointer",
+  };
+  return {
+    frameId,
+    parentFrameId: "main",
+    contextScopeId: "child",
+    target,
+    axNodes: [],
+    domNodes: [node],
+    url: "https://example.com/frame",
+  };
+}
+
+function semantics(documents: FrameDocument<FrameOwnedAxNode>[]) {
+  return resolveSemanticGraph(
+    buildSemanticGraph({
+      documents,
+      viewport: { width: 800, height: 600 },
+      rootFrameId: documents[0]?.frameId,
+    }),
+    { identifierFallback: false },
+  );
+}
+
+describe("tooltip name enrichment", () => {
+  it("uses the owning frame target and upgrades an identifier name from a tooltip", async () => {
+    const target = { tabId: 7, sessionId: "oopif-session" };
+    let hovered = false;
+    const cdp: CdpRunner = {
+      send: vi.fn(async (_tabId, method, params) => {
+        if (method === "Input.dispatchMouseEvent") {
+          hovered = (params as { x?: number }).x === 30;
+        }
+        return {};
+      }) as CdpRunner["send"],
+      sendToTarget: vi.fn(async (_target, method) => {
+        if (method === "Page.createIsolatedWorld") return { executionContextId: 11 };
+        if (method === "DOM.resolveNode") return { object: { objectId: "button-501" } };
+        if (method === "Runtime.callFunctionOn") {
+          return { result: { value: hovered ? ["插入行"] : [] } };
+        }
+        return {};
+      }) as CdpRunner["sendToTarget"],
+    };
+
+    const documents = [document(target, 501)];
+    const graph = semantics(documents);
+    const names = await probeTooltipNames(cdp, 7, documents, graph);
+
+    expect(names.get(frameBackendKey("child", 501))).toBe("插入行");
+    expect(cdp.sendToTarget).toHaveBeenCalledWith(
+      target,
+      "Page.createIsolatedWorld",
+      expect.objectContaining({ frameId: "child" }),
+    );
+
+    const sendsBeforeCache = vi.mocked(cdp.send).mock.calls.length;
+    const targetSendsBeforeCache = vi.mocked(
+      cdp.sendToTarget as NonNullable<CdpRunner["sendToTarget"]>,
+    ).mock.calls.length;
+    const cached = await probeTooltipNames(cdp, 7, documents, graph);
+    expect(cached.get(frameBackendKey("child", 501))).toBe("插入行");
+    expect(cdp.send).toHaveBeenCalledTimes(sendsBeforeCache);
+    expect(cdp.sendToTarget).toHaveBeenCalledTimes(targetSendsBeforeCache);
+  });
+
+  it("does not probe controls that already have a higher-confidence name", async () => {
+    const cdp: CdpRunner = {
+      send: vi.fn(async () => ({})) as CdpRunner["send"],
+      sendToTarget: vi.fn(async () => ({ executionContextId: 12 })) as CdpRunner["sendToTarget"],
+    };
+
+    const documents = [document({ tabId: 8 }, 601, "Add a new record")];
+    const names = await probeTooltipNames(cdp, 8, documents, semantics(documents));
+
+    expect(names.size).toBe(0);
+    expect(cdp.send).not.toHaveBeenCalled();
+    expect(cdp.sendToTarget).not.toHaveBeenCalled();
+  });
+
+  it("keeps tooltip evidence isolated across sibling frame sessions", async () => {
+    let hoveredX = -10;
+    const cdp: CdpRunner = {
+      send: vi.fn(async (_tabId, method, params) => {
+        if (method === "Input.dispatchMouseEvent") {
+          hoveredX = (params as { x: number }).x;
+        }
+        return {};
+      }) as CdpRunner["send"],
+      sendToTarget: vi.fn(async (target, method, params) => {
+        if (method === "Page.createIsolatedWorld") {
+          return { executionContextId: target.sessionId === "left-session" ? 21 : 22 };
+        }
+        if (method === "DOM.resolveNode") {
+          return { object: { objectId: target.sessionId === "left-session" ? "left" : "right" } };
+        }
+        if (method === "Runtime.callFunctionOn") {
+          const objectId = (params as { objectId: string }).objectId;
+          const value =
+            objectId === "left" && hoveredX === 30
+              ? ["Left action"]
+              : objectId === "right" && hoveredX === 130
+                ? ["Right action"]
+                : [];
+          return { result: { value } };
+        }
+        return {};
+      }) as CdpRunner["sendToTarget"],
+    };
+    const documents = [
+      document({ tabId: 9, sessionId: "left-session" }, 701, undefined, "left", 10),
+      document({ tabId: 9, sessionId: "right-session" }, 701, undefined, "right", 110),
+    ];
+
+    const names = await probeTooltipNames(cdp, 9, documents, semantics(documents));
+
+    expect(names.get(frameBackendKey("left", 701))).toBe("Left action");
+    expect(names.get(frameBackendKey("right", 701))).toBe("Right action");
+  });
+});
+
+describe("stable identifier evidence", () => {
+  it("accepts readable action identifiers and rejects framework-generated ids", () => {
+    expect(stableIdentifierName({ id: "toolInsertRecord" })).toBe("Insert record");
+    expect(stableIdentifierName({ id: "reactivateAccount" })).toBe("Reactivate account");
+    expect(stableIdentifierName({ id: "headlessui-menu-button-r1" })).toBeUndefined();
+    expect(stableIdentifierName({ id: "7f15a3bc91" })).toBeUndefined();
+  });
+});
diff --git a/apps/extension/src/tools/vom/__tests__/semantic-graph.test.ts b/apps/extension/src/tools/vom/__tests__/semantic-graph.test.ts
index eb9d6560..b5f95c1b 100644
--- a/apps/extension/src/tools/vom/__tests__/semantic-graph.test.ts
+++ b/apps/extension/src/tools/vom/__tests__/semantic-graph.test.ts
@@ -141,6 +141,64 @@ describe("semantic VOM graph", () => {
     ]);
   });
 
+  it("uses stable identifiers only as a final name fallback", () => {
+    const base = document(
+      "main",
+      [
+        {
+          nodeId: "root",
+          backendDOMNodeId: 1,
+          role: { type: "role", value: "RootWebArea" },
+          childIds: ["fallback", "labelled", "container"],
+        },
+        {
+          nodeId: "fallback",
+          parentId: "root",
+          backendDOMNodeId: 2,
+          role: { type: "role", value: "button" },
+        },
+        {
+          nodeId: "labelled",
+          parentId: "root",
+          backendDOMNodeId: 3,
+          role: { type: "role", value: "button" },
+          name: { type: "computedString", value: "Localized name" },
+        },
+        {
+          nodeId: "container",
+          parentId: "root",
+          backendDOMNodeId: 4,
+          role: { type: "role", value: "generic" },
+        },
+      ],
+      [
+        dom(1, null, "body"),
+        dom(2, 1, "button", { "data-test-id": "toolInsertRecord" }),
+        dom(3, 1, "button", { id: "toolIgnoredFallback" }),
+        dom(4, 1, "div", { id: "toolbarContainer" }),
+      ],
+    );
+    const staticScene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [base],
+    });
+    const enrichedScene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [base],
+      supplementalNames: new Map([["main\u00002", "插入行"]]),
+    });
+
+    expect(staticScene.nodes.find((node) => node.backendNodeId === 2)?.name).toBe("Insert record");
+    expect(staticScene.nodes.find((node) => node.backendNodeId === 3)?.name).toBe("Localized name");
+    expect(staticScene.nodes.find((node) => node.backendNodeId === 4)?.name).toBeUndefined();
+    expect(enrichedScene.nodes.find((node) => node.backendNodeId === 2)?.name).toBe("插入行");
+    expect(enrichedScene.nodes.find((node) => node.backendNodeId === 3)?.name).toBe(
+      "Localized name",
+    );
+  });
+
   it("isolates equal backend node ids in sibling frames", () => {
     const scene = buildSemanticVomScene({
       viewport: { width: 1000, height: 800 },
@@ -212,4 +270,279 @@ describe("semantic VOM graph", () => {
       ["frame-b", 5],
     ]);
   });
+
+  it("lets explicit DOM structure override ignored AX metadata", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["toolbar"],
+            },
+            {
+              nodeId: "toolbar",
+              parentId: "root",
+              backendDOMNodeId: 2,
+              ignored: true,
+              role: { type: "role", value: "generic" },
+              childIds: ["wrapper"],
+            },
+            {
+              nodeId: "wrapper",
+              parentId: "toolbar",
+              backendDOMNodeId: 5,
+              role: { type: "role", value: "generic" },
+              childIds: ["bold", "italic"],
+            },
+            {
+              nodeId: "bold",
+              parentId: "wrapper",
+              backendDOMNodeId: 3,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Bold" },
+            },
+            {
+              nodeId: "italic",
+              parentId: "wrapper",
+              backendDOMNodeId: 4,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Italic" },
+            },
+          ],
+          [
+            dom(1, null, "body"),
+            dom(2, 1, "div", { role: "toolbar" }),
+            dom(5, 2, "div"),
+            dom(3, 5, "button"),
+            dom(4, 5, "button"),
+          ],
+        ),
+      ],
+    });
+
+    const toolbar = scene.nodes.find((node) => node.backendNodeId === 2);
+    const buttons = scene.nodes.filter((node) => [3, 4].includes(node.backendNodeId ?? -1));
+    expect(toolbar).toEqual(expect.objectContaining({ role: "toolbar" }));
+    expect(toolbar && isVomReferenceNode(toolbar)).toBe(false);
+    expect(scene.nodes.some((node) => node.role === "group")).toBe(false);
+    expect(buttons.map((node) => node.parentId)).toEqual([toolbar?.id, toolbar?.id]);
+  });
+
+  it("infers an unnamed group only from independent interaction branches", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["wrapper"],
+            },
+            {
+              nodeId: "wrapper",
+              parentId: "root",
+              backendDOMNodeId: 2,
+              role: { type: "role", value: "generic" },
+              childIds: ["first", "second"],
+            },
+            {
+              nodeId: "first",
+              parentId: "wrapper",
+              backendDOMNodeId: 3,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "First" },
+            },
+            {
+              nodeId: "second",
+              parentId: "wrapper",
+              backendDOMNodeId: 4,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Second" },
+            },
+          ],
+          [dom(1, null, "body"), dom(2, 1, "div"), dom(3, 2, "button"), dom(4, 2, "button")],
+        ),
+      ],
+    });
+
+    const group = scene.nodes.find((node) => node.backendNodeId === 2);
+    const buttons = scene.nodes.filter((node) => [3, 4].includes(node.backendNodeId ?? -1));
+    expect(group).toEqual(expect.objectContaining({ role: "group" }));
+    expect(group?.name).toBeUndefined();
+    expect(group && isVomReferenceNode(group)).toBe(false);
+    expect(buttons.map((node) => node.parentId)).toEqual([group?.id, group?.id]);
+  });
+
+  it("keeps uncertain single-branch wrappers flat", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["wrapper"],
+            },
+            {
+              nodeId: "wrapper",
+              parentId: "root",
+              backendDOMNodeId: 2,
+              role: { type: "role", value: "generic" },
+              childIds: ["button"],
+            },
+            {
+              nodeId: "button",
+              parentId: "wrapper",
+              backendDOMNodeId: 3,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Only action" },
+            },
+          ],
+          [dom(1, null, "body"), dom(2, 1, "div"), dom(3, 2, "button")],
+        ),
+      ],
+    });
+
+    expect(scene.nodes.some((node) => node.role === "group")).toBe(false);
+    expect(scene.nodes.find((node) => node.backendNodeId === 3)?.parentId).toBe(
+      scene.nodes.find((node) => node.backendNodeId === 1)?.id,
+    );
+  });
+
+  it("does not infer across mixed content boundaries", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["wrapper"],
+            },
+            {
+              nodeId: "wrapper",
+              parentId: "root",
+              backendDOMNodeId: 2,
+              role: { type: "role", value: "generic" },
+              childIds: ["first", "second", "paragraph"],
+            },
+            {
+              nodeId: "first",
+              parentId: "wrapper",
+              backendDOMNodeId: 3,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "First" },
+            },
+            {
+              nodeId: "second",
+              parentId: "wrapper",
+              backendDOMNodeId: 4,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Second" },
+            },
+            {
+              nodeId: "paragraph",
+              parentId: "wrapper",
+              backendDOMNodeId: 5,
+              role: { type: "role", value: "paragraph" },
+            },
+          ],
+          [
+            dom(1, null, "body"),
+            dom(2, 1, "div"),
+            dom(3, 2, "button"),
+            dom(4, 2, "button"),
+            dom(5, 2, "p", {}, "Description"),
+          ],
+        ),
+      ],
+    });
+
+    expect(scene.nodes.some((node) => node.role === "group")).toBe(false);
+  });
+
+  it("keeps only the innermost reliable inferred group", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["outer"],
+            },
+            {
+              nodeId: "outer",
+              parentId: "root",
+              backendDOMNodeId: 2,
+              role: { type: "role", value: "generic" },
+              childIds: ["inner", "third"],
+            },
+            {
+              nodeId: "inner",
+              parentId: "outer",
+              backendDOMNodeId: 3,
+              role: { type: "role", value: "generic" },
+              childIds: ["first", "second"],
+            },
+            {
+              nodeId: "first",
+              parentId: "inner",
+              backendDOMNodeId: 4,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "First" },
+            },
+            {
+              nodeId: "second",
+              parentId: "inner",
+              backendDOMNodeId: 5,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Second" },
+            },
+            {
+              nodeId: "third",
+              parentId: "outer",
+              backendDOMNodeId: 6,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Third" },
+            },
+          ],
+          [
+            dom(1, null, "body"),
+            dom(2, 1, "div"),
+            dom(3, 2, "div"),
+            dom(4, 3, "button"),
+            dom(5, 3, "button"),
+            dom(6, 2, "button"),
+          ],
+        ),
+      ],
+    });
+
+    const groups = scene.nodes.filter((node) => node.role === "group");
+    expect(groups.map((node) => node.backendNodeId)).toEqual([3]);
+    expect(scene.nodes.find((node) => node.backendNodeId === 6)?.parentId).not.toBe(groups[0]?.id);
+  });
 });
diff --git a/apps/extension/src/tools/vom/capture.ts b/apps/extension/src/tools/vom/capture.ts
index d713d902..c221d8f2 100644
--- a/apps/extension/src/tools/vom/capture.ts
+++ b/apps/extension/src/tools/vom/capture.ts
@@ -9,6 +9,7 @@ import { evaluateHoverTrigger } from "@/lib/hover-trigger-policy";
 import { isOverlayHostNode, OVERLAY_HOST_SELECTOR } from "../../lib/overlay-bridge";
 import { childFrameProjection, type GeometryProjection, projectRectToViewport } from "../geometry";
 import type { CdpRunner } from "../shared";
+import { clearHover, waitForHover } from "./hover-perception";
 
 const REQUESTED_STYLES = ["position", "pointer-events", "cursor"] as const;
 const STYLE_COL = Object.fromEntries(
@@ -460,36 +461,6 @@ function hoverStateExpression(): string {
   })()`;
 }
 
-async function wait(ms: number, signal?: AbortSignal): Promise<void> {
-  throwIfAborted(signal);
-  await new Promise<void>((resolve, reject) => {
-    const timer = setTimeout(() => {
-      signal?.removeEventListener("abort", onAbort);
-      resolve();
-    }, ms);
-    const onAbort = () => {
-      clearTimeout(timer);
-      signal?.removeEventListener("abort", onAbort);
-      reject(captureAbortError());
-    };
-    signal?.addEventListener("abort", onAbort, { once: true });
-  });
-}
-
-async function clearHover(cdp: CdpRunner, tabId: number): Promise<void> {
-  await cdp
-    .send(tabId, "Input.dispatchMouseEvent", {
-      type: "mouseMoved",
-      x: -10,
-      y: -10,
-    })
-    .catch(() =>
-      cdp.send(tabId, "Input.dispatchMouseEvent", { type: "mouseMoved", x: 0, y: 0 }).catch(() => {
-        // best effort
-      }),
-    );
-}
-
 function capturedText(node: CapturedNode): string | undefined {
   const value =
     node.attrs["aria-label"] ?? node.attrs.title ?? node.attrs.alt ?? node.textContent ?? "";
@@ -669,7 +640,7 @@ async function probeHoverSurfaces(
         try {
           await clearHover(cdp, tabId);
           throwIfAborted(options.signal);
-          await wait(HOVER_SETTLE_MS, options.signal);
+          await waitForHover(HOVER_SETTLE_MS, options.signal);
           const baselineReply = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
             expression: hoverStateExpression(),
             returnByValue: true,
@@ -684,7 +655,7 @@ async function probeHoverSurfaces(
             y: candidate.y,
           });
           throwIfAborted(options.signal);
-          await wait(HOVER_SETTLE_MS, options.signal);
+          await waitForHover(HOVER_SETTLE_MS, options.signal);
           const collected = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
             expression: hoverStateExpression(),
             returnByValue: true,
diff --git a/apps/extension/src/tools/vom/hover-perception.ts b/apps/extension/src/tools/vom/hover-perception.ts
new file mode 100644
index 00000000..253f7926
--- /dev/null
+++ b/apps/extension/src/tools/vom/hover-perception.ts
@@ -0,0 +1,37 @@
+import type { CdpRunner } from "../shared";
+
+function abortError(): Error {
+  const error = new Error("hover perception aborted");
+  error.name = "AbortError";
+  return error;
+}
+
+export async function waitForHover(ms: number, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) throw abortError();
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      reject(abortError());
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+export async function clearHover(cdp: CdpRunner, tabId: number): Promise<void> {
+  await cdp
+    .send(tabId, "Input.dispatchMouseEvent", {
+      type: "mouseMoved",
+      x: -10,
+      y: -10,
+    })
+    .catch(() =>
+      cdp.send(tabId, "Input.dispatchMouseEvent", { type: "mouseMoved", x: 0, y: 0 }).catch(() => {
+        // Best effort cleanup.
+      }),
+    );
+}
diff --git a/apps/extension/src/tools/vom/name-enrichment.ts b/apps/extension/src/tools/vom/name-enrichment.ts
new file mode 100644
index 00000000..c94eaf2e
--- /dev/null
+++ b/apps/extension/src/tools/vom/name-enrichment.ts
@@ -0,0 +1,294 @@
+import { isVomReferenceNode } from "@browser-skill/vom";
+import { type CdpRunner, sendToCdpTarget } from "../shared";
+import type { FrameDocument, FrameOwnedAxNode } from "./frame-document";
+import { clearHover, waitForHover } from "./hover-perception";
+import { stableIdentifierName } from "./semantic-graph/name-evidence";
+import { frameBackendKey, type ResolvedSemanticGraph } from "./semantic-graph/types";
+
+const MAX_TOOLTIP_CANDIDATES = 8;
+const MAX_TOOLTIP_PROBE_MS = 2_400;
+const TOOLTIP_SETTLE_MS = 250;
+const CACHE_TTL_MS = 5 * 60_000;
+const MAX_CACHE_ENTRIES = 500;
+
+interface TooltipCacheEntry {
+  name: string;
+  expiresAt: number;
+}
+
+interface TooltipCandidate<T extends FrameOwnedAxNode> {
+  document: FrameDocument<T>;
+  backendNodeId: number;
+  x: number;
+  y: number;
+  stableIdentifier: boolean;
+}
+
+export interface TooltipNameProbeOptions {
+  signal?: AbortSignal;
+  hoverProbeBypassOverlay?: (tabId: number, enabled: boolean) => Promise<void>;
+}
+
+const tooltipCache = new Map<string, TooltipCacheEntry>();
+
+function cacheKey<T extends FrameOwnedAxNode>(
+  document: FrameDocument<T>,
+  backendNodeId: number,
+): string {
+  return `${document.target.tabId}\u0000${document.frameId}\u0000${document.url ?? ""}\u0000${backendNodeId}`;
+}
+
+function cachedName<T extends FrameOwnedAxNode>(
+  document: FrameDocument<T>,
+  backendNodeId: number,
+): string | undefined {
+  const key = cacheKey(document, backendNodeId);
+  const entry = tooltipCache.get(key);
+  if (!entry) return undefined;
+  if (entry.expiresAt <= Date.now()) {
+    tooltipCache.delete(key);
+    return undefined;
+  }
+  return entry.name;
+}
+
+function storeName<T extends FrameOwnedAxNode>(
+  document: FrameDocument<T>,
+  backendNodeId: number,
+  name: string,
+): void {
+  if (tooltipCache.size >= MAX_CACHE_ENTRIES) {
+    const oldest = tooltipCache.keys().next().value;
+    if (oldest !== undefined) tooltipCache.delete(oldest);
+  }
+  tooltipCache.set(cacheKey(document, backendNodeId), {
+    name,
+    expiresAt: Date.now() + CACHE_TTL_MS,
+  });
+}
+
+function tooltipCollectorFunction(): string {
+  return `function() {
+    const ownRoot = this && typeof this.getRootNode === "function" ? this.getRootNode() : null;
+    const roots = ownRoot && ownRoot !== document ? [ownRoot, document] : [document];
+    const items = [];
+    const seen = new Set();
+    for (const root of roots) {
+      for (const el of Array.from(root.querySelectorAll("[role='tooltip']"))) {
+        const style = getComputedStyle(el);
+        const rect = el.getBoundingClientRect();
+        if (rect.width <= 0 || rect.height <= 0) continue;
+        if (style.display === "none" || style.visibility === "hidden" || style.opacity === "0") continue;
+        const text = String(el.getAttribute("aria-label") || el.getAttribute("title") || el.textContent || "")
+          .replace(/\\s+/g, " ")
+          .trim();
+        if (!text || text.length > 160 || seen.has(text)) continue;
+        seen.add(text);
+        items.push(text);
+      }
+    }
+    return items.slice(0, 20);
+  }`;
+}
+
+function cleanTooltipDiff(before: string[], after: string[]): string | undefined {
+  const existing = new Set(before.map((value) => value.toLowerCase()));
+  const added = [...new Set(after.map((value) => value.replace(/\s+/g, " ").trim()))].filter(
+    (value) => value && !existing.has(value.toLowerCase()),
+  );
+  return added.length === 1 ? added[0] : undefined;
+}
+
+function candidates<T extends FrameOwnedAxNode>(
+  documents: FrameDocument<T>[],
+  graph: ResolvedSemanticGraph,
+): TooltipCandidate<T>[] {
+  const documentByFrame = new Map(documents.map((document) => [document.frameId, document]));
+  const byFrame = new Map<string, TooltipCandidate<T>[]>();
+  for (const node of graph.nodes.values()) {
+    if (
+      node.vom.name ||
+      !node.referenceable ||
+      node.backendNodeId === undefined ||
+      !isVomReferenceNode({
+        ...node.vom,
+        id: 0,
+        parentId: null,
+        backendNodeId: node.backendNodeId,
+        frameId: node.frameId,
+        referenceable: true,
+      })
+    ) {
+      continue;
+    }
+    const document = documentByFrame.get(node.frameId);
+    const rect = node.dom?.rect;
+    if (!document || !rect || rect.w <= 0 || rect.h <= 0) continue;
+    if (
+      rect.x + rect.w <= 0 ||
+      rect.y + rect.h <= 0 ||
+      rect.x >= graph.viewport.width ||
+      rect.y >= graph.viewport.height
+    ) {
+      continue;
+    }
+    if (
+      node.vom.disabled ||
+      node.vom.inert ||
+      node.vom.pointerEvents === "none" ||
+      node.vom.sensitive
+    ) {
+      continue;
+    }
+    const frameCandidates = byFrame.get(node.frameId) ?? [];
+    frameCandidates.push({
+      document,
+      backendNodeId: node.backendNodeId,
+      x: (Math.max(0, rect.x) + Math.min(graph.viewport.width, rect.x + rect.w)) / 2,
+      y: (Math.max(0, rect.y) + Math.min(graph.viewport.height, rect.y + rect.h)) / 2,
+      stableIdentifier: stableIdentifierName(node.dom?.attrs ?? {}) !== undefined,
+    });
+    byFrame.set(node.frameId, frameCandidates);
+  }
+
+  const out: TooltipCandidate<T>[] = [];
+  for (const stableIdentifier of [true, false]) {
+    const queues = documents.map((document) =>
+      (byFrame.get(document.frameId) ?? []).filter(
+        (candidate) => candidate.stableIdentifier === stableIdentifier,
+      ),
+    );
+    for (let index = 0; queues.some((queue) => index < queue.length); index += 1) {
+      for (const queue of queues) {
+        const candidate = queue[index];
+        if (candidate) out.push(candidate);
+      }
+    }
+  }
+  return out;
+}
+
+async function executionContextId<T extends FrameOwnedAxNode>(
+  cdp: CdpRunner,
+  document: FrameDocument<T>,
+): Promise<number | undefined> {
+  const result = await sendToCdpTarget<{ executionContextId?: number }>(
+    cdp,
+    document.target,
+    "Page.createIsolatedWorld",
+    {
+      frameId: document.frameId,
+      worldName: "bsk-vom-tooltip",
+      grantUniveralAccess: false,
+    },
+  );
+  return result.executionContextId;
+}
+
+async function resolvedObjectId<T extends FrameOwnedAxNode>(
+  cdp: CdpRunner,
+  document: FrameDocument<T>,
+  contextId: number,
+  backendNodeId: number,
+): Promise<string | undefined> {
+  const result = await sendToCdpTarget<{
+    object?: { objectId?: string };
+  }>(cdp, document.target, "DOM.resolveNode", {
+    backendNodeId,
+    executionContextId: contextId,
+  });
+  return result.object?.objectId;
+}
+
+async function tooltipTexts<T extends FrameOwnedAxNode>(
+  cdp: CdpRunner,
+  document: FrameDocument<T>,
+  objectId: string,
+): Promise<string[]> {
+  const result = await sendToCdpTarget<{
+    result?: { value?: string[] };
+  }>(cdp, document.target, "Runtime.callFunctionOn", {
+    functionDeclaration: tooltipCollectorFunction(),
+    objectId,
+    returnByValue: true,
+  });
+  return result.result?.value ?? [];
+}
+
+async function releaseObject<T extends FrameOwnedAxNode>(
+  cdp: CdpRunner,
+  document: FrameDocument<T>,
+  objectId: string,
+): Promise<void> {
+  await sendToCdpTarget(cdp, document.target, "Runtime.releaseObject", { objectId }).catch(
+    () => undefined,
+  );
+}
+
+export async function probeTooltipNames<T extends FrameOwnedAxNode>(
+  cdp: CdpRunner,
+  tabId: number,
+  documents: FrameDocument<T>[],
+  graph: ResolvedSemanticGraph,
+  options: TooltipNameProbeOptions = {},
+): Promise<Map<string, string>> {
+  const names = new Map<string, string>();
+  const pending: TooltipCandidate<T>[] = [];
+  for (const candidate of candidates(documents, graph)) {
+    const cached = cachedName(candidate.document, candidate.backendNodeId);
+    if (cached) {
+      names.set(frameBackendKey(candidate.document.frameId, candidate.backendNodeId), cached);
+    } else if (pending.length < MAX_TOOLTIP_CANDIDATES) {
+      pending.push(candidate);
+    }
+  }
+  if (pending.length === 0) return names;
+
+  const started = Date.now();
+  const contexts = new Map<string, number>();
+  await options.hoverProbeBypassOverlay?.(tabId, true).catch(() => undefined);
+  try {
+    for (const candidate of pending) {
+      if (options.signal?.aborted) throw new DOMException("observation aborted", "AbortError");
+      if (Date.now() - started >= MAX_TOOLTIP_PROBE_MS) break;
+      let objectId: string | undefined;
+      try {
+        let contextId = contexts.get(candidate.document.frameId);
+        if (contextId === undefined) {
+          contextId = await executionContextId(cdp, candidate.document);
+          if (contextId === undefined) continue;
+          contexts.set(candidate.document.frameId, contextId);
+        }
+        objectId = await resolvedObjectId(
+          cdp,
+          candidate.document,
+          contextId,
+          candidate.backendNodeId,
+        );
+        if (!objectId) continue;
+        await clearHover(cdp, tabId);
+        const before = await tooltipTexts(cdp, candidate.document, objectId);
+        await cdp.send(tabId, "Input.dispatchMouseEvent", {
+          type: "mouseMoved",
+          x: candidate.x,
+          y: candidate.y,
+        });
+        await waitForHover(TOOLTIP_SETTLE_MS, options.signal);
+        const after = await tooltipTexts(cdp, candidate.document, objectId);
+        const name = cleanTooltipDiff(before, after);
+        if (!name) continue;
+        names.set(frameBackendKey(candidate.document.frameId, candidate.backendNodeId), name);
+        storeName(candidate.document, candidate.backendNodeId, name);
+      } catch (error) {
+        if (error instanceof Error && error.name === "AbortError") throw error;
+      } finally {
+        if (objectId) await releaseObject(cdp, candidate.document, objectId);
+        await clearHover(cdp, tabId);
+      }
+    }
+  } finally {
+    await clearHover(cdp, tabId);
+    await options.hoverProbeBypassOverlay?.(tabId, false).catch(() => undefined);
+  }
+  return names;
+}
diff --git a/apps/extension/src/tools/vom/semantic-graph/index.ts b/apps/extension/src/tools/vom/semantic-graph/index.ts
index 211cad17..7e13a003 100644
--- a/apps/extension/src/tools/vom/semantic-graph/index.ts
+++ b/apps/extension/src/tools/vom/semantic-graph/index.ts
@@ -1,25 +1,58 @@
 import type { Viewport, VomScene } from "@browser-skill/vom";
 import type { FrameDocument } from "../frame-document";
-import { buildSemanticGraph } from "./build";
-import { projectSemanticGraph } from "./project";
-import { resolveSemanticGraph } from "./resolve";
-import type { SemanticAxNode } from "./types";
+import { buildSemanticGraph as buildGraph } from "./build";
+import { projectSemanticGraph as projectGraph } from "./project";
+import { resolveSemanticGraph as resolveGraph } from "./resolve";
+import { normalizeSemanticStructure as normalizeStructure } from "./structure";
+import type {
+  ResolvedSemanticGraph,
+  SemanticAxNode,
+  SemanticGraph,
+  StructuredSemanticGraph,
+} from "./types";
 
 export type { SemanticAxNode } from "./types";
 
-export function buildSemanticVomScene(input: {
+export interface SemanticVomInput {
   documents: FrameDocument<SemanticAxNode>[];
   viewport: Viewport;
   rootFrameId?: string;
   excludedBackendNodeIds?: ReadonlySet<number>;
-}): VomScene {
+}
+
+export function buildSemanticGraph(input: SemanticVomInput): SemanticGraph {
+  return buildGraph(input);
+}
+
+export function resolveSemanticGraph(
+  graph: SemanticGraph,
+  options: {
+    supplementalNames?: ReadonlyMap<string, string>;
+    identifierFallback?: boolean;
+  } = {},
+): ResolvedSemanticGraph {
+  return resolveGraph(graph, options);
+}
+
+export function normalizeSemanticStructure(graph: ResolvedSemanticGraph): StructuredSemanticGraph {
+  return normalizeStructure(graph);
+}
+
+export function projectSemanticGraph(graph: StructuredSemanticGraph): VomScene {
+  return projectGraph(graph);
+}
+
+export function buildSemanticVomScene(
+  input: SemanticVomInput & {
+    supplementalNames?: ReadonlyMap<string, string>;
+    identifierFallback?: boolean;
+  },
+): VomScene {
   return projectSemanticGraph(
-    resolveSemanticGraph(
-      buildSemanticGraph({
-        documents: input.documents,
-        viewport: input.viewport,
-        rootFrameId: input.rootFrameId,
-        excludedBackendNodeIds: input.excludedBackendNodeIds,
+    normalizeSemanticStructure(
+      resolveSemanticGraph(buildSemanticGraph(input), {
+        supplementalNames: input.supplementalNames,
+        identifierFallback: input.identifierFallback,
       }),
     ),
   );
diff --git a/apps/extension/src/tools/vom/semantic-graph/name-evidence.ts b/apps/extension/src/tools/vom/semantic-graph/name-evidence.ts
new file mode 100644
index 00000000..6dad4bc8
--- /dev/null
+++ b/apps/extension/src/tools/vom/semantic-graph/name-evidence.ts
@@ -0,0 +1,34 @@
+const IDENTIFIER_ATTRS = ["data-testid", "data-test-id", "id"] as const;
+const GENERIC_TOKENS = new Set(["btn", "button", "control", "icon", "item", "test", "tool"]);
+const GENERATED_PREFIXES = new Set(["ember", "headlessui", "mui", "radix", "react", "rc"]);
+
+function identifierTokens(value: string): string[] {
+  return value
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .split(/[^a-zA-Z0-9]+/)
+    .map((token) => token.toLowerCase())
+    .filter(Boolean);
+}
+
+function readableIdentifier(value: string | undefined): string | undefined {
+  const raw = value?.trim();
+  if (!raw || raw.length < 3 || raw.length > 80) return undefined;
+  if (/^[a-f0-9]{8,}$/i.test(raw)) return undefined;
+
+  const tokens = identifierTokens(raw);
+  if (GENERATED_PREFIXES.has(tokens[0])) return undefined;
+  while (tokens.length > 1 && GENERIC_TOKENS.has(tokens[0])) tokens.shift();
+  while (tokens.length > 1 && GENERIC_TOKENS.has(tokens[tokens.length - 1])) tokens.pop();
+  if (tokens.length === 0 || !tokens.some((token) => /[a-z]{3,}/.test(token))) return undefined;
+  return tokens
+    .map((token, index) => (index === 0 ? `${token[0].toUpperCase()}${token.slice(1)}` : token))
+    .join(" ");
+}
+
+export function stableIdentifierName(attrs: Readonly<Record<string, string>>): string | undefined {
+  for (const name of IDENTIFIER_ATTRS) {
+    const label = readableIdentifier(attrs[name]);
+    if (label) return label;
+  }
+  return undefined;
+}
diff --git a/apps/extension/src/tools/vom/semantic-graph/project.ts b/apps/extension/src/tools/vom/semantic-graph/project.ts
index fe5ef279..37e40dc0 100644
--- a/apps/extension/src/tools/vom/semantic-graph/project.ts
+++ b/apps/extension/src/tools/vom/semantic-graph/project.ts
@@ -1,14 +1,11 @@
-import {
-  applyVomInteractionRecovery,
-  isVomReferenceNode,
-  type VomNode,
-  type VomScene,
-} from "@browser-skill/vom";
-import type { ResolvedSemanticGraph, ResolvedSemanticNode, SemanticNodeId } from "./types";
+import type { VomNode, VomScene } from "@browser-skill/vom";
+import type { SemanticNodeId, StructuredSemanticGraph, StructuredSemanticNode } from "./types";
 
-const TRANSPARENT_ROLES = new Set(["", "generic", "none", "presentation", "inlinetextbox"]);
+function retained(node: StructuredSemanticNode): boolean {
+  return node.structure.kind === "keep" || node.structure.kind === "inferred-group";
+}
 
-function connectedFrameIds(graph: ResolvedSemanticGraph): Set<string> {
+function connectedFrameIds(graph: StructuredSemanticGraph): Set<string> {
   const connected = new Set<string>([graph.rootFrameId]);
   const childrenByParent = new Map<string, string[]>();
   for (const frame of graph.frames.values()) {
@@ -24,7 +21,7 @@ function connectedFrameIds(graph: ResolvedSemanticGraph): Set<string> {
       const frame = graph.frames.get(frameId);
       if (!frame?.ownerNodeId) continue;
       const owner = graph.nodes.get(frame.ownerNodeId);
-      if (!owner || owner.excluded) continue;
+      if (!owner || !retained(owner)) continue;
       connected.add(frame.frameId);
       queue.push(frame.frameId);
     }
@@ -32,121 +29,9 @@ function connectedFrameIds(graph: ResolvedSemanticGraph): Set<string> {
   return connected;
 }
 
-function semanticParentId(
-  graph: ResolvedSemanticGraph,
-  node: ResolvedSemanticNode,
-): SemanticNodeId | undefined {
-  let localParent = node.axParentId ?? node.domParentId;
-  if (node.axParentId && node.domParentId && node.axParentId !== node.domParentId) {
-    const axParent = graph.nodes.get(node.axParentId);
-    const axParentRole = axParent?.vom.role?.toLowerCase() ?? "";
-    const axParentIsRoot = axParentRole === "rootwebarea" || axParentRole === "webarea";
-    const axParentIsStructural =
-      !TRANSPARENT_ROLES.has(axParentRole) ||
-      Boolean(
-        axParent?.vom.name ||
-          axParent?.vom.text ||
-          (axParent ? hasMeaningfulRelations(axParent) : false),
-      );
-    localParent = !axParentIsRoot && axParentIsStructural ? node.axParentId : node.domParentId;
-  }
-  if (localParent) return localParent;
-  if (node.frameId === graph.rootFrameId) return undefined;
-  return graph.frames.get(node.frameId)?.ownerNodeId;
-}
-
-function isChildDocumentRoot(graph: ResolvedSemanticGraph, node: ResolvedSemanticNode): boolean {
-  if (node.frameId === graph.rootFrameId) return false;
-  if (semanticParentId(graph, node) !== graph.frames.get(node.frameId)?.ownerNodeId) return false;
-  const role = node.vom.role?.toLowerCase() ?? "";
-  return role === "rootwebarea" || role === "webarea";
-}
-
-function hasMeaningfulRelations(node: ResolvedSemanticNode): boolean {
-  const attrs = node.vom.attrs ?? {};
-  return ["aria-controls", "aria-labelledby", "aria-owns", "aria-describedby"].some((name) =>
-    attrs[name]?.trim(),
-  );
-}
-
-function shouldKeepNode(
-  graph: ResolvedSemanticGraph,
-  node: ResolvedSemanticNode,
-  recovered: VomNode,
-): boolean {
-  if (node.excluded || isChildDocumentRoot(graph, node)) return false;
-  if (node.ax?.ignored) return false;
-  const role = recovered.role?.toLowerCase() ?? "";
-  if (!TRANSPARENT_ROLES.has(role)) return true;
-  return Boolean(
-    recovered.name ||
-      recovered.text ||
-      recovered.value ||
-      recovered.placeholder ||
-      hasMeaningfulRelations(node) ||
-      (recovered.rect && ["fixed", "sticky"].includes(recovered.position)),
-  );
-}
-
-function redundantSourceNodes(
-  graph: ResolvedSemanticGraph,
-  nodes: ResolvedSemanticNode[],
-): Set<SemanticNodeId> {
-  const byKey = new Map<string, ResolvedSemanticNode[]>();
-  for (const node of nodes) {
-    const name = node.vom.name?.trim().toLowerCase() ?? "";
-    if (!name || !isVomReferenceNode({ ...node.vom, id: 0, parentId: null, referenceable: true })) {
-      continue;
-    }
-    const key = `${node.frameId}\u0000${semanticParentId(graph, node) ?? ""}\u0000${node.vom.role?.toLowerCase() ?? ""}\u0000${name}\u0000${node.vom.sensitive === true}`;
-    const matches = byKey.get(key) ?? [];
-    matches.push(node);
-    byKey.set(key, matches);
-  }
-  const duplicates = new Set<SemanticNodeId>();
-  for (const matches of byKey.values()) {
-    const axOnly = matches.filter((node) => node.ax && !node.dom);
-    const domOnly = matches.filter((node) => node.dom && !node.ax);
-    if (matches.length === 2 && axOnly.length === 1 && domOnly.length === 1) {
-      duplicates.add(domOnly[0].id);
-    }
-  }
-  return duplicates;
-}
-
-function nearestKeptParent(
-  graph: ResolvedSemanticGraph,
-  nodeId: SemanticNodeId,
-  kept: ReadonlySet<SemanticNodeId>,
-  memo: Map<SemanticNodeId, SemanticNodeId | undefined>,
-): SemanticNodeId | undefined {
-  if (memo.has(nodeId)) return memo.get(nodeId);
-  let current = semanticParentId(graph, graph.nodes.get(nodeId) as ResolvedSemanticNode);
-  const seen = new Set<SemanticNodeId>();
-  const path: SemanticNodeId[] = [];
-  let result: SemanticNodeId | undefined;
-  while (current && !seen.has(current)) {
-    if (kept.has(current)) {
-      result = current;
-      break;
-    }
-    if (memo.has(current)) {
-      result = memo.get(current);
-      break;
-    }
-    seen.add(current);
-    path.push(current);
-    const parent = graph.nodes.get(current);
-    current = parent ? semanticParentId(graph, parent) : undefined;
-  }
-  memo.set(nodeId, result);
-  for (const id of path) memo.set(id, result);
-  return result;
-}
-
 function domAncestors(
-  graph: ResolvedSemanticGraph,
-  node: ResolvedSemanticNode,
+  graph: StructuredSemanticGraph,
+  node: StructuredSemanticNode,
   numericId: ReadonlyMap<SemanticNodeId, number>,
 ): number[] {
   const ancestors: number[] = [];
@@ -161,10 +46,7 @@ function domAncestors(
   return ancestors;
 }
 
-export function projectSemanticGraph(graph: ResolvedSemanticGraph): VomScene {
-  const frameOwnerIds = new Set(
-    [...graph.frames.values()].flatMap((frame) => frame.ownerNodeId ?? []),
-  );
+export function projectSemanticGraph(graph: StructuredSemanticGraph): VomScene {
   const connectedFrames = connectedFrameIds(graph);
   const orderedNodes = [...graph.frames.values()]
     .filter((frame) => connectedFrames.has(frame.frameId))
@@ -172,67 +54,28 @@ export function projectSemanticGraph(graph: ResolvedSemanticGraph): VomScene {
     .flatMap((frame) =>
       (graph.nodeIdsByFrame.get(frame.frameId) ?? [])
         .map((id) => graph.nodes.get(id))
-        .filter((node): node is ResolvedSemanticNode => node !== undefined)
+        .filter((node): node is StructuredSemanticNode => node !== undefined && retained(node))
         .sort((a, b) => a.sourceOrder - b.sourceOrder),
     );
 
-  const provisionalNumericId = new Map<SemanticNodeId, number>();
-  orderedNodes.forEach((node, index) => provisionalNumericId.set(node.id, index + 1));
-  const provisionalNodes: VomNode[] = orderedNodes.map((node) => ({
+  const numericId = new Map<SemanticNodeId, number>();
+  orderedNodes.forEach((node, index) => numericId.set(node.id, index + 1));
+  const nodes: VomNode[] = orderedNodes.map((node) => ({
     ...node.vom,
-    id: provisionalNumericId.get(node.id) as number,
-    parentId: (() => {
-      const parent = semanticParentId(graph, node);
-      return parent ? (provisionalNumericId.get(parent) ?? null) : null;
-    })(),
+    id: numericId.get(node.id) as number,
+    parentId: node.semanticParentId ? (numericId.get(node.semanticParentId) ?? null) : null,
     ...(node.backendNodeId !== undefined ? { backendNodeId: node.backendNodeId } : {}),
     frameId: node.frameId,
     contextScopeId: graph.frames.get(node.frameId)?.contextScopeId ?? node.frameId,
     referenceable: node.referenceable,
+    ...(node.dom
+      ? {
+          domParentId:
+            node.domParentId === undefined ? null : (numericId.get(node.domParentId) ?? null),
+          domAncestorIds: domAncestors(graph, node, numericId),
+        }
+      : {}),
   }));
-  const recoveredById = new Map(
-    applyVomInteractionRecovery(provisionalNodes).map((node) => [node.id, node]),
-  );
-  const duplicates = redundantSourceNodes(graph, orderedNodes);
-  const kept = new Set<SemanticNodeId>();
-  for (const node of orderedNodes) {
-    if (duplicates.has(node.id)) continue;
-    const id = provisionalNumericId.get(node.id) as number;
-    const recovered = recoveredById.get(id) as VomNode;
-    if ((!node.excluded && frameOwnerIds.has(node.id)) || shouldKeepNode(graph, node, recovered)) {
-      kept.add(node.id);
-    }
-  }
-
-  const numericId = new Map<SemanticNodeId, number>();
-  let nextId = 1;
-  for (const node of orderedNodes) {
-    if (!kept.has(node.id)) continue;
-    numericId.set(node.id, nextId);
-    nextId += 1;
-  }
-
-  const nodes: VomNode[] = [];
-  const keptParentMemo = new Map<SemanticNodeId, SemanticNodeId | undefined>();
-  for (const node of orderedNodes) {
-    const id = numericId.get(node.id);
-    if (id === undefined) continue;
-    const provisional = recoveredById.get(provisionalNumericId.get(node.id) as number) as VomNode;
-    const parent = nearestKeptParent(graph, node.id, kept, keptParentMemo);
-    const domParent = node.domParentId ? numericId.get(node.domParentId) : undefined;
-    nodes.push({
-      ...provisional,
-      id,
-      parentId: parent ? (numericId.get(parent) ?? null) : null,
-      ...(node.backendNodeId !== undefined ? { backendNodeId: node.backendNodeId } : {}),
-      ...(node.dom
-        ? {
-            domParentId: node.domParentId === undefined ? null : (domParent ?? null),
-            domAncestorIds: domAncestors(graph, node, numericId),
-          }
-        : {}),
-    });
-  }
 
   return {
     viewport: graph.viewport,
diff --git a/apps/extension/src/tools/vom/semantic-graph/resolve.ts b/apps/extension/src/tools/vom/semantic-graph/resolve.ts
index 9a3b7617..03281cbb 100644
--- a/apps/extension/src/tools/vom/semantic-graph/resolve.ts
+++ b/apps/extension/src/tools/vom/semantic-graph/resolve.ts
@@ -1,4 +1,5 @@
 import type { VomNode } from "@browser-skill/vom";
+import { stableIdentifierName } from "./name-evidence";
 import type {
   ResolvedSemanticGraph,
   ResolvedSemanticNode,
@@ -7,6 +8,7 @@ import type {
   SemanticGraphNode,
   SemanticNodeId,
 } from "./types";
+import { frameBackendKey } from "./types";
 
 const FORM_TAGS = new Set(["input", "textarea", "select"]);
 const NATIVE_CONTROL_TAGS = new Set(["button", "input", "select", "textarea"]);
@@ -57,8 +59,6 @@ function normalizeRole(value: string | undefined): string | undefined {
 }
 
 function nativeRole(tag: string, attrs: Record<string, string>): string | undefined {
-  const explicit = normalizeRole(attrs.role);
-  if (explicit) return explicit;
   if (tag === "button") return "button";
   if (tag === "textarea") return "textbox";
   if (tag === "select") return attrs.multiple === undefined ? "combobox" : "listbox";
@@ -90,14 +90,29 @@ function nativeRole(tag: string, attrs: Record<string, string>): string | undefi
   return undefined;
 }
 
-function resolvedRole(node: SemanticGraphNode): string | undefined {
+function domRole(tag: string, attrs: Record<string, string>): string | undefined {
+  return normalizeRole(attrs.role) ?? nativeRole(tag, attrs);
+}
+
+function resolvedRole(node: SemanticGraphNode): {
+  value?: string;
+  source: ResolvedSemanticNode["roleSource"];
+} {
   const rawAxRole = clean(axValue(node.ax?.role));
   const axRole = normalizeRole(rawAxRole);
-  const domRole = nativeRole(node.dom?.tag.toLowerCase() ?? "", node.dom?.attrs ?? {});
-  if (!axRole || ["generic", "none", "presentation"].includes(axRole)) {
-    return domRole ?? rawAxRole;
+  const attrs = node.dom?.attrs ?? {};
+  const explicitDomRole = normalizeRole(attrs.role);
+  const nativeDomRole = nativeRole(node.dom?.tag.toLowerCase() ?? "", attrs);
+  const usableAxRole = node.ax?.ignored !== true;
+  if (usableAxRole && axRole && !["generic", "none", "presentation"].includes(axRole)) {
+    return { value: rawAxRole, source: "ax" };
+  }
+  if (explicitDomRole) return { value: explicitDomRole, source: "dom-explicit" };
+  if (nativeDomRole) return { value: nativeDomRole, source: "dom-native" };
+  if (rawAxRole) {
+    return { value: rawAxRole, source: usableAxRole ? "ax" : "ax-ignored" };
   }
-  return rawAxRole;
+  return { source: "none" };
 }
 
 function sensitive(node: SemanticGraphNode): boolean {
@@ -143,14 +158,6 @@ function externalHrefHost(
   }
 }
 
-function iconKeyword(value: string | undefined): string | undefined {
-  const token = clean(value)
-    ?.split(/[#/.\s:_-]+/)
-    .filter(Boolean)
-    .pop();
-  return token && /^[a-z][a-z0-9_-]{1,32}$/i.test(token) ? token.toLowerCase() : undefined;
-}
-
 interface ResolveIndexes {
   domChildren: Map<SemanticNodeId, SemanticNodeId[]>;
   axChildren: Map<SemanticNodeId, SemanticNodeId[]>;
@@ -214,7 +221,7 @@ function buildIndexes(graph: SemanticGraph): ResolveIndexes {
     for (const childId of domChildren.get(nodeId) ?? []) {
       const child = graph.nodes.get(childId);
       const childRole = child
-        ? nativeRole(child.dom?.tag.toLowerCase() ?? "", child.dom?.attrs ?? {})
+        ? domRole(child.dom?.tag.toLowerCase() ?? "", child.dom?.attrs ?? {})
         : undefined;
       if (childRole && INTERACTIVE_ROLES.has(childRole.toLowerCase())) continue;
       const childText = domText(childId);
@@ -262,10 +269,8 @@ function buildIndexes(graph: SemanticGraph): ResolveIndexes {
     for (const childId of domChildren.get(nodeId) ?? []) {
       const child = graph.nodes.get(childId);
       const childRole =
-        normalizeRole(axValue(child?.ax?.role)) ??
-        (child
-          ? nativeRole(child.dom?.tag.toLowerCase() ?? "", child.dom?.attrs ?? {})
-          : undefined);
+        (child?.ax?.ignored === true ? undefined : normalizeRole(axValue(child?.ax?.role))) ??
+        (child ? domRole(child.dom?.tag.toLowerCase() ?? "", child.dom?.attrs ?? {}) : undefined);
       if (
         (child?.dom && NATIVE_CONTROL_TAGS.has(child.dom.tag.toLowerCase())) ||
         INTERACTIVE_ROLES.has(childRole ?? "") ||
@@ -359,7 +364,7 @@ function precedingDomText(
   for (let offset = 1; offset <= 4 && index - offset >= 0; offset += 1) {
     const sibling = graph.nodes.get(siblings[index - offset]);
     const siblingRole = sibling
-      ? nativeRole(sibling.dom?.tag.toLowerCase() ?? "", sibling.dom?.attrs ?? {})
+      ? domRole(sibling.dom?.tag.toLowerCase() ?? "", sibling.dom?.attrs ?? {})
       : undefined;
     if (siblingRole && INTERACTIVE_ROLES.has(siblingRole.toLowerCase())) break;
     const text = indexes.domText(siblings[index - offset])?.replace(/[：:]\s*$/, "");
@@ -368,49 +373,23 @@ function precedingDomText(
   return undefined;
 }
 
-function iconHint(
-  nodeId: SemanticNodeId,
-  graph: SemanticGraph,
-  indexes: ResolveIndexes,
-  depth = 0,
-): string | undefined {
-  if (depth > 3) return undefined;
-  for (const childId of indexes.domChildren.get(nodeId) ?? []) {
-    const child = graph.nodes.get(childId);
-    const attrs = child?.dom?.attrs ?? {};
-    const hint =
-      iconKeyword(attrs["aria-label"]) ??
-      iconKeyword(attrs.title) ??
-      iconKeyword(attrs.href) ??
-      iconKeyword(attrs["xlink:href"]) ??
-      iconKeyword(axValue(child?.ax?.name)) ??
-      iconKeyword(attrs.class) ??
-      iconKeyword(child?.dom?.textContent);
-    if (hint) return hint;
-    const nested = iconHint(childId, graph, indexes, depth + 1);
-    if (nested) return nested;
-  }
-  return undefined;
-}
-
 function resolvedName(
   node: SemanticGraphNode,
   role: string | undefined,
   graph: SemanticGraph,
   indexes: ResolveIndexes,
+  supplementalNames: ReadonlyMap<string, string>,
+  identifierFallback: boolean,
 ): string | undefined {
   const attrs = node.dom?.attrs ?? {};
   const formControl = FORM_TAGS.has(node.dom?.tag.toLowerCase() ?? "");
   const descendantText = indexes.domText(node.id);
-  const canUseIconHint =
-    !indexes.hasNativeDescendant(node.id) &&
-    (INTERACTIVE_ROLES.has(role?.toLowerCase() ?? "") ||
-      node.dom?.cursor === "pointer" ||
-      attrs.onclick !== undefined ||
-      attrs.tabindex !== undefined);
+  const interactive =
+    INTERACTIVE_ROLES.has(role?.toLowerCase() ?? "") ||
+    NATIVE_CONTROL_TAGS.has(node.dom?.tag.toLowerCase() ?? "");
   const candidates = [
-    axValue(node.ax?.name),
-    indexes.axText(node.id),
+    node.ax?.ignored === true ? undefined : axValue(node.ax?.name),
+    node.ax?.ignored === true ? undefined : indexes.axText(node.id),
     ariaLabelledText(node, indexes),
     clean(attrs["aria-label"]),
     nativeLabelText(node, graph, indexes),
@@ -420,7 +399,10 @@ function resolvedName(
     formControl ? precedingAxText(node, graph, indexes) : undefined,
     formControl ? precedingDomText(node, graph, indexes) : undefined,
     formControl ? clean(node.dom?.formPlaceholder ?? attrs.placeholder) : undefined,
-    canUseIconHint ? iconHint(node.id, graph, indexes) : undefined,
+    !interactive || node.backendNodeId === undefined
+      ? undefined
+      : clean(supplementalNames.get(frameBackendKey(node.frameId, node.backendNodeId))),
+    identifierFallback && interactive ? stableIdentifierName(attrs) : undefined,
   ];
   let name = candidates.find((candidate) => candidate !== undefined);
   const hasPopup = axProperty(node.ax, "hasPopup");
@@ -462,12 +444,21 @@ function nearbyText(
   return clean(texts.join(" "));
 }
 
-export function resolveSemanticGraph(graph: SemanticGraph): ResolvedSemanticGraph {
+export function resolveSemanticGraph(
+  graph: SemanticGraph,
+  options: {
+    supplementalNames?: ReadonlyMap<string, string>;
+    identifierFallback?: boolean;
+  } = {},
+): ResolvedSemanticGraph {
   const indexes = buildIndexes(graph);
+  const supplementalNames = options.supplementalNames ?? new Map<string, string>();
+  const identifierFallback = options.identifierFallback ?? true;
   const nodes = new Map<SemanticNodeId, ResolvedSemanticNode>();
   for (const node of graph.nodes.values()) {
-    const role = resolvedRole(node);
-    const name = resolvedName(node, role, graph, indexes);
+    const roleResolution = resolvedRole(node);
+    const role = roleResolution.value;
+    const name = resolvedName(node, role, graph, indexes, supplementalNames, identifierFallback);
     const isSensitive = sensitive(node);
     const sourceValue = node.dom?.formValue ?? axValue(node.ax?.value);
     const value = isSensitive ? undefined : sourceValue;
@@ -505,9 +496,9 @@ export function resolveSemanticGraph(graph: SemanticGraph): ResolvedSemanticGrap
       insideNative: insideNative(node, graph),
       ...(role?.toLowerCase() === "link" ? { href: externalHrefHost(attrs.href, frame?.url) } : {}),
     };
-    const selected = axProperty(node.ax, "selected");
-    const expanded = axProperty(node.ax, "expanded");
-    const controls = axProperty(node.ax, "controls");
+    const selected = node.ax?.ignored === true ? undefined : axProperty(node.ax, "selected");
+    const expanded = node.ax?.ignored === true ? undefined : axProperty(node.ax, "expanded");
+    const controls = node.ax?.ignored === true ? undefined : axProperty(node.ax, "controls");
     if (selected === "true" && !vom.attrs?.["aria-selected"]) {
       vom.attrs = { ...(vom.attrs ?? {}), "aria-selected": "true" };
     }
@@ -521,6 +512,7 @@ export function resolveSemanticGraph(graph: SemanticGraph): ResolvedSemanticGrap
       ...node,
       vom,
       referenceable: node.backendNodeId !== undefined,
+      roleSource: roleResolution.source,
     });
   }
   return { ...graph, nodes };
diff --git a/apps/extension/src/tools/vom/semantic-graph/structure.ts b/apps/extension/src/tools/vom/semantic-graph/structure.ts
new file mode 100644
index 00000000..9b5b1a6a
--- /dev/null
+++ b/apps/extension/src/tools/vom/semantic-graph/structure.ts
@@ -0,0 +1,436 @@
+import {
+  applyVomInteractionRecovery,
+  isVomReferenceNode,
+  isVomStructuralRole,
+  type VomNode,
+} from "@browser-skill/vom";
+import type {
+  ResolvedSemanticGraph,
+  ResolvedSemanticNode,
+  SemanticNodeId,
+  StructureDecision,
+  StructuredSemanticGraph,
+  StructuredSemanticNode,
+} from "./types";
+
+const TRANSPARENT_ROLES = new Set(["", "generic", "none", "presentation", "inlinetextbox"]);
+const ROOT_ROLES = new Set(["rootwebarea", "webarea"]);
+const CONTENT_BOUNDARY_ROLES = new Set([
+  "article",
+  "dialog",
+  "document",
+  "feed",
+  "form",
+  "grid",
+  "heading",
+  "iframe",
+  "list",
+  "main",
+  "navigation",
+  "paragraph",
+  "region",
+  "section",
+  "table",
+  "tree",
+]);
+
+function hasMeaningfulRelations(node: ResolvedSemanticNode): boolean {
+  const attrs = node.vom.attrs ?? {};
+  return ["aria-controls", "aria-labelledby", "aria-owns", "aria-describedby"].some((name) =>
+    attrs[name]?.trim(),
+  );
+}
+
+function explicitStructural(node: ResolvedSemanticNode): boolean {
+  return (
+    isVomStructuralRole(node.vom.role) &&
+    node.roleSource !== "none" &&
+    node.roleSource !== "ax-ignored"
+  );
+}
+
+function initialParentId(
+  graph: ResolvedSemanticGraph,
+  node: ResolvedSemanticNode,
+): SemanticNodeId | undefined {
+  let parentId = node.axParentId ?? node.domParentId;
+  if (node.axParentId && node.domParentId && node.axParentId !== node.domParentId) {
+    const axParent = graph.nodes.get(node.axParentId);
+    const axRole = axParent?.vom.role?.toLowerCase() ?? "";
+    const meaningfulAxParent =
+      axParent !== undefined &&
+      !ROOT_ROLES.has(axRole) &&
+      (explicitStructural(axParent) ||
+        !TRANSPARENT_ROLES.has(axRole) ||
+        Boolean(axParent.vom.name || axParent.vom.text || hasMeaningfulRelations(axParent)));
+    parentId = meaningfulAxParent ? node.axParentId : node.domParentId;
+  }
+  if (parentId) return parentId;
+  if (node.frameId === graph.rootFrameId) return undefined;
+  return graph.frames.get(node.frameId)?.ownerNodeId;
+}
+
+function orderedNodes(graph: ResolvedSemanticGraph): ResolvedSemanticNode[] {
+  return [...graph.frames.values()]
+    .sort((a, b) => a.order - b.order)
+    .flatMap((frame) =>
+      (graph.nodeIdsByFrame.get(frame.frameId) ?? [])
+        .map((id) => graph.nodes.get(id))
+        .filter((node): node is ResolvedSemanticNode => node !== undefined)
+        .sort((a, b) => a.sourceOrder - b.sourceOrder),
+    );
+}
+
+function recoveredNodes(
+  graph: ResolvedSemanticGraph,
+  nodes: ResolvedSemanticNode[],
+): Map<SemanticNodeId, VomNode> {
+  const numericId = new Map(nodes.map((node, index) => [node.id, index + 1]));
+  const semanticId = new Map([...numericId].map(([id, numeric]) => [numeric, id]));
+  const provisional = nodes.map((node) => ({
+    ...node.vom,
+    id: numericId.get(node.id) as number,
+    parentId: (() => {
+      const parent = initialParentId(graph, node);
+      return parent ? (numericId.get(parent) ?? null) : null;
+    })(),
+    ...(node.backendNodeId !== undefined ? { backendNodeId: node.backendNodeId } : {}),
+    frameId: node.frameId,
+    contextScopeId: graph.frames.get(node.frameId)?.contextScopeId ?? node.frameId,
+    referenceable: node.referenceable,
+  }));
+  return new Map(
+    applyVomInteractionRecovery(provisional).flatMap((node) => {
+      const id = semanticId.get(node.id);
+      return id ? [[id, node] as const] : [];
+    }),
+  );
+}
+
+function redundantSourceNodes(
+  graph: ResolvedSemanticGraph,
+  nodes: ResolvedSemanticNode[],
+  recovered: ReadonlyMap<SemanticNodeId, VomNode>,
+): Set<SemanticNodeId> {
+  const byKey = new Map<string, ResolvedSemanticNode[]>();
+  for (const node of nodes) {
+    const output = recovered.get(node.id) as VomNode;
+    const name = output.name?.trim().toLowerCase() ?? "";
+    if (!name || !isVomReferenceNode({ ...output, referenceable: true })) continue;
+    const key = `${node.frameId}\u0000${initialParentId(graph, node) ?? ""}\u0000${output.role?.toLowerCase() ?? ""}\u0000${name}\u0000${output.sensitive === true}`;
+    const matches = byKey.get(key) ?? [];
+    matches.push(node);
+    byKey.set(key, matches);
+  }
+  const redundant = new Set<SemanticNodeId>();
+  for (const matches of byKey.values()) {
+    const axOnly = matches.filter((node) => node.ax && !node.dom);
+    const domOnly = matches.filter((node) => node.dom && !node.ax);
+    if (matches.length === 2 && axOnly.length === 1 && domOnly.length === 1) {
+      redundant.add(domOnly[0].id);
+    }
+  }
+  return redundant;
+}
+
+function baseDecision(
+  graph: ResolvedSemanticGraph,
+  node: ResolvedSemanticNode,
+  output: VomNode,
+  frameOwnerIds: ReadonlySet<SemanticNodeId>,
+  redundant: ReadonlySet<SemanticNodeId>,
+): StructureDecision {
+  if (node.excluded) return { kind: "excluded", reason: "excluded" };
+  if (redundant.has(node.id)) return { kind: "excluded", reason: "redundant-source" };
+  if (frameOwnerIds.has(node.id)) return { kind: "keep", reason: "frame-owner" };
+  if (node.frameId !== graph.rootFrameId && ROOT_ROLES.has(output.role?.toLowerCase() ?? "")) {
+    return { kind: "transparent", reason: "child-document-root" };
+  }
+  if (node.ax?.ignored === true && !node.dom) {
+    return { kind: "transparent", reason: "ax-ignored" };
+  }
+  const role = output.role?.toLowerCase() ?? "";
+  if (!TRANSPARENT_ROLES.has(role)) return { kind: "keep", reason: "semantic" };
+  if (
+    output.name ||
+    output.text ||
+    output.value ||
+    output.placeholder ||
+    hasMeaningfulRelations(node) ||
+    (output.rect && ["fixed", "sticky"].includes(output.position))
+  ) {
+    return { kind: "keep", reason: "semantic" };
+  }
+  return { kind: "transparent", reason: "wrapper" };
+}
+
+function buildChildren(
+  nodes: ResolvedSemanticNode[],
+  relation: "axParentId" | "domParentId",
+): Map<SemanticNodeId, SemanticNodeId[]> {
+  const children = new Map<SemanticNodeId, SemanticNodeId[]>();
+  for (const node of nodes) {
+    const parentId = node[relation];
+    if (!parentId) continue;
+    const siblings = children.get(parentId) ?? [];
+    siblings.push(node.id);
+    children.set(parentId, siblings);
+  }
+  return children;
+}
+
+function explicitDomAncestors(
+  graph: ResolvedSemanticGraph,
+  nodes: ResolvedSemanticNode[],
+  domChildren: ReadonlyMap<SemanticNodeId, SemanticNodeId[]>,
+): Set<SemanticNodeId> {
+  const inside = new Set<SemanticNodeId>();
+  const roots = nodes.filter((node) => !node.domParentId);
+  const queue = roots.map((node) => node.id);
+  for (let index = 0; index < queue.length; index += 1) {
+    const parentId = queue[index];
+    const parent = graph.nodes.get(parentId);
+    const parentIsBoundary =
+      parent !== undefined &&
+      explicitStructural(parent) &&
+      !ROOT_ROLES.has(parent.vom.role?.toLowerCase() ?? "");
+    for (const childId of domChildren.get(parentId) ?? []) {
+      if (inside.has(parentId) || parentIsBoundary) inside.add(childId);
+      queue.push(childId);
+    }
+  }
+  return inside;
+}
+
+function reliableGroupCandidates(
+  graph: ResolvedSemanticGraph,
+  nodes: ResolvedSemanticNode[],
+  recovered: ReadonlyMap<SemanticNodeId, VomNode>,
+  decisions: ReadonlyMap<SemanticNodeId, StructureDecision>,
+  domChildren: ReadonlyMap<SemanticNodeId, SemanticNodeId[]>,
+): Set<SemanticNodeId> {
+  const insideExplicitStructure = explicitDomAncestors(graph, nodes, domChildren);
+  const remainingChildren = new Map(
+    nodes.map((node) => [node.id, domChildren.get(node.id)?.length ?? 0]),
+  );
+  const summaries = new Map<SemanticNodeId, { blocked: boolean; interactions: number }>();
+  const queue = nodes
+    .filter((node) => (remainingChildren.get(node.id) ?? 0) === 0)
+    .map((node) => node.id);
+  for (let index = 0; index < queue.length; index += 1) {
+    const nodeId = queue[index];
+    const node = graph.nodes.get(nodeId);
+    const output = recovered.get(nodeId);
+    if (!node || !output) continue;
+    const role = output.role?.toLowerCase() ?? "";
+    const excluded = decisions.get(nodeId)?.kind === "excluded";
+    const blocked = excluded || explicitStructural(node) || CONTENT_BOUNDARY_ROLES.has(role);
+    const summary = excluded
+      ? { blocked: true, interactions: 0 }
+      : isVomReferenceNode(output)
+        ? { blocked: false, interactions: 1 }
+        : blocked
+          ? { blocked: true, interactions: 0 }
+          : (domChildren.get(nodeId) ?? []).reduce(
+              (combined, childId) => {
+                const child = summaries.get(childId);
+                return {
+                  blocked: combined.blocked || !child || child.blocked,
+                  interactions: Math.min(2, combined.interactions + (child?.interactions ?? 0)),
+                };
+              },
+              { blocked: false, interactions: 0 },
+            );
+    summaries.set(nodeId, summary);
+    const parentId = node.domParentId;
+    if (!parentId) continue;
+    const remaining = (remainingChildren.get(parentId) ?? 1) - 1;
+    remainingChildren.set(parentId, remaining);
+    if (remaining === 0) queue.push(parentId);
+  }
+
+  const candidates = new Set<SemanticNodeId>();
+  for (const node of nodes) {
+    const output = recovered.get(node.id) as VomNode;
+    const role = output.role?.toLowerCase() ?? "";
+    if (
+      !node.dom ||
+      node.dom.tag.toLowerCase() !== "div" ||
+      !TRANSPARENT_ROLES.has(role) ||
+      insideExplicitStructure.has(node.id) ||
+      decisions.get(node.id)?.kind === "excluded" ||
+      node.dom.attrs.hidden !== undefined ||
+      (node.dom.attrs["aria-hidden"] ?? "").toLowerCase() === "true" ||
+      node.dom.attrs.inert !== undefined
+    ) {
+      continue;
+    }
+
+    const branches = (domChildren.get(node.id) ?? []).map((id) => summaries.get(id));
+    const blocked = branches.some((summary) => !summary || summary.blocked);
+    const contributingBranches = branches.filter(
+      (summary) => (summary?.interactions ?? 0) > 0,
+    ).length;
+    const interactions = branches.reduce(
+      (count, summary) => Math.min(2, count + (summary?.interactions ?? 0)),
+      0,
+    );
+    if (!blocked && contributingBranches >= 2 && interactions >= 2) {
+      candidates.add(node.id);
+    }
+  }
+  return candidates;
+}
+
+function leafCandidates(
+  nodes: ResolvedSemanticNode[],
+  candidates: ReadonlySet<SemanticNodeId>,
+  domChildren: ReadonlyMap<SemanticNodeId, SemanticNodeId[]>,
+): Set<SemanticNodeId> {
+  const parentById = new Map(
+    nodes.flatMap((node) => (node.domParentId ? ([[node.id, node.domParentId]] as const) : [])),
+  );
+  const childCount = new Map(nodes.map((node) => [node.id, domChildren.get(node.id)?.length ?? 0]));
+  const containsCandidate = new Set<SemanticNodeId>();
+  const queue = nodes.filter((node) => (childCount.get(node.id) ?? 0) === 0).map((node) => node.id);
+  const selected = new Set<SemanticNodeId>();
+  for (let index = 0; index < queue.length; index += 1) {
+    const nodeId = queue[index];
+    if (candidates.has(nodeId) && !containsCandidate.has(nodeId)) selected.add(nodeId);
+    const parentId = parentById.get(nodeId);
+    if (!parentId) continue;
+    if (candidates.has(nodeId) || containsCandidate.has(nodeId)) containsCandidate.add(parentId);
+    const remaining = (childCount.get(parentId) ?? 1) - 1;
+    childCount.set(parentId, remaining);
+    if (remaining === 0) queue.push(parentId);
+  }
+  return selected;
+}
+
+function nearestKept(
+  graph: ResolvedSemanticGraph,
+  startId: SemanticNodeId | undefined,
+  relation: "axParentId" | "domParentId",
+  kept: ReadonlySet<SemanticNodeId>,
+  memo: Map<SemanticNodeId, SemanticNodeId | undefined>,
+): SemanticNodeId | undefined {
+  let currentId = startId;
+  const path: SemanticNodeId[] = [];
+  const seen = new Set<SemanticNodeId>();
+  let result: SemanticNodeId | undefined;
+  while (currentId && !seen.has(currentId)) {
+    if (kept.has(currentId)) {
+      result = currentId;
+      break;
+    }
+    if (memo.has(currentId)) {
+      result = memo.get(currentId);
+      break;
+    }
+    seen.add(currentId);
+    path.push(currentId);
+    currentId = graph.nodes.get(currentId)?.[relation];
+  }
+  for (const id of path) memo.set(id, result);
+  return result;
+}
+
+function finalParentId(
+  graph: ResolvedSemanticGraph,
+  node: ResolvedSemanticNode,
+  kept: ReadonlySet<SemanticNodeId>,
+  decisions: ReadonlyMap<SemanticNodeId, StructureDecision>,
+  axParentMemo: Map<SemanticNodeId, SemanticNodeId | undefined>,
+  domParentMemo: Map<SemanticNodeId, SemanticNodeId | undefined>,
+): SemanticNodeId | undefined {
+  const axParent = nearestKept(graph, node.axParentId, "axParentId", kept, axParentMemo);
+  const domParent = nearestKept(graph, node.domParentId, "domParentId", kept, domParentMemo);
+  const axNode = axParent ? graph.nodes.get(axParent) : undefined;
+  const domNode = domParent ? graph.nodes.get(domParent) : undefined;
+  const axIsRoot = ROOT_ROLES.has(axNode?.vom.role?.toLowerCase() ?? "");
+  const axIsExplicit = axNode ? explicitStructural(axNode) && !axIsRoot : false;
+  const domIsStructural =
+    domNode !== undefined &&
+    (explicitStructural(domNode) || decisions.get(domNode.id)?.kind === "inferred-group");
+  if (axIsExplicit) return axParent;
+  if (domIsStructural) return domParent;
+  if (axParent && !axIsRoot) return axParent;
+  if (domParent) return domParent;
+  if (axParent) return axParent;
+  if (node.frameId === graph.rootFrameId) return undefined;
+  return graph.frames.get(node.frameId)?.ownerNodeId;
+}
+
+function recoveredVom(node: VomNode, inferredGroup: boolean): ResolvedSemanticNode["vom"] {
+  const {
+    id: _id,
+    parentId: _parentId,
+    backendNodeId: _backendNodeId,
+    frameId: _frameId,
+    contextScopeId: _contextScopeId,
+    referenceable: _referenceable,
+    ...vom
+  } = node;
+  if (!inferredGroup) return vom;
+  const { name: _name, text: _text, nearbyText: _nearbyText, ...groupVom } = vom;
+  return { ...groupVom, role: "group" };
+}
+
+export function normalizeSemanticStructure(graph: ResolvedSemanticGraph): StructuredSemanticGraph {
+  const nodes = orderedNodes(graph);
+  const recovered = recoveredNodes(graph, nodes);
+  const redundant = redundantSourceNodes(graph, nodes, recovered);
+  const frameOwnerIds = new Set(
+    [...graph.frames.values()].flatMap((frame) => frame.ownerNodeId ?? []),
+  );
+  const decisions = new Map<SemanticNodeId, StructureDecision>();
+  for (const node of nodes) {
+    decisions.set(
+      node.id,
+      baseDecision(graph, node, recovered.get(node.id) as VomNode, frameOwnerIds, redundant),
+    );
+  }
+
+  const domChildren = buildChildren(nodes, "domParentId");
+  const candidates = reliableGroupCandidates(graph, nodes, recovered, decisions, domChildren);
+  for (const nodeId of leafCandidates(nodes, candidates, domChildren)) {
+    decisions.set(nodeId, {
+      kind: "inferred-group",
+      reason: "independent-interaction-branches",
+    });
+  }
+
+  const kept = new Set(
+    nodes
+      .filter((node) => {
+        const kind = decisions.get(node.id)?.kind;
+        return kind === "keep" || kind === "inferred-group";
+      })
+      .map((node) => node.id),
+  );
+  const axParentMemo = new Map<SemanticNodeId, SemanticNodeId | undefined>();
+  const domParentMemo = new Map<SemanticNodeId, SemanticNodeId | undefined>();
+  const structuredNodes = new Map<SemanticNodeId, StructuredSemanticNode>();
+  for (const node of nodes) {
+    const structure = decisions.get(node.id) as StructureDecision;
+    const inferredGroup = structure.kind === "inferred-group";
+    structuredNodes.set(node.id, {
+      ...node,
+      vom: recoveredVom(recovered.get(node.id) as VomNode, inferredGroup),
+      structure,
+      ...(kept.has(node.id)
+        ? {
+            semanticParentId: finalParentId(
+              graph,
+              node,
+              kept,
+              decisions,
+              axParentMemo,
+              domParentMemo,
+            ),
+          }
+        : {}),
+    });
+  }
+  return { ...graph, nodes: structuredNodes };
+}
diff --git a/apps/extension/src/tools/vom/semantic-graph/types.ts b/apps/extension/src/tools/vom/semantic-graph/types.ts
index 3cb098b9..bd26d768 100644
--- a/apps/extension/src/tools/vom/semantic-graph/types.ts
+++ b/apps/extension/src/tools/vom/semantic-graph/types.ts
@@ -54,12 +54,28 @@ export interface SemanticGraph {
 export interface ResolvedSemanticNode extends SemanticGraphNode {
   vom: Omit<VomNode, "id" | "parentId" | "backendNodeId" | "frameId" | "contextScopeId">;
   referenceable: boolean;
+  roleSource: "ax" | "ax-ignored" | "dom-explicit" | "dom-native" | "none";
 }
 
 export interface ResolvedSemanticGraph extends Omit<SemanticGraph, "nodes"> {
   nodes: Map<SemanticNodeId, ResolvedSemanticNode>;
 }
 
+export type StructureDecision =
+  | { kind: "keep"; reason: "semantic" | "frame-owner" }
+  | { kind: "inferred-group"; reason: "independent-interaction-branches" }
+  | { kind: "transparent"; reason: "wrapper" | "child-document-root" | "ax-ignored" }
+  | { kind: "excluded"; reason: "excluded" | "redundant-source" };
+
+export interface StructuredSemanticNode extends ResolvedSemanticNode {
+  structure: StructureDecision;
+  semanticParentId?: SemanticNodeId;
+}
+
+export interface StructuredSemanticGraph extends Omit<ResolvedSemanticGraph, "nodes"> {
+  nodes: Map<SemanticNodeId, StructuredSemanticNode>;
+}
+
 export function frameBackendKey(frameId: string, backendNodeId: number): string {
   return `${frameId}\u0000${backendNodeId}`;
 }
diff --git a/packages/vom/src/__tests__/render.test.ts b/packages/vom/src/__tests__/render.test.ts
index d8a3d049..fa02ae53 100644
--- a/packages/vom/src/__tests__/render.test.ts
+++ b/packages/vom/src/__tests__/render.test.ts
@@ -333,6 +333,84 @@ describe("renderVom single-layer page", () => {
     expect(coreRefs(out.refs)).toEqual([{ ref: "e1", backendNodeId: 2 }]);
   });
 
+  it("does not treat implementation CSS classes as control names", () => {
+    const out = renderVom(
+      scene([
+        node({ id: 1, role: "RootWebArea", name: "Doc" }),
+        node({
+          id: 2,
+          parentId: 1,
+          role: "generic",
+          cursor: "pointer",
+          attrs: { onclick: "handleClick()" },
+          rect: { x: 20, y: 20, w: 40, h: 40 },
+        }),
+        node({
+          id: 3,
+          parentId: 2,
+          role: "img",
+          tag: "svg",
+          attrs: { class: "kocomz" },
+        }),
+      ]),
+    );
+
+    expect(out.text).not.toContain("kocomz");
+    expect(out.refs).toEqual([]);
+  });
+
+  it("recovers icon controls only from explicit semantic icon evidence", () => {
+    const out = renderVom(
+      scene([
+        node({ id: 1, role: "RootWebArea", name: "Doc" }),
+        node({
+          id: 2,
+          parentId: 1,
+          role: "generic",
+          cursor: "pointer",
+          attrs: { onclick: "handleFilter()" },
+          rect: { x: 20, y: 20, w: 40, h: 40 },
+        }),
+        node({
+          id: 3,
+          parentId: 2,
+          role: "img",
+          tag: "svg",
+          attrs: { "aria-label": "Filter rows", class: "kocomz" },
+        }),
+      ]),
+    );
+
+    expect(out.text).toContain('@e1 button "Filter rows"');
+    expect(coreRefs(out.refs)).toEqual([{ ref: "e1", backendNodeId: 2 }]);
+  });
+
+  it("keeps a semantic image as evidence for its clickable wrapper", () => {
+    const out = renderVom(
+      scene([
+        node({ id: 1, role: "RootWebArea", name: "Doc" }),
+        node({
+          id: 2,
+          parentId: 1,
+          role: "generic",
+          cursor: "pointer",
+          rect: { x: 20, y: 20, w: 40, h: 40 },
+        }),
+        node({
+          id: 3,
+          parentId: 2,
+          role: "img",
+          name: "Account",
+          cursor: "pointer",
+          tag: "div",
+        }),
+      ]),
+    );
+
+    expect(out.text).toContain('@e1 button "Account"');
+    expect(coreRefs(out.refs)).toEqual([{ ref: "e1", backendNodeId: 2 }]);
+  });
+
   it("keeps the deepest custom control when wrapper and child both look clickable", () => {
     const out = renderVom(
       scene([
diff --git a/packages/vom/src/index.ts b/packages/vom/src/index.ts
index aab8507d..afbbf363 100644
--- a/packages/vom/src/index.ts
+++ b/packages/vom/src/index.ts
@@ -1,4 +1,9 @@
-export { applyVomInteractionRecovery, isVomReferenceNode, renderVom } from "./render";
+export {
+  applyVomInteractionRecovery,
+  isVomReferenceNode,
+  isVomStructuralRole,
+  renderVom,
+} from "./render";
 export type {
   ActiveScopeBlock,
   BlockingLayer,
diff --git a/packages/vom/src/render.ts b/packages/vom/src/render.ts
index d20c7851..b943dbd2 100644
--- a/packages/vom/src/render.ts
+++ b/packages/vom/src/render.ts
@@ -75,6 +75,10 @@ const STRUCTURAL_ROLES = new Set([
   "webarea",
 ]);
 
+export function isVomStructuralRole(role: string | undefined): boolean {
+  return STRUCTURAL_ROLES.has(role?.toLowerCase() ?? "");
+}
+
 const SENSITIVE_MASK = "•••";
 const DEFAULT_MAX_DEPTH = Number.POSITIVE_INFINITY;
 const DEFAULT_MAX_TOKENS = Number.POSITIVE_INFINITY;
@@ -193,7 +197,7 @@ function shouldRender(node: VomNode): boolean {
   const role = normalizedRole(node);
   if (SKIP_ROLES.has(role)) return false;
   if (INTERACTIVE_ROLES.has(role)) return true;
-  if (STRUCTURAL_ROLES.has(role)) return true;
+  if (isVomStructuralRole(role)) return true;
 
   return cleaned(node.name) !== undefined;
 }
@@ -222,14 +226,30 @@ function isContentEditable(node: VomNode): boolean {
   return contentEditable === "true" || contentEditable === "plaintext-only";
 }
 
-function iconKeyword(value: string | undefined): string | undefined {
-  const cleanedValue = cleaned(value);
-  if (!cleanedValue) return undefined;
-  const last = cleanedValue
-    .split(/[#/.\s:_-]+/)
+const ICON_REFERENCE_MARKERS = new Set(["glyph", "icon", "icons", "symbol"]);
+const ICON_REFERENCE_DECORATORS = new Set(["fill", "filled", "line", "outline", "outlined"]);
+
+function iconReferenceName(value: string | undefined): string | undefined {
+  const reference = cleaned(value);
+  if (!reference) return undefined;
+  const fragment = reference.includes("#") ? reference.slice(reference.lastIndexOf("#") + 1) : "";
+  const tokens = (fragment || reference)
+    ?.split(/[#/.\s:_-]+/)
     .filter(Boolean)
-    .pop();
-  return last && /^[a-z][a-z0-9_-]{1,32}$/i.test(last) ? last.toLowerCase() : undefined;
+    .map((token) => token.toLowerCase());
+  if (tokens.length === 0) return undefined;
+  if (fragment) {
+    const semanticTokens = tokens.filter(
+      (token) => !ICON_REFERENCE_MARKERS.has(token) && !ICON_REFERENCE_DECORATORS.has(token),
+    );
+    return semanticTokens.length > 0 ? semanticTokens.join(" ") : undefined;
+  }
+  const marker = tokens.findLastIndex((token) => ICON_REFERENCE_MARKERS.has(token));
+  if (marker < 0) return undefined;
+  const semanticTokens = tokens
+    .slice(marker + 1)
+    .filter((token) => !ICON_REFERENCE_DECORATORS.has(token));
+  return semanticTokens.length > 0 ? semanticTokens.join(" ") : undefined;
 }
 
 function iconHintFromSubtree(
@@ -241,12 +261,12 @@ function iconHintFromSubtree(
   for (const child of children.get(node.id) ?? []) {
     const attrs = child.attrs ?? {};
     const hint =
-      iconKeyword(attrs["aria-label"]) ??
-      iconKeyword(attrs.title) ??
-      iconKeyword(attrs.href) ??
-      iconKeyword(attrs["xlink:href"]) ??
-      iconKeyword(attrs.class) ??
-      iconKeyword(child.text);
+      cleaned(attrs["aria-label"]) ??
+      cleaned(attrs.title) ??
+      (normalizedRole(child) === "img" ? cleaned(child.name) : undefined) ??
+      (["img", "svg", "use"].includes(normalizedTag(child))
+        ? (iconReferenceName(attrs.href) ?? iconReferenceName(attrs["xlink:href"]))
+        : undefined);
     if (hint) return hint;
     const nested = iconHintFromSubtree(child, children, depth + 1);
     if (nested) return nested;
@@ -272,6 +292,7 @@ function recoveredRole(
   node: VomNode,
   children?: Map<number | null, VomNode[]>,
 ): string | undefined {
+  const currentRole = normalizedRole(node);
   const explicitRole = node.attrs?.role?.toLowerCase() ?? "";
   const hasHandler = hasRecoveryHandler(node);
   const focusable = isFocusable(node);
@@ -293,7 +314,9 @@ function recoveredRole(
       : "button";
   }
   if (hasHandler && hasName) return "button";
-  if (node.cursor === "pointer" && hasName) return "button";
+  if ((!currentRole || SKIP_ROLES.has(currentRole)) && node.cursor === "pointer" && hasName) {
+    return "button";
+  }
   return undefined;
 }
 

From 38fd7d3f4c87b42db431379bfe7e2ef7c06379df Mon Sep 17 00:00:00 2001
From: Ljy-0827 <liujunyao0827@gmail.com>
Date: Fri, 21 Aug 2026 13:31:32 +0800
Subject: [PATCH 3/5] fix(vom): safety policy and rebase bug fix

---
 apps/extension/src/tools/observation.ts       |  7 ++-
 .../vom/__tests__/name-enrichment.test.ts     | 22 ++++++++
 .../vom/__tests__/semantic-graph.test.ts      | 52 +++++++++++++++++++
 .../src/tools/vom/name-enrichment.ts          |  2 +
 .../src/tools/vom/semantic-graph/resolve.ts   |  2 +-
 5 files changed, 80 insertions(+), 5 deletions(-)

diff --git a/apps/extension/src/tools/observation.ts b/apps/extension/src/tools/observation.ts
index aa1a6a53..e7a7edd4 100644
--- a/apps/extension/src/tools/observation.ts
+++ b/apps/extension/src/tools/observation.ts
@@ -54,12 +54,11 @@ import {
   collectOverlayExcludedBackendIds,
 } from "./vom/capture";
 import { type CapturedFrameDocument, captureFrameData } from "./vom/frame-capture";
+import { probeTooltipNames } from "./vom/name-enrichment";
 import {
   type CaptureVomObservationResult,
   projectRecordSafeObservation,
 } from "./vom/record-safe-observation";
-import type { FrameDocument } from "./vom/frame-document";
-import { probeTooltipNames } from "./vom/name-enrichment";
 import {
   buildSemanticGraph,
   buildSemanticVomScene,
@@ -812,7 +811,7 @@ export function buildFrameVomScene(
   options: BuildVomSceneOptions = {},
 ): VomScene {
   const scene = buildSemanticVomScene({
-    documents: documents as FrameDocument<SemanticAxNode>[],
+    documents,
     viewport: captured.viewport,
     rootFrameId: captured.rootFrameId,
     excludedBackendNodeIds: captured.excludedBackendNodeIds,
@@ -1038,7 +1037,7 @@ export async function captureVomObservation(
       ? legacyFrameDocuments(documents[0].axNodes, captured, url, documents[0].target)
       : documents;
   const semanticGraph = buildSemanticGraph({
-    documents: normalizedDocuments as FrameDocument<SemanticAxNode>[],
+    documents: normalizedDocuments,
     viewport: captured.viewport,
     rootFrameId: captured.rootFrameId,
     excludedBackendNodeIds: captured.excludedBackendNodeIds,
diff --git a/apps/extension/src/tools/vom/__tests__/name-enrichment.test.ts b/apps/extension/src/tools/vom/__tests__/name-enrichment.test.ts
index 5165ff8c..425517ed 100644
--- a/apps/extension/src/tools/vom/__tests__/name-enrichment.test.ts
+++ b/apps/extension/src/tools/vom/__tests__/name-enrichment.test.ts
@@ -110,6 +110,28 @@ describe("tooltip name enrichment", () => {
     expect(cdp.sendToTarget).not.toHaveBeenCalled();
   });
 
+  it("does not collect supplemental names from form controls", async () => {
+    const cdp: CdpRunner = {
+      send: vi.fn(async () => ({})) as CdpRunner["send"],
+      sendToTarget: vi.fn(async () => ({ executionContextId: 12 })) as CdpRunner["sendToTarget"],
+    };
+    const inputDocument = document({ tabId: 8 }, 602);
+    inputDocument.domNodes[0] = {
+      ...inputDocument.domNodes[0],
+      tag: "input",
+      attrs: { type: "email" },
+      formValue: "user@example.com",
+      formDefaultValue: "",
+      formState: "filled",
+    };
+
+    const names = await probeTooltipNames(cdp, 8, [inputDocument], semantics([inputDocument]));
+
+    expect(names.size).toBe(0);
+    expect(cdp.send).not.toHaveBeenCalled();
+    expect(cdp.sendToTarget).not.toHaveBeenCalled();
+  });
+
   it("keeps tooltip evidence isolated across sibling frame sessions", async () => {
     let hoveredX = -10;
     const cdp: CdpRunner = {
diff --git a/apps/extension/src/tools/vom/__tests__/semantic-graph.test.ts b/apps/extension/src/tools/vom/__tests__/semantic-graph.test.ts
index b5f95c1b..d4dda001 100644
--- a/apps/extension/src/tools/vom/__tests__/semantic-graph.test.ts
+++ b/apps/extension/src/tools/vom/__tests__/semantic-graph.test.ts
@@ -381,6 +381,58 @@ describe("semantic VOM graph", () => {
     expect(group?.name).toBeUndefined();
     expect(group && isVomReferenceNode(group)).toBe(false);
     expect(buttons.map((node) => node.parentId)).toEqual([group?.id, group?.id]);
+
+    const rendered = renderVom(scene);
+    const lines = rendered.text.split("\n");
+    const groupLine = lines.findIndex((line) => line.trim() === "group");
+    expect(groupLine).toBeGreaterThanOrEqual(0);
+    for (const ref of rendered.refs) {
+      expect(ref.line).toBeGreaterThan(groupLine);
+      expect(lines[ref.line]).toMatch(/^\s+@e\d+ button/);
+    }
+  });
+
+  it("never promotes a form value into its semantic name through supplemental evidence", () => {
+    const secret = "user@example.com";
+    const input = {
+      ...dom(2, 1, "input", { type: "email" }),
+      formValue: secret,
+      formDefaultValue: "",
+      formState: "filled" as const,
+    };
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      supplementalNames: new Map([["main\u00002", secret]]),
+      identifierFallback: false,
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["email"],
+            },
+            {
+              nodeId: "email",
+              parentId: "root",
+              backendDOMNodeId: 2,
+              role: { type: "role", value: "textbox" },
+              value: { value: secret },
+            },
+          ],
+          [dom(1, null, "body"), input],
+        ),
+      ],
+    });
+
+    const field = scene.nodes.find((node) => node.backendNodeId === 2);
+    expect(field?.name).toBeUndefined();
+    const rendered = renderVom(scene, { redactValues: true });
+    expect(rendered.text).toContain("•••");
+    expect(JSON.stringify(rendered)).not.toContain(secret);
   });
 
   it("keeps uncertain single-branch wrappers flat", () => {
diff --git a/apps/extension/src/tools/vom/name-enrichment.ts b/apps/extension/src/tools/vom/name-enrichment.ts
index c94eaf2e..1f42ee3f 100644
--- a/apps/extension/src/tools/vom/name-enrichment.ts
+++ b/apps/extension/src/tools/vom/name-enrichment.ts
@@ -10,6 +10,7 @@ const MAX_TOOLTIP_PROBE_MS = 2_400;
 const TOOLTIP_SETTLE_MS = 250;
 const CACHE_TTL_MS = 5 * 60_000;
 const MAX_CACHE_ENTRIES = 500;
+const FORM_CONTROL_TAGS = new Set(["input", "select", "textarea"]);
 
 interface TooltipCacheEntry {
   name: string;
@@ -108,6 +109,7 @@ function candidates<T extends FrameOwnedAxNode>(
   for (const node of graph.nodes.values()) {
     if (
       node.vom.name ||
+      FORM_CONTROL_TAGS.has(node.dom?.tag.toLowerCase() ?? "") ||
       !node.referenceable ||
       node.backendNodeId === undefined ||
       !isVomReferenceNode({
diff --git a/apps/extension/src/tools/vom/semantic-graph/resolve.ts b/apps/extension/src/tools/vom/semantic-graph/resolve.ts
index 03281cbb..ad5b2cb2 100644
--- a/apps/extension/src/tools/vom/semantic-graph/resolve.ts
+++ b/apps/extension/src/tools/vom/semantic-graph/resolve.ts
@@ -399,7 +399,7 @@ function resolvedName(
     formControl ? precedingAxText(node, graph, indexes) : undefined,
     formControl ? precedingDomText(node, graph, indexes) : undefined,
     formControl ? clean(node.dom?.formPlaceholder ?? attrs.placeholder) : undefined,
-    !interactive || node.backendNodeId === undefined
+    formControl || !interactive || node.backendNodeId === undefined
       ? undefined
       : clean(supplementalNames.get(frameBackendKey(node.frameId, node.backendNodeId))),
     identifierFallback && interactive ? stableIdentifierName(attrs) : undefined,

From d1d3eb6a94379429e5698a2b804028bd55fb88a3 Mon Sep 17 00:00:00 2001
From: Ljy-0827 <liujunyao0827@gmail.com>
Date: Mon, 24 Aug 2026 14:31:35 +0800
Subject: [PATCH 4/5] fix(vom): bug fix

---
 .../src/tools/__tests__/observation.test.ts   | 92 +++++++++++++++++++
 apps/extension/src/tools/observation.ts       | 11 ++-
 .../src/tools/vom/__tests__/capture.test.ts   | 42 ++++++++-
 .../vom/__tests__/semantic-graph.test.ts      | 57 ++++++++++++
 apps/extension/src/tools/vom/capture.ts       | 23 ++++-
 .../src/tools/vom/semantic-graph/structure.ts | 20 ++++
 .../src/tools/vom/semantic-graph/types.ts     |  5 +-
 7 files changed, 244 insertions(+), 6 deletions(-)

diff --git a/apps/extension/src/tools/__tests__/observation.test.ts b/apps/extension/src/tools/__tests__/observation.test.ts
index a560f3e4..2e18a414 100644
--- a/apps/extension/src/tools/__tests__/observation.test.ts
+++ b/apps/extension/src/tools/__tests__/observation.test.ts
@@ -3155,6 +3155,98 @@ describe("handleSnapshot", () => {
     });
   });
 
+  it("decorates live observations with active controlled content", async () => {
+    const strings = [
+      "html",
+      "body",
+      "button",
+      "div",
+      "#text",
+      "role",
+      "tab",
+      "aria-selected",
+      "true",
+      "aria-controls",
+      "reviews-panel",
+      "id",
+      "static",
+      "auto",
+      "visible",
+      "1",
+      "A detailed review",
+    ];
+    const index = (value: string) => strings.indexOf(value);
+    const style = [index("static"), index("auto"), index("auto"), index("visible"), index("1")];
+    const snapshot = {
+      strings,
+      documents: [
+        {
+          nodes: {
+            parentIndex: [-1, 0, 1, 1, 3],
+            nodeName: [index("html"), index("body"), index("button"), index("div"), index("#text")],
+            backendNodeId: [10, 11, 12, 13, 14],
+            attributes: [
+              [],
+              [],
+              [
+                index("role"),
+                index("tab"),
+                index("aria-selected"),
+                index("true"),
+                index("aria-controls"),
+                index("reviews-panel"),
+              ],
+              [index("id"), index("reviews-panel")],
+              [],
+            ],
+            nodeValue: [-1, -1, -1, -1, index("A detailed review")],
+          },
+          layout: {
+            nodeIndex: [0, 1, 2, 3, 4],
+            styles: [style, style, style, style, style],
+            bounds: [
+              [0, 0, 1000, 800],
+              [0, 0, 1000, 800],
+              [20, 20, 120, 40],
+              [20, 80, 500, 200],
+              [20, 80, 200, 20],
+            ],
+            paintOrders: [0, 0, 1, 1, 1],
+          },
+        },
+      ],
+    };
+    const ax: CdpAxNode[] = [
+      {
+        nodeId: "root",
+        backendDOMNodeId: 11,
+        role: { type: "role", value: "RootWebArea" },
+        childIds: ["reviews"],
+      },
+      {
+        nodeId: "reviews",
+        parentId: "root",
+        backendDOMNodeId: 12,
+        role: { type: "role", value: "tab" },
+        name: { type: "computedString", value: "Reviews" },
+        properties: [
+          { name: "selected", value: { value: true } },
+          { name: "controls", value: { value: "reviews-panel" } },
+        ],
+      },
+    ];
+
+    const result = await captureVomObservation(
+      makeOverlayDeps(ax, snapshot, VP_METRICS).cdp,
+      4,
+      "https://example.com",
+    );
+
+    expect(result.text).toContain('@e1 tab "Reviews"');
+    expect(result.text).toContain("[§ active: Reviews]");
+    expect(result.text).toContain("A detailed review");
+  });
+
   it("does not leak form secrets through the record-safe observation payload", async () => {
     const secrets = {
       email: "user@example.com",
diff --git a/apps/extension/src/tools/observation.ts b/apps/extension/src/tools/observation.ts
index e7a7edd4..ec78d183 100644
--- a/apps/extension/src/tools/observation.ts
+++ b/apps/extension/src/tools/observation.ts
@@ -817,6 +817,14 @@ export function buildFrameVomScene(
     excludedBackendNodeIds: captured.excludedBackendNodeIds,
     supplementalNames: options.supplementalNames,
   });
+  return attachCapturedSceneAnnotations(scene, documents, captured);
+}
+
+function attachCapturedSceneAnnotations(
+  scene: VomScene,
+  documents: VomFrameDocument[],
+  captured: CapturedViewModel,
+): VomScene {
   const rootDocument = documents.find((document) => document.frameId === scene.rootFrameId);
   const signals = capturedOnlySignals(rootDocument?.domNodes ?? captured.nodes);
   const activeScopeBlocks = buildActiveScopeBlocks(scene.nodes, signals);
@@ -1055,7 +1063,8 @@ export async function captureVomObservation(
       resolveSemanticGraph(semanticGraph, { supplementalNames: tooltipNames }),
     ),
   );
-  const rendered = renderVom(scene, {
+  const decoratedScene = attachCapturedSceneAnnotations(scene, normalizedDocuments, captured);
+  const rendered = renderVom(decoratedScene, {
     maxDepth: options.maxDepth,
     maxTokens: options.maxTokens,
     redactValues: options.redactValues,
diff --git a/apps/extension/src/tools/vom/__tests__/capture.test.ts b/apps/extension/src/tools/vom/__tests__/capture.test.ts
index de38ca52..94633836 100644
--- a/apps/extension/src/tools/vom/__tests__/capture.test.ts
+++ b/apps/extension/src/tools/vom/__tests__/capture.test.ts
@@ -36,7 +36,7 @@ function fakeSnapshotReply() {
         },
         layout: {
           nodeIndex: [1, 2, 3],
-          // styles columns follow requested computedStyles order: [position, pointer-events]
+          // Legacy fixture: omitted style columns fall back to visible defaults.
           styles: [
             [i("static"), i("auto")],
             [i("fixed"), i("auto")],
@@ -682,6 +682,46 @@ describe("captureViewModel", () => {
     expect(nodes.find((n) => n.backendNodeId === 11)?.cursor).toBe("auto");
   });
 
+  it("captures painted visibility as DOM fallback evidence", async () => {
+    const S = ["html", "body", "button", "static", "auto", "visible", "hidden", "1", "0"];
+    const i = (value: string) => S.indexOf(value);
+    const snapshot = {
+      strings: S,
+      documents: [
+        {
+          nodes: {
+            parentIndex: [-1, 0, 1, 1, 1],
+            nodeName: [i("html"), i("body"), i("button"), i("button"), i("button")],
+            backendNodeId: [10, 11, 12, 13, 14],
+            attributes: [[], [], [], [], []],
+          },
+          layout: {
+            nodeIndex: [1, 2, 3, 4],
+            styles: [
+              [i("static"), i("auto"), i("auto"), i("visible"), i("1")],
+              [i("static"), i("auto"), i("auto"), i("visible"), i("1")],
+              [i("static"), i("auto"), i("auto"), i("hidden"), i("1")],
+              [i("static"), i("auto"), i("auto"), i("visible"), i("0")],
+            ],
+            bounds: [
+              [0, 0, 1000, 800],
+              [10, 10, 100, 30],
+              [10, 50, 100, 30],
+              [10, 90, 100, 30],
+            ],
+            paintOrders: [0, 1, 2, 3],
+          },
+        },
+      ],
+    };
+
+    const { nodes } = await captureViewModel(makeCdp(snapshot), 4);
+
+    expect(nodes.find((node) => node.backendNodeId === 12)?.rendered).toBe(true);
+    expect(nodes.find((node) => node.backendNodeId === 13)?.rendered).toBe(false);
+    expect(nodes.find((node) => node.backendNodeId === 14)?.rendered).toBe(false);
+  });
+
   it("subtracts scroll offset to make rects viewport-relative", async () => {
     const cdp = {
       send: vi.fn(async (_t: number, method: string) => {
diff --git a/apps/extension/src/tools/vom/__tests__/semantic-graph.test.ts b/apps/extension/src/tools/vom/__tests__/semantic-graph.test.ts
index d4dda001..f26883a7 100644
--- a/apps/extension/src/tools/vom/__tests__/semantic-graph.test.ts
+++ b/apps/extension/src/tools/vom/__tests__/semantic-graph.test.ts
@@ -271,6 +271,63 @@ describe("semantic VOM graph", () => {
     ]);
   });
 
+  it("requires render evidence before promoting DOM fallback semantics", () => {
+    const hiddenOwner = {
+      ...dom(10, 1, "iframe", { hidden: "" }),
+      rect: null,
+      localRect: null,
+      rendered: false,
+    };
+    const hiddenButton = {
+      ...dom(2, 1, "button", { "aria-label": "Hidden action" }),
+      rendered: false,
+    };
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+            },
+          ],
+          [dom(1, null, "body"), hiddenButton, hiddenOwner],
+        ),
+        document("hidden-frame", [], [dom(20, null, "button", {}, "Frame action")], {
+          parentFrameId: "main",
+          ownerBackendNodeId: 10,
+        }),
+      ],
+    });
+
+    expect(scene.nodes.some((node) => node.backendNodeId === 2)).toBe(false);
+    expect(scene.nodes.some((node) => node.backendNodeId === 10)).toBe(false);
+    expect(scene.nodes.some((node) => node.frameId === "hidden-frame")).toBe(false);
+    expect(renderVom(scene).refs).toEqual([]);
+  });
+
+  it("retains rendered DOM fallback controls when AX semantics are unavailable", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [],
+          [dom(1, null, "body"), { ...dom(2, 1, "button", {}, "Save"), rendered: true }],
+        ),
+      ],
+    });
+
+    expect(renderVom(scene).refs).toEqual([
+      expect.objectContaining({ backendNodeId: 2, role: "button", name: "Save" }),
+    ]);
+  });
+
   it("lets explicit DOM structure override ignored AX metadata", () => {
     const scene = buildSemanticVomScene({
       viewport: { width: 800, height: 600 },
diff --git a/apps/extension/src/tools/vom/capture.ts b/apps/extension/src/tools/vom/capture.ts
index c221d8f2..1db0e298 100644
--- a/apps/extension/src/tools/vom/capture.ts
+++ b/apps/extension/src/tools/vom/capture.ts
@@ -1,8 +1,8 @@
 // CDP capture adapter: DOMSnapshot.captureSnapshot + Page.getLayoutMetrics
 // → CapturedNode[] + Viewport. This is the ONLY VOM module that touches
 // raw CDP. The captureSnapshot reply is columnar (parallel arrays + a
-// shared string table); we request exactly three computed styles so the
-// `styles` columns are [position, pointer-events, cursor] in that order.
+// shared string table); requested computed styles are decoded through
+// STYLE_COL so capture and visibility policy share one explicit contract.
 
 import type { Rect, Viewport } from "@browser-skill/vom";
 import { evaluateHoverTrigger } from "@/lib/hover-trigger-policy";
@@ -11,7 +11,7 @@ import { childFrameProjection, type GeometryProjection, projectRectToViewport }
 import type { CdpRunner } from "../shared";
 import { clearHover, waitForHover } from "./hover-perception";
 
-const REQUESTED_STYLES = ["position", "pointer-events", "cursor"] as const;
+const REQUESTED_STYLES = ["position", "pointer-events", "cursor", "visibility", "opacity"] as const;
 const STYLE_COL = Object.fromEntries(
   REQUESTED_STYLES.map((name, index) => [name, index]),
 ) as Record<(typeof REQUESTED_STYLES)[number], number>;
@@ -39,6 +39,12 @@ export interface CapturedNode {
    * `textContent`: the live parser always sets it, hand-built fixtures may not.
    */
   cursor?: string;
+  /**
+   * Whether the live DOM snapshot provides a painted, non-hidden box for this
+   * node. Semantic resolution uses this only for DOM fallback nodes; AX-backed
+   * nodes remain authoritative even when they are outside the viewport.
+   */
+  rendered?: boolean;
   textContent?: string;
   formState?: "empty" | "filled" | "default";
   formValue?: string;
@@ -788,6 +794,8 @@ function parseDocumentNodes(
   const posCol = STYLE_COL.position;
   const peCol = STYLE_COL["pointer-events"];
   const cursorCol = STYLE_COL.cursor;
+  const visibilityCol = STYLE_COL.visibility;
+  const opacityCol = STYLE_COL.opacity;
   const inputValues = sparseIndexMap(dn.inputValue);
   const textValues = sparseIndexMap(dn.textValue);
   const checkedInputs = new Set(dn.inputChecked?.index ?? []);
@@ -832,6 +840,7 @@ function parseDocumentNodes(
     let position = "static";
     let pointerEvents = "auto";
     let cursor = "auto";
+    let rendered = false;
     const li = layoutByNode.get(n);
     if (li !== undefined) {
       const b = dl?.bounds?.[li];
@@ -852,6 +861,13 @@ function parseDocumentNodes(
       position = str(strings, styleRow[posCol]) || "static";
       pointerEvents = str(strings, styleRow[peCol]) || "auto";
       cursor = str(strings, styleRow[cursorCol]) || "auto";
+      const visibility = str(strings, styleRow[visibilityCol]) || "visible";
+      const opacity = str(strings, styleRow[opacityCol]) || "1";
+      rendered =
+        localRect !== null &&
+        visibility !== "hidden" &&
+        visibility !== "collapse" &&
+        (Number.parseFloat(opacity) || 0) > 0;
     }
 
     // Skip non-element nodes (#text, #cdata-section, etc.) — they carry no
@@ -887,6 +903,7 @@ function parseDocumentNodes(
       position,
       pointerEvents,
       cursor,
+      rendered,
       textContent,
       ...(formValue !== undefined ? { formValue } : {}),
       ...(tag === "input" || tag === "textarea"
diff --git a/apps/extension/src/tools/vom/semantic-graph/structure.ts b/apps/extension/src/tools/vom/semantic-graph/structure.ts
index 9b5b1a6a..72df95f9 100644
--- a/apps/extension/src/tools/vom/semantic-graph/structure.ts
+++ b/apps/extension/src/tools/vom/semantic-graph/structure.ts
@@ -49,6 +49,23 @@ function explicitStructural(node: ResolvedSemanticNode): boolean {
   );
 }
 
+function hasUsableAxSemantics(node: ResolvedSemanticNode): boolean {
+  return node.ax !== undefined && node.ax.ignored !== true;
+}
+
+function isRenderedDomFallback(node: ResolvedSemanticNode): boolean {
+  if (!node.dom) return false;
+  const attrs = node.dom.attrs;
+  if (
+    Object.prototype.hasOwnProperty.call(attrs, "hidden") ||
+    Object.prototype.hasOwnProperty.call(attrs, "inert") ||
+    (attrs["aria-hidden"] ?? "").toLowerCase() === "true"
+  ) {
+    return false;
+  }
+  return node.dom.rendered ?? (node.dom.localRect != null || node.dom.rect != null);
+}
+
 function initialParentId(
   graph: ResolvedSemanticGraph,
   node: ResolvedSemanticNode,
@@ -142,6 +159,9 @@ function baseDecision(
 ): StructureDecision {
   if (node.excluded) return { kind: "excluded", reason: "excluded" };
   if (redundant.has(node.id)) return { kind: "excluded", reason: "redundant-source" };
+  if (!hasUsableAxSemantics(node) && !isRenderedDomFallback(node)) {
+    return { kind: "excluded", reason: "non-rendered-dom-fallback" };
+  }
   if (frameOwnerIds.has(node.id)) return { kind: "keep", reason: "frame-owner" };
   if (node.frameId !== graph.rootFrameId && ROOT_ROLES.has(output.role?.toLowerCase() ?? "")) {
     return { kind: "transparent", reason: "child-document-root" };
diff --git a/apps/extension/src/tools/vom/semantic-graph/types.ts b/apps/extension/src/tools/vom/semantic-graph/types.ts
index bd26d768..b71b458b 100644
--- a/apps/extension/src/tools/vom/semantic-graph/types.ts
+++ b/apps/extension/src/tools/vom/semantic-graph/types.ts
@@ -65,7 +65,10 @@ export type StructureDecision =
   | { kind: "keep"; reason: "semantic" | "frame-owner" }
   | { kind: "inferred-group"; reason: "independent-interaction-branches" }
   | { kind: "transparent"; reason: "wrapper" | "child-document-root" | "ax-ignored" }
-  | { kind: "excluded"; reason: "excluded" | "redundant-source" };
+  | {
+      kind: "excluded";
+      reason: "excluded" | "redundant-source" | "non-rendered-dom-fallback";
+    };
 
 export interface StructuredSemanticNode extends ResolvedSemanticNode {
   structure: StructureDecision;

From 0d7f97633594da72aca9fc6175ed1737a0dba366 Mon Sep 17 00:00:00 2001
From: Ljy-0827 <liujunyao0827@gmail.com>
Date: Mon, 24 Aug 2026 14:52:16 +0800
Subject: [PATCH 5/5] fix(vom): fix repeat names

---
 .../vom/__tests__/semantic-graph.test.ts      | 125 ++++++++++++++++++
 .../src/tools/vom/semantic-graph/resolve.ts   |  16 ++-
 2 files changed, 134 insertions(+), 7 deletions(-)

diff --git a/apps/extension/src/tools/vom/__tests__/semantic-graph.test.ts b/apps/extension/src/tools/vom/__tests__/semantic-graph.test.ts
index f26883a7..e3ec8457 100644
--- a/apps/extension/src/tools/vom/__tests__/semantic-graph.test.ts
+++ b/apps/extension/src/tools/vom/__tests__/semantic-graph.test.ts
@@ -141,6 +141,104 @@ describe("semantic VOM graph", () => {
     ]);
   });
 
+  it("aggregates AX text at the semantic text frontier", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["covered", "inline-only", "repeated", "labelled"],
+            },
+            {
+              nodeId: "covered",
+              parentId: "root",
+              backendDOMNodeId: 2,
+              role: { type: "role", value: "paragraph" },
+              childIds: ["covered-static"],
+            },
+            {
+              nodeId: "covered-static",
+              parentId: "covered",
+              role: { type: "role", value: "StaticText" },
+              name: { type: "computedString", value: "Covered text" },
+              childIds: ["covered-inline"],
+            },
+            {
+              nodeId: "covered-inline",
+              parentId: "covered-static",
+              role: { type: "role", value: "InlineTextBox" },
+              name: { type: "computedString", value: "Covered text" },
+            },
+            {
+              nodeId: "inline-only",
+              parentId: "root",
+              backendDOMNodeId: 3,
+              role: { type: "role", value: "paragraph" },
+              childIds: ["inline-leaf"],
+            },
+            {
+              nodeId: "inline-leaf",
+              parentId: "inline-only",
+              role: { type: "role", value: "InlineTextBox" },
+              name: { type: "computedString", value: "Inline fallback" },
+            },
+            {
+              nodeId: "repeated",
+              parentId: "root",
+              backendDOMNodeId: 4,
+              role: { type: "role", value: "paragraph" },
+              childIds: ["first-go", "second-go"],
+            },
+            {
+              nodeId: "first-go",
+              parentId: "repeated",
+              role: { type: "role", value: "StaticText" },
+              name: { type: "computedString", value: "Go" },
+            },
+            {
+              nodeId: "second-go",
+              parentId: "repeated",
+              role: { type: "role", value: "StaticText" },
+              name: { type: "computedString", value: "Go" },
+            },
+            {
+              nodeId: "labelled",
+              parentId: "root",
+              backendDOMNodeId: 5,
+              role: { type: "role", value: "button" },
+              childIds: ["visible-label"],
+            },
+            {
+              nodeId: "visible-label",
+              parentId: "labelled",
+              role: { type: "role", value: "StaticText" },
+              name: { type: "computedString", value: "Visible text" },
+            },
+          ],
+          [
+            dom(1, null, "body"),
+            dom(2, 1, "p"),
+            dom(3, 1, "p"),
+            dom(4, 1, "p"),
+            dom(5, 1, "button", { "aria-label": "Explicit action" }),
+          ],
+        ),
+      ],
+    });
+
+    expect(scene.nodes.find((node) => node.backendNodeId === 2)?.name).toBe("Covered text");
+    expect(scene.nodes.find((node) => node.backendNodeId === 3)?.name).toBe("Inline fallback");
+    expect(scene.nodes.find((node) => node.backendNodeId === 4)?.name).toBe("Go Go");
+    expect(scene.nodes.find((node) => node.backendNodeId === 5)?.name).toBe("Explicit action");
+    expect(renderVom(scene).text).not.toContain("Covered text Covered text");
+  });
+
   it("uses stable identifiers only as a final name fallback", () => {
     const base = document(
       "main",
@@ -235,6 +333,19 @@ describe("semantic VOM graph", () => {
               nodeId: "button-a",
               backendDOMNodeId: 5,
               role: { type: "role", value: "button" },
+              childIds: ["text-a"],
+            },
+            {
+              nodeId: "text-a",
+              parentId: "button-a",
+              role: { type: "role", value: "StaticText" },
+              name: { type: "computedString", value: "Accept" },
+              childIds: ["inline-a"],
+            },
+            {
+              nodeId: "inline-a",
+              parentId: "text-a",
+              role: { type: "role", value: "InlineTextBox" },
               name: { type: "computedString", value: "Accept" },
             },
           ],
@@ -248,6 +359,19 @@ describe("semantic VOM graph", () => {
               nodeId: "button-b",
               backendDOMNodeId: 5,
               role: { type: "role", value: "button" },
+              childIds: ["text-b"],
+            },
+            {
+              nodeId: "text-b",
+              parentId: "button-b",
+              role: { type: "role", value: "StaticText" },
+              name: { type: "computedString", value: "Decline" },
+              childIds: ["inline-b"],
+            },
+            {
+              nodeId: "inline-b",
+              parentId: "text-b",
+              role: { type: "role", value: "InlineTextBox" },
               name: { type: "computedString", value: "Decline" },
             },
           ],
@@ -264,6 +388,7 @@ describe("semantic VOM graph", () => {
         .map((node) => [node.backendNodeId, node.id]),
     );
     expect(frameButtons.map((node) => node.frameId)).toEqual(["frame-a", "frame-b"]);
+    expect(frameButtons.map((node) => node.name)).toEqual(["Accept", "Decline"]);
     expect(frameButtons.map((node) => node.parentId)).toEqual([owners.get(10), owners.get(20)]);
     expect(renderVom(scene).refs.map((ref) => [ref.frameId, ref.backendNodeId])).toEqual([
       ["frame-a", 5],
diff --git a/apps/extension/src/tools/vom/semantic-graph/resolve.ts b/apps/extension/src/tools/vom/semantic-graph/resolve.ts
index ad5b2cb2..3e2c2f35 100644
--- a/apps/extension/src/tools/vom/semantic-graph/resolve.ts
+++ b/apps/extension/src/tools/vom/semantic-graph/resolve.ts
@@ -240,13 +240,18 @@ function buildIndexes(graph: SemanticGraph): ResolveIndexes {
     if (axTextMemo.has(nodeId)) return axTextMemo.get(nodeId);
     if (resolvingAxText.has(nodeId)) return undefined;
     resolvingAxText.add(nodeId);
+    const complete = (value: string | undefined): string | undefined => {
+      resolvingAxText.delete(nodeId);
+      axTextMemo.set(nodeId, value);
+      return value;
+    };
     const node = graph.nodes.get(nodeId);
     const role = normalizeRole(axValue(node?.ax?.role)) ?? "";
-    const parts: string[] = [];
     if (TEXT_AX_ROLES.has(role)) {
       const own = clean(axValue(node?.ax?.name) ?? axValue(node?.ax?.value));
-      if (own) parts.push(own);
+      if (own) return complete(own);
     }
+    const parts: string[] = [];
     for (const childId of axChildren.get(nodeId) ?? []) {
       const child = graph.nodes.get(childId);
       const childRole = normalizeRole(axValue(child?.ax?.role)) ?? "";
@@ -255,10 +260,7 @@ function buildIndexes(graph: SemanticGraph): ResolveIndexes {
       if (childText) parts.push(childText);
       if (parts.join(" ").length >= 240) break;
     }
-    resolvingAxText.delete(nodeId);
-    const result = clean(parts.join(" ").slice(0, 240));
-    axTextMemo.set(nodeId, result);
-    return result;
+    return complete(clean(parts.join(" ").slice(0, 240)));
   };
 
   const nativeMemo = new Map<SemanticNodeId, boolean>();
@@ -389,12 +391,12 @@ function resolvedName(
     NATIVE_CONTROL_TAGS.has(node.dom?.tag.toLowerCase() ?? "");
   const candidates = [
     node.ax?.ignored === true ? undefined : axValue(node.ax?.name),
-    node.ax?.ignored === true ? undefined : indexes.axText(node.id),
     ariaLabelledText(node, indexes),
     clean(attrs["aria-label"]),
     nativeLabelText(node, graph, indexes),
     clean(attrs.title),
     clean(attrs.alt),
+    node.ax?.ignored === true ? undefined : indexes.axText(node.id),
     descendantText,
     formControl ? precedingAxText(node, graph, indexes) : undefined,
     formControl ? precedingDomText(node, graph, indexes) : undefined,