From 913616f5c4c9574329557955d2320ceb7b2b3fad Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Mon, 28 Sep 2026 22:07:11 +0530
Subject: [PATCH 1/3] ci(release): install Chrome for the browser suite, as
 ci.yml does

The release job ran pnpm test against whatever Chrome the runner had
preinstalled, and failed once in the browser suite's setup hook. Use the
same setup-chrome step and REINS_TEST_CHROME env as ci.yml.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/release.yml | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index c4afa59..cd775c2 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -26,10 +26,16 @@ jobs:
     steps:
       - uses: actions/checkout@v7.0.0
       - uses: jdx/mise-action@v4.2.0
+      # Same Chrome as ci.yml, so the extension's real-browser suite runs the
+      # same way here as it did on the PR.
+      - uses: browser-actions/setup-chrome@v2.2.0
+        id: chrome
       - run: pnpm install --frozen-lockfile
       - run: pnpm lint
       - run: pnpm typecheck
       - run: pnpm test
+        env:
+          REINS_TEST_CHROME: ${{ steps.chrome.outputs.chrome-path }}
       - run: pnpm build
 
       - name: Version or publish (changesets)

From 309d51b5447dd1035debd8b5313249d25c1dd7c1 Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Mon, 28 Sep 2026 22:16:34 +0530
Subject: [PATCH 2/3] fix(extension): step commands see shadow DOM and custom
 controls

reins snapshot walked document.querySelectorAll only, so controls in web
components (MDN's search button, openlibrary's Sort by menu) never got a
ref. It now reuses reins do's page helpers, moved to page-dom.ts: it walks
open shadow roots and names elements through aria-labelledby, labels,
shadow roots and slots. Refs resolve through open shadow roots for click,
type, fill, hover, select, scroll, text, wait and upload. --selector stays
light-DOM CSS.

"element has zero size" on the wizard's Team card and the settings
switches came from stale refs: a snapshot never cleared the previous
one's data-reins-ref tags, so an element hidden since (the wizard step or
tab panel just left) kept e8 while the new snapshot gave e8 to the switch,
and querySelector found the hidden one first. Each snapshot now clears the
old tags before tagging.

actionPoint also presses a stand-in for a target with no box: a 0x0 or
display:none native radio/checkbox is pressed through its visible label or
the custom radio/switch/checkbox/option it sits in, and a display:contents
element through its first rendered child. Disabled, covered and moving
checks apply to the element pressed, and disabled to the original too.
The hit test now walks the flat tree (assignedSlot), so a caption slotted
through two shadow roots counts as inside its button.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/step-commands-shadow-dom.md        |   6 +
 packages/extension/src/lib/actionability.ts   |  70 ++++++-
 packages/extension/src/lib/cdp.test.ts        |  41 +++-
 packages/extension/src/lib/cdp.ts             |  67 ++++---
 packages/extension/src/lib/jev-snapshot.ts    | 139 +-------------
 packages/extension/src/lib/jev.ts             |   7 +-
 .../extension/src/lib/page-actions.test.ts    |  23 +++
 packages/extension/src/lib/page-actions.ts    |  34 +++-
 packages/extension/src/lib/page-dom.ts        | 177 ++++++++++++++++++
 .../extension/src/lib/pointer.browser.test.ts | 127 ++++++++++++-
 packages/extension/src/lib/snapshot.ts        |  41 ++++
 packages/web/src/routes/docs/commands.tsx     |   3 +-
 skills/reins/SKILL.md                         |   9 +-
 13 files changed, 553 insertions(+), 191 deletions(-)
 create mode 100644 .changeset/step-commands-shadow-dom.md
 create mode 100644 packages/extension/src/lib/page-dom.ts
 create mode 100644 packages/extension/src/lib/snapshot.ts

diff --git a/.changeset/step-commands-shadow-dom.md b/.changeset/step-commands-shadow-dom.md
new file mode 100644
index 0000000..6e2a5b4
--- /dev/null
+++ b/.changeset/step-commands-shadow-dom.md
@@ -0,0 +1,6 @@
+---
+"@karnstack/reins": patch
+"@reins/extension": patch
+---
+
+Step commands see web components and custom controls. `reins snapshot` now lists elements inside open shadow roots (a site's search button, a `Sort by` menu built as a web component) and names them the way `reins do` does — through `aria-labelledby`, labels, shadow roots and slots — and `--ref` reaches them in `click`, `type`, `fill`, `hover`, `select` and the rest. `--selector` stays light-DOM CSS. Each snapshot now re-issues its refs, so a ref no longer lands on an element hidden since the previous snapshot (the "element has zero size" failures on wizards and tab panels). A click on a control with no box of its own — a native radio or checkbox shrunk to 0×0 under a styled card, or a `display: contents` wrapper — presses its visible label, custom radio/switch it sits in, or first rendered child instead.
diff --git a/packages/extension/src/lib/actionability.ts b/packages/extension/src/lib/actionability.ts
index 26fcf44..45ba446 100644
--- a/packages/extension/src/lib/actionability.ts
+++ b/packages/extension/src/lib/actionability.ts
@@ -35,7 +35,16 @@ export type ProbeResult = (
  * reaches the element; read it back with `readProbe`.
  *
  * With `node`, the target is the Jev node cache entry (`reins do` observed it
- * by id); `selector` then only names it in messages.
+ * by id); with `locate`, whatever that function returns (a ref looked up
+ * through shadow roots). `selector` then only names it in messages.
+ *
+ * A target with no box of its own is pressed where it shows: a native radio
+ * or checkbox shrunk to 0×0 (or display:none) under a styled card is pressed
+ * through its visible <label> (which forwards the click to it) or the custom
+ * radio/switch/checkbox/option it sits in; a `display: contents` wrapper
+ * through its first rendered child. Every check — disabled, covered, moving —
+ * then applies to the element actually pressed, and "disabled" to the
+ * original target as well.
  *
  * A click target inside an `<a href target=_blank>` (or any link whose
  * effective target, including a `<base target>`, names no frame of this page)
@@ -54,17 +63,61 @@ export async function actionPoint(
   timeoutMs: number,
   forClick: boolean,
   node: number | null = null,
+  locate: (() => Element | null) | null = null,
 ): Promise<ActionPoint> {
   // A Jev node id points at the exact element reins do observed; otherwise
-  // the CSS selector is re-queried (frameworks may swap nodes while we wait).
+  // the target is re-queried (frameworks may swap nodes while we wait).
   const find = (): Element | null => {
-    if (node === null) return document.querySelector(selector);
+    if (node === null) {
+      const el = locate ? locate() : document.querySelector(selector);
+      return el?.isConnected ? el : null;
+    }
     const cache = (
       window as unknown as Record<symbol, { nodes?: Map<number, Element> } | undefined>
     )[Symbol.for("reins.jev")];
     const el = cache?.nodes?.get(node);
     return el?.isConnected ? el : null;
   };
+  // The parent as rendered (the flat tree, the path events take): slotted
+  // content's parent is its slot, a shadow root's is its host.
+  const up = (n: Node): Node | null =>
+    (n instanceof Element && n.assignedSlot) ||
+    n.parentNode ||
+    (n instanceof ShadowRoot ? n.host : null);
+  const sized = (e: Element) => {
+    const r = e.getBoundingClientRect();
+    return r.width > 0 && r.height > 0;
+  };
+  // The first box a display:contents element renders, looking through
+  // nested display:contents children, its shadow root and slots.
+  const firstBox = (e: Element): Element | null => {
+    const kids = e.shadowRoot
+      ? [...e.shadowRoot.children]
+      : e instanceof HTMLSlotElement
+        ? e.assignedElements({ flatten: true })
+        : [...e.children];
+    for (const k of kids) {
+      if (sized(k)) return k;
+      if (getComputedStyle(k).display === "contents") {
+        const inner = firstBox(k);
+        if (inner) return inner;
+      }
+    }
+    return null;
+  };
+  const CUSTOM =
+    '[role="radio"],[role="switch"],[role="checkbox"],[role="option"],[role="menuitemradio"],[role="menuitemcheckbox"]';
+  // Where to press for `t`: itself when it has a box, else what shows for it.
+  const standIn = (t: Element): Element => {
+    if (sized(t)) return t;
+    if (getComputedStyle(t).display === "contents") return firstBox(t) ?? t;
+    for (const l of (t as HTMLInputElement).labels ?? []) if (sized(l)) return l;
+    for (let p = up(t); p; p = up(p)) {
+      if (p instanceof Element && p.matches(CUSTOM)) return sized(p) ? p : t;
+    }
+    return t;
+  };
+  const disabled = (e: Element) => e.matches(":disabled") || !!e.closest('[aria-disabled="true"]');
   const describe = (n: Element | null): string => {
     if (!n) return "nothing (the point is outside the viewport)";
     let s = n.tagName.toLowerCase();
@@ -158,8 +211,9 @@ export async function actionPoint(
   let reason = "";
   for (let first = true; ; first = false) {
     // Re-query every attempt: frameworks may swap the node while we wait.
-    const el = find();
-    if (!el) {
+    const found = find();
+    const el = found && standIn(found);
+    if (!found || !el) {
       if (first) return { error: "notfound" };
       reason = "element was removed from the page";
     } else {
@@ -170,7 +224,7 @@ export async function actionPoint(
       const { r, still } = await settle(el);
       if (r.width === 0 || r.height === 0) {
         reason = "element has zero size (hidden?)";
-      } else if (forClick && (el.matches(":disabled") || el.closest('[aria-disabled="true"]'))) {
+      } else if (forClick && (disabled(el) || disabled(found))) {
         reason = "element is disabled";
       } else {
         const x = r.x + r.width / 2;
@@ -182,7 +236,7 @@ export async function actionPoint(
           hit = inner;
         }
         let n: Node | null = hit;
-        while (n && n !== el) n = n.parentNode ?? (n instanceof ShadowRoot ? n.host : null);
+        while (n && n !== el) n = up(n);
         // Slotted content: when the top-most box at the point is light-DOM
         // content a host slots into `el` (a web component's button whose
         // caption arrives through <slot>), hit-testing retargets it to the
@@ -214,7 +268,7 @@ export async function actionPoint(
               const now = find();
               const path = e.composedPath();
               state.result =
-                path.includes(el) || (now !== null && path.includes(now))
+                path.includes(el) || (now !== null && path.includes(standIn(now)))
                   ? { state: "hit" }
                   : { state: "missed", by: describe(at instanceof Element ? at : null) };
             };
diff --git a/packages/extension/src/lib/cdp.test.ts b/packages/extension/src/lib/cdp.test.ts
index 2047bd1..cddb7cb 100644
--- a/packages/extension/src/lib/cdp.test.ts
+++ b/packages/extension/src/lib/cdp.test.ts
@@ -9,6 +9,7 @@ import {
   cdpOpenTab,
   cdpType,
   initDebugSessionListeners,
+  targetExpr,
   withDebugger,
 } from "./cdp.js";
 
@@ -383,7 +384,45 @@ describe("actionablePoint for a Jev node", () => {
     const expr = (
       sendCommand.mock.calls[0] as unknown as [unknown, string, { expression: string }]
     )[2].expression;
-    expect(expr).toMatch(/\("node 12", 500, true, 12\)$/);
+    expect(expr).toMatch(/\("node 12", 500, true, 12, null\)$/);
+  });
+
+  it("passes a locator for a ref, which looks through open shadow roots", async () => {
+    const sendCommand = vi.fn(async () => ({ result: { value: { x: 5, y: 6 } } }));
+    vi.stubGlobal("chrome", {
+      debugger: {
+        attach: vi.fn(),
+        detach: vi.fn(),
+        onDetach: { addListener: () => {} },
+        sendCommand,
+      },
+    });
+    await actionablePoint(7, '[data-reins-ref="e3"]', "click", true, {
+      locate: targetExpr("e3"),
+    });
+    const expr = (
+      sendCommand.mock.calls[0] as unknown as [unknown, string, { expression: string }]
+    )[2].expression;
+    expect(expr).toContain(", null, () => (function findRef(ref) {");
+    expect(expr).toMatch(/\)\("e3"\)\)$/);
+  });
+});
+
+describe("targetExpr", () => {
+  it("a selector stays plain light-DOM CSS", () => {
+    expect(targetExpr("e1", "#go")).toBe('document.querySelector("#go")');
+  });
+
+  it("a ref is found by walking open shadow roots", () => {
+    const expr = targetExpr("e1");
+    expect(expr).toMatch(/^\(function findRef\(ref\) \{/);
+    expect(expr).toContain("shadowRoot");
+    expect(expr).toContain("data-reins-ref");
+    expect(expr).toMatch(/\("e1"\)$/);
+  });
+
+  it("needs one or the other", () => {
+    expect(() => targetExpr()).toThrow("requires a ref or selector");
   });
 });
 
diff --git a/packages/extension/src/lib/cdp.ts b/packages/extension/src/lib/cdp.ts
index d837667..209258a 100644
--- a/packages/extension/src/lib/cdp.ts
+++ b/packages/extension/src/lib/cdp.ts
@@ -13,6 +13,8 @@ import type {
 import { actionPoint, type ProbeResult, readProbe } from "./actionability.js";
 import { autofillGuard } from "./autofill-guard.js";
 import { isMonitored } from "./monitor.js";
+import { findRef, pageDom } from "./page-dom.js";
+import { type StepSnapshot, stepSnapshot } from "./snapshot.js";
 
 const PROTOCOL = "1.3";
 
@@ -293,45 +295,37 @@ export async function cdpNavigate(params: NavigateParams): Promise<{ url: string
   });
 }
 
-/** Tag interactive/labelled elements with data-reins-ref and return a compact tree + refs. */
-const SNAPSHOT_EXPR = `(() => {
-  const refs = [];
-  let n = 0;
-  const sel = "a,button,input,textarea,select,[role],h1,h2,h3,[contenteditable=true]";
-  for (const el of document.querySelectorAll(sel)) {
-    if (!(el instanceof HTMLElement) || el.offsetParent === null) continue;
-    const ref = "e" + (++n);
-    el.setAttribute("data-reins-ref", ref);
-    const role = el.getAttribute("role") || el.tagName.toLowerCase();
-    const name = (el.getAttribute("aria-label") || el.textContent || el.getAttribute("placeholder") || "").trim().slice(0, 80);
-    refs.push({ ref, role, name });
-  }
-  const text = refs.map(r => r.ref + ": " + r.role + " " + JSON.stringify(r.name)).join("\\n");
-  return { content: text, refs };
-})()`;
-
-export async function cdpSnapshot(
-  params: SnapshotParams,
-): Promise<{ content: string; refs: Array<{ ref: string; role?: string; name?: string }> }> {
+export async function cdpSnapshot(params: SnapshotParams): Promise<StepSnapshot> {
   const tabId = await resolveTabId(params.tabId);
   return withDebugger(tabId, async () => {
-    const { result } = await send<{
-      result: {
-        value: { content: string; refs: Array<{ ref: string; role?: string; name?: string }> };
-      };
-    }>(tabId, "Runtime.evaluate", { expression: SNAPSHOT_EXPR, returnByValue: true });
+    const { result } = await send<{ result: { value: StepSnapshot } }>(tabId, "Runtime.evaluate", {
+      expression: `(${stepSnapshot})(${pageDom})`,
+      returnByValue: true,
+    });
     const value = result.value;
     const content = params.maxChars ? value.content.slice(0, params.maxChars) : value.content;
     return { content, refs: value.refs };
   });
 }
 
+/** How a command's target is named in its messages. */
 export function selectorFor(ref?: string, selector?: string): string {
   if (selector) return selector;
   if (ref) return `[data-reins-ref="${ref}"]`;
   throw new Error("requires a ref or selector");
 }
 
+/**
+ * A page expression evaluating to the command's target, or null. A selector
+ * is plain CSS on the light DOM (`document.querySelector`); a ref is found
+ * through open shadow roots, where `reins snapshot` tags elements too.
+ */
+export function targetExpr(ref?: string, selector?: string): string {
+  if (selector) return `document.querySelector(${JSON.stringify(selector)})`;
+  if (ref) return `(${findRef})(${JSON.stringify(ref)})`;
+  throw new Error("requires a ref or selector");
+}
+
 /** How long click/hover wait for their target to become actionable. */
 const ACTION_TIMEOUT_MS = 5000;
 
@@ -361,20 +355,22 @@ export async function ensureVisible(tabId: number): Promise<void> {
 
 /**
  * Resolve a point where trusted pointer input will land on the element.
- * `opts.node` targets a Jev node id instead of the selector (which then only
- * names the element in errors); `opts.timeoutMs` overrides the default wait.
+ * `opts.node` targets a Jev node id, and `opts.locate` a page expression
+ * (`targetExpr`), instead of the selector — which then only names the
+ * element in errors; `opts.timeoutMs` overrides the default wait.
  */
 export async function actionablePoint(
   tabId: number,
   css: string,
   action: string,
   forClick: boolean,
-  opts: { node?: number; timeoutMs?: number } = {},
+  opts: { node?: number; locate?: string; timeoutMs?: number } = {},
 ): Promise<{ x: number; y: number }> {
+  const locate = opts.locate === undefined ? "null" : `() => ${opts.locate}`;
   const { result } = await send<{
     result: { value: { x: number; y: number } | { error: string } };
   }>(tabId, "Runtime.evaluate", {
-    expression: `(${actionPoint})(${JSON.stringify(css)}, ${opts.timeoutMs ?? ACTION_TIMEOUT_MS}, ${forClick}, ${opts.node ?? null})`,
+    expression: `(${actionPoint})(${JSON.stringify(css)}, ${opts.timeoutMs ?? ACTION_TIMEOUT_MS}, ${forClick}, ${opts.node ?? null}, ${locate})`,
     returnByValue: true,
     awaitPromise: true,
   });
@@ -468,7 +464,9 @@ export async function cdpClick(params: ClickParams): Promise<ClickResult> {
   const clickCount = params.clickCount ?? 1;
   return drivePage(tabId, async () => {
     await ensureVisible(tabId);
-    const { x, y } = await actionablePoint(tabId, css, "click", true);
+    const { x, y } = await actionablePoint(tabId, css, "click", true, {
+      locate: targetExpr(params.ref, params.selector),
+    });
     const { newTabUrl } = await pressAt(tabId, x, y, css, button, clickCount);
     if (newTabUrl === undefined) return { ok: true };
     // The user sees the new tab as after a normal click, without Chrome
@@ -484,7 +482,7 @@ export async function cdpType(params: TypeParams): Promise<{ ok: true }> {
   return drivePage(tabId, async () => {
     await ensureVisible(tabId);
     const { result } = await send<{ result: { value: boolean } }>(tabId, "Runtime.evaluate", {
-      expression: `(() => { const el = document.querySelector(${JSON.stringify(css)}); if (!el) return false; el.focus(); return true; })()`,
+      expression: `(() => { const el = ${targetExpr(params.ref, params.selector)}; if (!el) return false; el.focus(); return true; })()`,
       returnByValue: true,
     });
     if (!result.value) throw new Error(`element not found: ${css}`);
@@ -546,12 +544,13 @@ export async function cdpWaitFor(params: WaitForParams): Promise<{ ok: true }> {
   const state = params.state ?? "visible";
   const timeoutMs = params.timeoutMs ?? 5000;
 
+  const target = targetExpr(params.ref, params.selector);
   let checkExpr: string;
   if (state === "present") {
-    checkExpr = `!!document.querySelector(${JSON.stringify(css)})`;
+    checkExpr = `!!${target}`;
   } else if (state === "visible") {
     checkExpr = `(() => {
-      const el = document.querySelector(${JSON.stringify(css)});
+      const el = ${target};
       if (!el) return false;
       const r = el.getBoundingClientRect();
       const s = getComputedStyle(el);
@@ -560,7 +559,7 @@ export async function cdpWaitFor(params: WaitForParams): Promise<{ ok: true }> {
   } else {
     // hidden: element missing OR not visible
     checkExpr = `(() => {
-      const el = document.querySelector(${JSON.stringify(css)});
+      const el = ${target};
       if (!el) return true;
       const r = el.getBoundingClientRect();
       const s = getComputedStyle(el);
diff --git a/packages/extension/src/lib/jev-snapshot.ts b/packages/extension/src/lib/jev-snapshot.ts
index 3a22ea4..1bfa25d 100644
--- a/packages/extension/src/lib/jev-snapshot.ts
+++ b/packages/extension/src/lib/jev-snapshot.ts
@@ -10,6 +10,7 @@
  */
 
 import type { JevAction } from "@reins/protocol";
+import type { pageDom } from "./page-dom.js";
 
 interface JevCache {
   ids: WeakMap<Element, number>;
@@ -25,7 +26,10 @@ interface JevCache {
  *  erased, so the serialized function stays self-contained. */
 type Action = Omit<JevAction, "id"> & { id?: string };
 
-export function jevSnapshot(terms: string[] = []): {
+export function jevSnapshot(
+  terms: string[],
+  dom: typeof pageDom,
+): {
   url: string;
   title: string;
   text: string;
@@ -61,127 +65,11 @@ export function jevSnapshot(terms: string[] = []): {
   };
   for (const [id, e] of c.nodes) if (!e.isConnected) c.nodes.delete(id);
 
-  // Shadow DOM: what an open shadow root renders is part of the page a
-  // person sees (a site's search box or dialog built as a web component), so
-  // controls and text are collected through open roots, recursively, and
-  // ancestor walks cross the boundary through the host. A closed root cannot
-  // be reached from the page and stays invisible.
-  const parentOf = (n: Node): Element | null => {
-    const p = n.parentNode;
-    if (!p) return null;
-    if (p instanceof ShadowRoot) return p.host;
-    return p.nodeType === 1 ? (p as Element) : null;
-  };
-  /** `closest`, crossing shadow boundaries. */
-  const ancestor = (e: Element, sel: string): Element | null => {
-    for (let p: Element | null = e; p; p = parentOf(p)) if (p.matches(sel)) return p;
-    return null;
-  };
-  /** The element with `id` in the tree `e` belongs to (a shadow root has its own ids). */
-  const byId = (e: Element, id: string): Element | null => {
-    const root = e.getRootNode();
-    return root instanceof Document || root instanceof ShadowRoot ? root.getElementById(id) : null;
-  };
+  // Shadow DOM: controls and text are collected through open shadow roots,
+  // and ancestor walks cross the boundary (see pageDom).
+  const { parentOf, ancestor, visible, name, collect } = dom();
   const safe = (e: Element) =>
     !["password", "file", "hidden"].includes((e as HTMLInputElement).type);
-  const visible = (e: Element) =>
-    !ancestor(e, '[aria-hidden="true"],[inert]') &&
-    e.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true });
-  /** What an element renders, the way the accessibility tree reads it: an
-   *  open shadow root's children stand in for the host's own (which only
-   *  show through slots), and a slot stands for what is assigned to it. */
-  const rendered = (e: Element): Node[] => {
-    if (e.shadowRoot) return [...e.shadowRoot.childNodes];
-    if (e instanceof HTMLSlotElement) return e.assignedNodes({ flatten: true });
-    return [...e.childNodes];
-  };
-  const name = (e: Element | null, seen = new Set<Element>()): string => {
-    if (!e || seen.has(e)) return "";
-    seen.add(e);
-    const input = e as HTMLInputElement;
-    const referenced = (e.getAttribute("aria-labelledby") ?? "")
-      .split(/\s+/)
-      .map((id) => name(byId(e, id), seen))
-      .filter(Boolean)
-      .join(" ");
-    const raw =
-      referenced ||
-      e.getAttribute("aria-label") ||
-      [...(input.labels ?? [])]
-        .map((l) => name(l, seen))
-        .filter(Boolean)
-        .join(" ") ||
-      (["button", "submit", "reset"].includes(input.type) && e.tagName === "INPUT"
-        ? input.value
-        : "") ||
-      e.getAttribute("alt") ||
-      // A select's options are not its name. Text is read through open
-      // shadow roots and slots, so a web-component option or button whose
-      // words sit in its own root (or come in through a slot) is named.
-      (e.tagName === "INPUT" || e.tagName === "SELECT"
-        ? ""
-        : rendered(e)
-            .map((n) =>
-              n.nodeType === 3
-                ? (n.textContent ?? "")
-                : n.nodeType === 1 && (n as Element).getAttribute("aria-hidden") !== "true"
-                  ? name(n as Element, seen)
-                  : "",
-            )
-            .join(" ")) ||
-      "";
-    const own = raw.replace(/\s+/g, " ").trim();
-    if (own) return own;
-    // No label of its own: a title or placeholder is a weak name, and a form
-    // control gets the row or group it sits in — the first cell of an
-    // enclosing table row that is not its own, a fieldset's legend, a
-    // labelled group — so "Year" under "Start Date" and "Year" under "End
-    // Date" read apart, and an unlabelled select is not just "combobox".
-    const weak = (e.getAttribute("title") || e.getAttribute("placeholder") || "")
-      .replace(/\s+/g, " ")
-      .trim();
-    if (!e.matches("input,select,textarea")) return weak;
-    const ctx = context(e);
-    return ctx ? (weak ? `${ctx}: ${weak}` : ctx) : weak;
-  };
-  // A cell's own words: what a person reads as the row's label. Controls in
-  // the cell (a select's options, a button's caption) are not that label.
-  const cellText = (cell: Element): string => {
-    let out = "";
-    const walk = (n: Node) => {
-      if (n.nodeType === 3) out += `${n.textContent ?? ""} `;
-      else if (n.nodeType === 1) {
-        const el = n as Element;
-        if (
-          /^(SELECT|INPUT|TEXTAREA|BUTTON|SCRIPT|STYLE)$/.test(el.tagName) ||
-          el.getAttribute("aria-hidden") === "true"
-        )
-          return;
-        for (const c of el.childNodes) walk(c);
-      }
-    };
-    walk(cell);
-    return out.replace(/\s+/g, " ").trim();
-  };
-  const context = (e: Element): string => {
-    for (let p = parentOf(e); p && p !== document.body; p = parentOf(p)) {
-      if (p.tagName === "TR") {
-        for (const cell of p.children) {
-          if (cell.contains(e)) continue;
-          const t = cellText(cell);
-          if (t && t.length <= 60) return t;
-        }
-      } else if (p.tagName === "FIELDSET") {
-        const legend = p.querySelector(":scope > legend");
-        const t = legend ? name(legend) : "";
-        if (t) return t;
-      } else if (p.getAttribute("role") === "group") {
-        const t = name(p);
-        if (t) return t;
-      }
-    }
-    return "";
-  };
   const roles = [
     "button",
     "link",
@@ -299,16 +187,7 @@ export function jevSnapshot(terms: string[] = []): {
 
   // Every control in document order, descending into open shadow roots where
   // their hosts sit (so ids stay positional across light and shadow trees).
-  const controls: Element[] = [];
-  const collect = (root: Node): void => {
-    const tw = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
-    for (let n = tw.nextNode(); n; n = tw.nextNode()) {
-      const e = n as Element;
-      if (e.matches(selector)) controls.push(e);
-      if (e.shadowRoot) collect(e.shadowRoot);
-    }
-  };
-  collect(document.documentElement);
+  const controls = collect(selector);
   const actions: Action[] = [];
   // Beyond the viewport, two kinds of control are worth listing (the page's
   // text stays viewport-only): a pager — a next/previous/page-N control, or
diff --git a/packages/extension/src/lib/jev.ts b/packages/extension/src/lib/jev.ts
index 97110c7..58f372d 100644
--- a/packages/extension/src/lib/jev.ts
+++ b/packages/extension/src/lib/jev.ts
@@ -24,6 +24,7 @@ import {
   jevSubmitFocus,
   jevSubmitted,
 } from "./jev-snapshot.js";
+import { pageDom } from "./page-dom.js";
 
 /** reins do waits this long for a covered or moving target, then re-reads the page. */
 export const JEV_ACTION_TIMEOUT_MS = 500;
@@ -178,8 +179,10 @@ async function readOnce(
   const settled = tab?.status !== "loading" || doc.ready === "interactive";
   if (!settled && !overdue) return undefined;
   return (
-    (await evaluate<Snapshot | null>(tabId, `(${jevSnapshot})(${JSON.stringify(terms)})`)) ??
-    undefined
+    (await evaluate<Snapshot | null>(
+      tabId,
+      `(${jevSnapshot})(${JSON.stringify(terms)}, ${pageDom})`,
+    )) ?? undefined
   );
 }
 
diff --git a/packages/extension/src/lib/page-actions.test.ts b/packages/extension/src/lib/page-actions.test.ts
index 85a334b..61e0dc4 100644
--- a/packages/extension/src/lib/page-actions.test.ts
+++ b/packages/extension/src/lib/page-actions.test.ts
@@ -214,6 +214,29 @@ describe("upload", () => {
     expect(set?.params).toEqual({ files: ["/tmp/cv.pdf"], nodeId: 42 });
   });
 
+  it("hands CDP the element itself for a ref, which may sit in a shadow root", async () => {
+    const calls = stubChrome((method) => {
+      if (method === "Runtime.evaluate") return { result: { type: "object", objectId: "obj-1" } };
+      return {};
+    });
+    await upload({ ref: "e4", files: ["/tmp/cv.pdf"], tabId: 1 });
+    expect(calls[0]?.params?.expression).toContain('"e4"');
+    expect(calls.some((c) => c.method === "DOM.querySelector")).toBe(false);
+    const set = calls.find((c) => c.method === "DOM.setFileInputFiles");
+    expect(set?.params).toEqual({ files: ["/tmp/cv.pdf"], objectId: "obj-1" });
+    expect(calls.at(-1)).toEqual({
+      method: "Runtime.releaseObject",
+      params: { objectId: "obj-1" },
+    });
+  });
+
+  it("errors when no element holds the ref", async () => {
+    stubChrome(() => ({ result: { type: "object", subtype: "null" } }));
+    await expect(upload({ ref: "e9", files: ["/tmp/a"], tabId: 1 })).rejects.toThrow(
+      'element not found: [data-reins-ref="e9"]',
+    );
+  });
+
   it("errors when the selector matches nothing", async () => {
     stubChrome((method) => {
       if (method === "DOM.getDocument") return { root: { nodeId: 1 } };
diff --git a/packages/extension/src/lib/page-actions.ts b/packages/extension/src/lib/page-actions.ts
index 48e6f82..252e1ac 100644
--- a/packages/extension/src/lib/page-actions.ts
+++ b/packages/extension/src/lib/page-actions.ts
@@ -16,6 +16,7 @@ import {
   resolveTabId,
   selectorFor,
   send,
+  targetExpr,
   withDebugger,
 } from "./cdp.js";
 import { parseKeySpec } from "./keys.js";
@@ -71,7 +72,9 @@ export async function hover(params: HoverParams): Promise<{ ok: true }> {
   const css = selectorFor(params.ref, params.selector);
   return drivePage(tabId, async () => {
     await ensureVisible(tabId);
-    const { x, y } = await actionablePoint(tabId, css, "hover", false);
+    const { x, y } = await actionablePoint(tabId, css, "hover", false, {
+      locate: targetExpr(params.ref, params.selector),
+    });
     await send(tabId, "Input.dispatchMouseEvent", { type: "mouseMoved", x, y });
     return { ok: true };
   });
@@ -81,8 +84,7 @@ export async function scroll(params: ScrollParams): Promise<{ ok: true }> {
   const tabId = await resolveTabId(params.tabId);
   let expression: string;
   if (params.ref !== undefined || params.selector !== undefined) {
-    const css = selectorFor(params.ref, params.selector);
-    expression = `(() => { const el = document.querySelector(${JSON.stringify(css)}); if (!el) return false; el.scrollIntoView({block:"center"}); return true; })()`;
+    expression = `(() => { const el = ${targetExpr(params.ref, params.selector)}; if (!el) return false; el.scrollIntoView({block:"center"}); return true; })()`;
   } else if (params.by) {
     expression = `(window.scrollBy(${params.by.dx}, ${params.by.dy}), true)`;
   } else if (params.to === "top") {
@@ -104,7 +106,7 @@ export async function fill(params: FillParams): Promise<{ ok: true }> {
   // Native value setter so frameworks (React) observe the change; then the
   // events a real user interaction would produce.
   const expression = `(() => {
-    const el = document.querySelector(${JSON.stringify(css)});
+    const el = ${targetExpr(params.ref, params.selector)};
     if (!el) return false;
     el.focus();
     const proto = el instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype
@@ -130,7 +132,7 @@ export async function selectOption(params: SelectOptionParams): Promise<{ ok: tr
   const value = JSON.stringify(params.value);
   // Match by option value first, then by visible label.
   const expression = `(() => {
-    const el = document.querySelector(${JSON.stringify(css)});
+    const el = ${targetExpr(params.ref, params.selector)};
     if (!el) return "missing";
     if (!(el instanceof HTMLSelectElement)) return "notselect";
     el.value = ${value};
@@ -156,6 +158,24 @@ export async function upload(params: UploadParams): Promise<{ ok: true }> {
   const tabId = await resolveTabId(params.tabId);
   const css = selectorFor(params.ref, params.selector);
   return drivePage(tabId, async () => {
+    if (!params.selector && params.ref) {
+      // A ref may sit in an open shadow root, out of DOM.querySelector's reach:
+      // hand CDP the element itself.
+      const { result } = await send<{ result: { objectId?: string; subtype?: string } }>(
+        tabId,
+        "Runtime.evaluate",
+        { expression: targetExpr(params.ref) },
+      );
+      if (!result.objectId || result.subtype === "null")
+        throw new Error(`element not found: ${css}`);
+      const { objectId } = result;
+      try {
+        await send(tabId, "DOM.setFileInputFiles", { files: params.files, objectId });
+      } finally {
+        await send(tabId, "Runtime.releaseObject", { objectId }).catch(() => {});
+      }
+      return { ok: true };
+    }
     const doc = await send<{ root: { nodeId: number } }>(tabId, "DOM.getDocument", { depth: 0 });
     const { nodeId } = await send<{ nodeId: number }>(tabId, "DOM.querySelector", {
       nodeId: doc.root.nodeId,
@@ -170,9 +190,7 @@ export async function upload(params: UploadParams): Promise<{ ok: true }> {
 export async function readText(params: ReadTextParams): Promise<{ text: string }> {
   const tabId = await resolveTabId(params.tabId);
   const hasTarget = params.ref !== undefined || params.selector !== undefined;
-  const target = hasTarget
-    ? `document.querySelector(${JSON.stringify(selectorFor(params.ref, params.selector))})`
-    : "document.body";
+  const target = hasTarget ? targetExpr(params.ref, params.selector) : "document.body";
   const expression = `(() => { const el = ${target}; return el ? el.innerText : null; })()`;
   return withDebugger(tabId, async () => {
     const text = await evaluate<string | null>(tabId, expression);
diff --git a/packages/extension/src/lib/page-dom.ts b/packages/extension/src/lib/page-dom.ts
new file mode 100644
index 0000000..f6dfd3e
--- /dev/null
+++ b/packages/extension/src/lib/page-dom.ts
@@ -0,0 +1,177 @@
+/**
+ * Page-side DOM helpers shared by `reins snapshot` and `reins do`'s
+ * observation. Like every page function here, these run *inside the page* via
+ * Runtime.evaluate, serialized with Function.prototype.toString, so they stay
+ * self-contained: no imports, no references to module scope. A page function
+ * that needs them takes `pageDom` itself as an argument —
+ * `(${stepSnapshot})(${pageDom})` — and calls it for the helpers.
+ *
+ * Shadow DOM: what an open shadow root renders is part of the page a person
+ * sees (a site's search box or dialog built as a web component), so elements
+ * and text are collected through open roots, recursively, and ancestor walks
+ * cross the boundary through the host. A closed root cannot be reached from
+ * the page and stays invisible.
+ */
+export function pageDom() {
+  const parentOf = (n: Node): Element | null => {
+    const p = n.parentNode;
+    if (!p) return null;
+    if (p instanceof ShadowRoot) return p.host;
+    return p.nodeType === 1 ? (p as Element) : null;
+  };
+  /** `closest`, crossing shadow boundaries. */
+  const ancestor = (e: Element, sel: string): Element | null => {
+    for (let p: Element | null = e; p; p = parentOf(p)) if (p.matches(sel)) return p;
+    return null;
+  };
+  /** The element with `id` in the tree `e` belongs to (a shadow root has its own ids). */
+  const byId = (e: Element, id: string): Element | null => {
+    const root = e.getRootNode();
+    return root instanceof Document || root instanceof ShadowRoot ? root.getElementById(id) : null;
+  };
+  const visible = (e: Element) =>
+    !ancestor(e, '[aria-hidden="true"],[inert]') &&
+    e.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true });
+  /** What an element renders, the way the accessibility tree reads it: an
+   *  open shadow root's children stand in for the host's own (which only
+   *  show through slots), and a slot stands for what is assigned to it. */
+  const rendered = (e: Element): Node[] => {
+    if (e.shadowRoot) return [...e.shadowRoot.childNodes];
+    if (e instanceof HTMLSlotElement) return e.assignedNodes({ flatten: true });
+    return [...e.childNodes];
+  };
+  /** Every element matching `selector` in document order, descending into
+   *  open shadow roots where their hosts sit. */
+  const collect = (selector: string): Element[] => {
+    const out: Element[] = [];
+    const walk = (root: Node): void => {
+      const tw = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
+      for (let n = tw.nextNode(); n; n = tw.nextNode()) {
+        const e = n as Element;
+        if (e.matches(selector)) out.push(e);
+        if (e.shadowRoot) walk(e.shadowRoot);
+      }
+    };
+    walk(document.documentElement);
+    return out;
+  };
+  const label = (e: Element | null, max: number, seen: Set<Element>): string => {
+    if (!e || seen.has(e)) return "";
+    seen.add(e);
+    const input = e as HTMLInputElement;
+    const referenced = (e.getAttribute("aria-labelledby") ?? "")
+      .split(/\s+/)
+      .map((id) => label(byId(e, id), max, seen))
+      .filter(Boolean)
+      .join(" ");
+    // A select's options are not its name. Text is read through open shadow
+    // roots and slots, so a web-component option or button whose words sit in
+    // its own root (or come in through a slot) is named. Reading stops once
+    // `max` characters are in: a big container is not walked to the end.
+    const text = (): string => {
+      if (e.tagName === "INPUT" || e.tagName === "SELECT") return "";
+      let out = "";
+      for (const n of rendered(e)) {
+        if (out.length > max) break;
+        out += ` ${
+          n.nodeType === 3
+            ? (n.textContent ?? "")
+            : n.nodeType === 1 && (n as Element).getAttribute("aria-hidden") !== "true"
+              ? label(n as Element, max, seen)
+              : ""
+        }`;
+      }
+      return out;
+    };
+    const raw =
+      referenced ||
+      e.getAttribute("aria-label") ||
+      [...(input.labels ?? [])]
+        .map((l) => label(l, max, seen))
+        .filter(Boolean)
+        .join(" ") ||
+      (["button", "submit", "reset"].includes(input.type) && e.tagName === "INPUT"
+        ? input.value
+        : "") ||
+      e.getAttribute("alt") ||
+      text() ||
+      "";
+    const own = raw.replace(/\s+/g, " ").trim();
+    if (own) return own;
+    // No label of its own: a title or placeholder is a weak name, and a form
+    // control gets the row or group it sits in — the first cell of an
+    // enclosing table row that is not its own, a fieldset's legend, a
+    // labelled group — so "Year" under "Start Date" and "Year" under "End
+    // Date" read apart, and an unlabelled select is not just "combobox".
+    const weak = (e.getAttribute("title") || e.getAttribute("placeholder") || "")
+      .replace(/\s+/g, " ")
+      .trim();
+    if (!e.matches("input,select,textarea")) return weak;
+    const ctx = context(e);
+    return ctx ? (weak ? `${ctx}: ${weak}` : ctx) : weak;
+  };
+  /** An element's accessible name, composed through open shadow roots and
+   *  slots. `max` bounds how much text is read (the name may run past it). */
+  const name = (e: Element | null, max = Number.POSITIVE_INFINITY): string =>
+    label(e, max, new Set());
+  // A cell's own words: what a person reads as the row's label. Controls in
+  // the cell (a select's options, a button's caption) are not that label.
+  const cellText = (cell: Element): string => {
+    let out = "";
+    const walk = (n: Node) => {
+      if (n.nodeType === 3) out += `${n.textContent ?? ""} `;
+      else if (n.nodeType === 1) {
+        const el = n as Element;
+        if (
+          /^(SELECT|INPUT|TEXTAREA|BUTTON|SCRIPT|STYLE)$/.test(el.tagName) ||
+          el.getAttribute("aria-hidden") === "true"
+        )
+          return;
+        for (const c of el.childNodes) walk(c);
+      }
+    };
+    walk(cell);
+    return out.replace(/\s+/g, " ").trim();
+  };
+  const context = (e: Element): string => {
+    for (let p = parentOf(e); p && p !== document.body; p = parentOf(p)) {
+      if (p.tagName === "TR") {
+        for (const cell of p.children) {
+          if (cell.contains(e)) continue;
+          const t = cellText(cell);
+          if (t && t.length <= 60) return t;
+        }
+      } else if (p.tagName === "FIELDSET") {
+        const legend = p.querySelector(":scope > legend");
+        const t = legend ? name(legend) : "";
+        if (t) return t;
+      } else if (p.getAttribute("role") === "group") {
+        const t = name(p);
+        if (t) return t;
+      }
+    }
+    return "";
+  };
+  return { parentOf, ancestor, byId, visible, rendered, collect, name };
+}
+
+/** The helpers `pageDom` hands a page function. */
+export type PageDom = ReturnType<typeof pageDom>;
+
+/**
+ * The element `reins snapshot` tagged with `ref`, searched through open
+ * shadow roots (the snapshot tags elements there too); null when none has it.
+ */
+export function findRef(ref: string): Element | null {
+  const search = (root: Node): Element | null => {
+    const tw = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
+    for (let n = tw.nextNode(); n; n = tw.nextNode()) {
+      const e = n as Element;
+      if (e.getAttribute("data-reins-ref") === ref) return e;
+      const inner = e.shadowRoot ? search(e.shadowRoot) : null;
+      if (inner) return inner;
+    }
+    return null;
+  };
+  return search(document.documentElement);
+}
diff --git a/packages/extension/src/lib/pointer.browser.test.ts b/packages/extension/src/lib/pointer.browser.test.ts
index cea4a95..3fb45c8 100644
--- a/packages/extension/src/lib/pointer.browser.test.ts
+++ b/packages/extension/src/lib/pointer.browser.test.ts
@@ -19,10 +19,11 @@ import { WebSocket } from "ws";
 vi.mock("./monitor.js", () => ({ isMonitored: () => false }));
 
 import { autofillGuard } from "./autofill-guard.js";
-import { __resetDebugSessions, cdpClick, cdpType, drivePage } from "./cdp.js";
+import { __resetDebugSessions, cdpClick, cdpSnapshot, cdpType, drivePage } from "./cdp.js";
 import { initDialogTracking, jevAct, jevObserve, openDialog } from "./jev.js";
 import { jevSnapshot } from "./jev-snapshot.js";
-import { handleDialog, hover, pressKey } from "./page-actions.js";
+import { fill, handleDialog, hover, pressKey } from "./page-actions.js";
+import { pageDom } from "./page-dom.js";
 
 const CHROME = [
   process.env.REINS_TEST_CHROME,
@@ -158,6 +159,49 @@ const JEV_FIXTURE = `<!doctype html><html><head><meta charset="utf-8"><style>
   });
 </script></body></html>`;
 
+/** `reins snapshot` and ref-addressed commands: shadow DOM, custom controls. */
+const STEPS_FIXTURE = `<!doctype html><html><head><meta charset="utf-8"><style>
+  body { margin: 0; font: 14px sans-serif }
+  .card { display: block; position: relative; border: 1px solid #999; padding: 12px; margin: 6px; width: 240px }
+  .card input, [role=switch] input { position: absolute; width: 0; height: 0; margin: 0; padding: 0; border: 0; appearance: none }
+  [role=switch] { display: inline-block; position: relative; width: 44px; height: 24px; background: #ccc }
+</style></head><body>
+<x-search id="xs"></x-search>
+<x-field id="xf"><span slot="label">Due date</span></x-field>
+<div id="sealed"></div>
+<fieldset><legend>Plan</legend>
+  <label class="card"><input type="radio" name="plan" id="solo" value="solo" checked> Solo</label>
+  <label class="card"><input type="radio" name="plan" id="team" value="team"> Team</label>
+</fieldset>
+<input type="checkbox" id="terms" style="display:none"><label for="terms" class="card">I agree</label>
+<div role="switch" id="sw" aria-checked="false" aria-label="Dark mode"><input type="checkbox" id="swi"></div>
+<span id="dc" style="display:contents"><button id="dcb">Chip</button></span>
+<div role="tablist"><button role="tab" id="t1">One</button><button role="tab" id="t2">Two</button></div>
+<div id="p1"><input id="one" aria-label="First field"></div>
+<div id="p2" hidden><button role="switch" id="alerts" aria-checked="false" aria-label="Alerts">x</button></div>
+<script>
+  window.__log = [];
+  document.addEventListener("click", (e) => __log.push("click:" + (e.composedPath()[0].id || e.composedPath()[0].tagName)), true);
+  // A site search built as a web component: field and button in an open root.
+  { const r = document.getElementById("xs").attachShadow({ mode: "open" });
+    r.innerHTML = '<input id="sq" placeholder="Search the docs"><button id="sb">Search</button>';
+    r.getElementById("sb").addEventListener("click", () => __log.push("search:" + r.getElementById("sq").value)); }
+  // A button two shadow roots down whose caption is slotted through both.
+  { const r = document.getElementById("xf").attachShadow({ mode: "open" });
+    r.innerHTML = '<x-inner id="xi"><slot name="label" slot="lbl"></slot></x-inner>';
+    const inner = r.getElementById("xi").attachShadow({ mode: "open" });
+    inner.innerHTML = '<button id="pick"><slot name="lbl"></slot></button>';
+    inner.getElementById("pick").addEventListener("click", () => __log.push("pick")); }
+  document.getElementById("sealed").attachShadow({ mode: "closed" }).innerHTML = "<button>Sealed</button>";
+  const sw = document.getElementById("sw"), swi = document.getElementById("swi");
+  sw.addEventListener("click", () => { swi.checked = !swi.checked; sw.setAttribute("aria-checked", String(swi.checked)); });
+  const alerts = document.getElementById("alerts");
+  alerts.addEventListener("click", () => alerts.setAttribute("aria-checked", String(alerts.getAttribute("aria-checked") !== "true")));
+  for (const [tab, show] of [["t1", "p1"], ["t2", "p2"]]) document.getElementById(tab).addEventListener("click", () => {
+    for (const p of ["p1", "p2"]) document.getElementById(p).hidden = p !== show;
+  });
+</script></body></html>`;
+
 let chromeProc: ChildProcess | undefined;
 /** Scripts drivePage injected, with the tab (socket) each belongs to. */
 const injected: Array<{ identifier: string; tabId: number | undefined }> = [];
@@ -270,7 +314,9 @@ describe.skipIf(!CHROME)("pointer + key input in a real browser", () => {
           ? LOGIN_FIXTURE
           : path === "/jev"
             ? JEV_FIXTURE.replace("SLOW_URL", slowUrl)
-            : FIXTURE,
+            : path === "/steps"
+              ? STEPS_FIXTURE
+              : FIXTURE,
       );
     });
     // A second origin (so its tab gets its own renderer, as another site's
@@ -743,7 +789,7 @@ describe.skipIf(!CHROME)("pointer + key input in a real browser", () => {
   });
 
   type Snap = NonNullable<ReturnType<typeof jevSnapshot>>;
-  const snap = () => evaluate<Snap>(`(${jevSnapshot})()`);
+  const snap = () => evaluate<Snap>(`(${jevSnapshot})([], ${pageDom})`);
   const nodeOf = (s: Snap, label: string) => s.actions.find((a) => a.label === label)?.node;
 
   it("jev: lists visible controls, including a fixed-position dialog, and skips the rest", async () => {
@@ -1020,4 +1066,77 @@ describe.skipIf(!CHROME)("pointer + key input in a real browser", () => {
     await new Promise((r) => setTimeout(r, 200));
     expect(openDialog(1)).toBeUndefined();
   }, 10_000);
+
+  const refOf = async (role: string, name: string) => {
+    const { refs } = await cdpSnapshot({ tabId: 1, mode: "a11y" });
+    const hit = refs.find((r) => r.role === role && r.name === name);
+    if (!hit) throw new Error(`no ${role} "${name}" in ${JSON.stringify(refs)}`);
+    return hit.ref;
+  };
+  const byRef = (ref: string) => cdpClick({ tabId: 1, ref, button: "left", clickCount: 1 });
+
+  it("snapshot: lists controls in an open shadow root, and click/type/fill by ref reach them; a closed root stays invisible", async () => {
+    await load("/steps");
+    const { content } = await cdpSnapshot({ tabId: 1, mode: "a11y" });
+    expect(content).toMatch(/e\d+: input "Search the docs"/);
+    expect(content).toMatch(/e\d+: button "Search"/);
+    expect(content).not.toContain("Sealed");
+    const field = await refOf("input", "Search the docs");
+    await fill({ tabId: 1, ref: field, value: "fe" });
+    await cdpType({ tabId: 1, ref: field, text: "tch", submit: false });
+    await byRef(await refOf("button", "Search"));
+    expect(await log()).toContain("search:fetch");
+  });
+
+  it("snapshot: a shadow button two roots down is named by its slotted caption", async () => {
+    await load("/steps");
+    await byRef(await refOf("button", "Due date"));
+    // The press lands on the slotted caption, inside the button as rendered.
+    expect(await log()).toEqual(["click:SPAN", "pick"]);
+  });
+
+  it("snapshot: refs are re-issued each time, so a ref an element hidden since held reaches its new owner", async () => {
+    await load("/steps");
+    const first = await refOf("input", "First field");
+    await byRef(await refOf("tab", "Two"));
+    // The panel switch hid the field; the switch now listed takes its number.
+    const alerts = await refOf("switch", "Alerts");
+    expect(alerts).toBe(first);
+    await byRef(alerts);
+    expect(await evaluate("document.getElementById('alerts').getAttribute('aria-checked')")).toBe(
+      "true",
+    );
+  });
+
+  it("a radio card whose native input is 0x0 is clicked by ref through its label, and ends checked", async () => {
+    await load("/steps");
+    await byRef(await refOf("input", "Team"));
+    expect(await evaluate("document.getElementById('team').checked")).toBe(true);
+    expect(await evaluate("document.getElementById('solo').checked")).toBe(false);
+  });
+
+  it("a display:none checkbox is clicked through its label[for]", async () => {
+    await load("/steps");
+    await click("#terms");
+    expect(await evaluate("document.getElementById('terms').checked")).toBe(true);
+  });
+
+  it("a role=switch toggle whose native checkbox is 0x0 is clicked by the checkbox's ref, and ends checked", async () => {
+    await load("/steps");
+    await cdpSnapshot({ tabId: 1, mode: "a11y" });
+    const ref = await evaluate<string>(
+      "document.getElementById('swi').getAttribute('data-reins-ref')",
+    );
+    await byRef(ref);
+    expect(await evaluate("document.getElementById('swi').checked")).toBe(true);
+    expect(await evaluate("document.getElementById('sw').getAttribute('aria-checked')")).toBe(
+      "true",
+    );
+  });
+
+  it("a display:contents element is clicked on its first rendered child", async () => {
+    await load("/steps");
+    await click("#dc");
+    expect(await log()).toEqual(["click:dcb"]);
+  });
 });
diff --git a/packages/extension/src/lib/snapshot.ts b/packages/extension/src/lib/snapshot.ts
new file mode 100644
index 0000000..bfda64c
--- /dev/null
+++ b/packages/extension/src/lib/snapshot.ts
@@ -0,0 +1,41 @@
+/**
+ * `reins snapshot`'s page half. Runs *inside the page* via Runtime.evaluate,
+ * serialized with Function.prototype.toString, so it stays self-contained:
+ * the shared DOM helpers come in as the `dom` argument (see pageDom).
+ */
+
+import type { pageDom } from "./page-dom.js";
+
+export interface StepSnapshot {
+  content: string;
+  refs: Array<{ ref: string; role: string; name: string }>;
+}
+
+/**
+ * Tag interactive and heading elements with `data-reins-ref="e#"` and list
+ * them. Elements inside open shadow roots are listed and tagged too (a site's
+ * search button or menu built as a web component); closed roots stay out of
+ * reach. Names are composed the way `reins do` reads them: aria-labelledby,
+ * aria-label, labels, then rendered text through shadow roots and slots.
+ */
+export function stepSnapshot(dom: typeof pageDom): StepSnapshot {
+  const { name, collect } = dom();
+  const ATTR = "data-reins-ref";
+  // A ref names exactly one element, so the last snapshot's tags come off
+  // first. An element hidden since (the wizard step just left, the tab panel
+  // just switched away from) would otherwise keep a ref this snapshot hands to
+  // another element, and `--ref` would find the hidden one first.
+  for (const el of collect(`[${ATTR}]`)) el.removeAttribute(ATTR);
+  const refs: StepSnapshot["refs"] = [];
+  let n = 0;
+  const sel = 'a,button,input,textarea,select,[role],h1,h2,h3,[contenteditable="true"]';
+  for (const el of collect(sel)) {
+    if (!(el instanceof HTMLElement) || !el.checkVisibility({ checkVisibilityCSS: true })) continue;
+    const ref = `e${++n}`;
+    el.setAttribute(ATTR, ref);
+    const role = el.getAttribute("role") || el.tagName.toLowerCase();
+    refs.push({ ref, role, name: name(el, 80).slice(0, 80) });
+  }
+  const content = refs.map((r) => `${r.ref}: ${r.role} ${JSON.stringify(r.name)}`).join("\n");
+  return { content, refs };
+}
diff --git a/packages/web/src/routes/docs/commands.tsx b/packages/web/src/routes/docs/commands.tsx
index 8ba9dae..83ad5d7 100644
--- a/packages/web/src/routes/docs/commands.tsx
+++ b/packages/web/src/routes/docs/commands.tsx
@@ -67,7 +67,8 @@ const GROUPS: Array<{ id: string; title: string; intro?: ReactNode; rows: [strin
   {
     id: "interaction",
     title: "Interaction",
-    intro: "Interaction commands address elements by ref (from reins snapshot) or by CSS selector.",
+    intro:
+      "Interaction commands address elements by ref (from reins snapshot) or by CSS selector. Snapshot and refs reach into open shadow roots; a CSS selector matches the light DOM only.",
     rows: [
       [
         "reins snapshot [--tab <id>] [--max-chars <n>]",
diff --git a/skills/reins/SKILL.md b/skills/reins/SKILL.md
index c477816..e09c323 100644
--- a/skills/reins/SKILL.md
+++ b/skills/reins/SKILL.md
@@ -76,13 +76,16 @@ reins status
 1. **Find the tab** — `reins tabs` lists every tab in every connected
    browser (`b1  tab 12 *  Title — url`; `*` = active tab).
 2. **See what's interactive** — `reins snapshot --tab 12` prints elements
-   with refs like `e5: button "Submit"`.
+   with refs like `e5: button "Submit"`, including ones inside open shadow
+   roots (web components); closed shadow roots stay invisible.
 3. **Act on refs** — `reins click --ref e5 --tab 12`,
    `reins type --ref e3 --text "hi" --enter --tab 12`.
-   CSS selectors work anywhere a ref does: `--selector "#submit"`.
+   CSS selectors work anywhere a ref does: `--selector "#submit"` — but only
+   on the light DOM; use a ref for an element inside a shadow root.
 4. **Verify** — `reins text --tab 12` (visible page text) or
    `reins screenshot --tab 12` (prints an image path — Read the file to view
-   it). Refs go stale after navigation; re-run `snapshot`.
+   it). Refs go stale after navigation, and each `snapshot` re-issues them
+   (only the latest snapshot's refs are valid); re-run `snapshot`.
 
 ## Delegate a whole task: `reins do` (when a TypeSafe key is set)
 

From c38296130d0f2c6b170326ced11c72d99e9aaa0e Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Mon, 28 Sep 2026 22:17:43 +0530
Subject: [PATCH 3/3] fix(bench): wizard fixture's modal starts hidden; report
 notes the step-command fixes

.backdrop { display: flex } overrode the hidden attribute, so the New
project modal was already open on load in every benchmark run. The
report and page now say the snapshot and stale-ref bugs behind some
step-by-step failures were fixed after the benchmark.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/step-commands-shadow-dom.md          | 2 +-
 docs/benchmarks/2026-09-reins-do.md             | 2 +-
 packages/cli/scripts/bench/fixtures/wizard.html | 1 +
 packages/web/src/routes/docs/benchmarks.tsx     | 6 ++++--
 4 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/.changeset/step-commands-shadow-dom.md b/.changeset/step-commands-shadow-dom.md
index 6e2a5b4..6f5de2c 100644
--- a/.changeset/step-commands-shadow-dom.md
+++ b/.changeset/step-commands-shadow-dom.md
@@ -3,4 +3,4 @@
 "@reins/extension": patch
 ---
 
-Step commands see web components and custom controls. `reins snapshot` now lists elements inside open shadow roots (a site's search button, a `Sort by` menu built as a web component) and names them the way `reins do` does — through `aria-labelledby`, labels, shadow roots and slots — and `--ref` reaches them in `click`, `type`, `fill`, `hover`, `select` and the rest. `--selector` stays light-DOM CSS. Each snapshot now re-issues its refs, so a ref no longer lands on an element hidden since the previous snapshot (the "element has zero size" failures on wizards and tab panels). A click on a control with no box of its own — a native radio or checkbox shrunk to 0×0 under a styled card, or a `display: contents` wrapper — presses its visible label, custom radio/switch it sits in, or first rendered child instead.
+Step commands see web components and custom controls. `reins snapshot` now lists elements inside open shadow roots (a site's search button, a `Sort by` menu built as a web component) and names them the way `reins do` does (through `aria-labelledby`, labels, shadow roots and slots), and `--ref` reaches them in `click`, `type`, `fill`, `hover`, `select` and the rest. `--selector` stays light-DOM CSS. Each snapshot now re-issues its refs, so a ref no longer lands on an element hidden since the previous snapshot (the "element has zero size" failures on wizards and tab panels). A click on a control with no box of its own (a native radio or checkbox shrunk to 0×0 under a styled card, or a `display: contents` wrapper) presses its visible label, custom radio/switch it sits in, or first rendered child instead.
diff --git a/docs/benchmarks/2026-09-reins-do.md b/docs/benchmarks/2026-09-reins-do.md
index a9626af..212be03 100644
--- a/docs/benchmarks/2026-09-reins-do.md
+++ b/docs/benchmarks/2026-09-reins-do.md
@@ -443,7 +443,7 @@ claude.ai connectors, so their definitions were in the context too).
 **What the step-by-step arm measures.** It is Claude plus reins' step
 commands, and some of its failures are the step commands': `reins snapshot`
 does not read shadow roots (mdn, openlibrary) and reported "zero size" on
-controls in fx-wizard and fx-settings. A better step toolkit, or a Claude
+controls in fx-wizard and fx-settings. Both were fixed after this benchmark (0.6.1: the snapshot reads open shadow roots, and stale refs from an earlier snapshot no longer point at hidden elements). The fx-wizard page also opened with its modal already showing, for both arms, because a CSS rule overrode `hidden`; that fixture bug was fixed afterwards too. A better step toolkit, or a Claude
 allowed to navigate by URL or use other tabs, would score higher and differ
 in speed and cost.
 
diff --git a/packages/cli/scripts/bench/fixtures/wizard.html b/packages/cli/scripts/bench/fixtures/wizard.html
index 125e6e2..3da52d1 100644
--- a/packages/cli/scripts/bench/fixtures/wizard.html
+++ b/packages/cli/scripts/bench/fixtures/wizard.html
@@ -16,6 +16,7 @@
   button.secondary { background: #fff; color: #2f3e6e; }
   button:disabled { opacity: .5; cursor: not-allowed; }
   .backdrop { position: fixed; inset: 0; background: rgba(20, 24, 40, .55); display: flex; align-items: center; justify-content: center; }
+  .backdrop[hidden] { display: none; }
   .modal { background: #fff; border-radius: 10px; width: 520px; max-width: calc(100% - 32px); box-shadow: 0 20px 60px rgba(0,0,0,.3); }
   .modal header { background: #fff; color: #1a1a1a; border-bottom: 1px solid #dfe3e8; border-radius: 10px 10px 0 0; display: flex; justify-content: space-between; align-items: center; }
   .modal header button { all: unset; cursor: pointer; font-size: 20px; color: #666; padding: 0 4px; }
diff --git a/packages/web/src/routes/docs/benchmarks.tsx b/packages/web/src/routes/docs/benchmarks.tsx
index 6ea2d75..5ce9842 100644
--- a/packages/web/src/routes/docs/benchmarks.tsx
+++ b/packages/web/src/routes/docs/benchmarks.tsx
@@ -1014,8 +1014,10 @@ function BenchmarksPage() {
       <P>
         Read from each failed run's final reply. Several point at reins' own step commands rather
         than at Claude's reasoning: <Code>reins snapshot</Code>, which the step-by-step arm reads
-        pages with, does not look inside shadow roots, while <Code>reins do</Code>'s observation
-        does.
+        pages with, did not look inside shadow roots at the time, while <Code>reins do</Code>'s
+        observation did, and stale refs from an earlier snapshot could point at hidden elements
+        ("zero size"). Both are fixed in 0.6.1. The fx-wizard page also opened with its modal
+        already showing, for both arms, because of a CSS bug in the fixture (fixed since).
       </P>
       <Ul>
         <li>