Frame-Aware Locator Implementation Plan
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Add an optional frame field (CSS selector or array of selectors, outer→inner) to the locator object so every primitive that takes a locator can target elements inside iframes, resolved centrally in the locator layer.
Architecture: Add a pure resolveFrameRoot(frame, topDocument) helper in content.js that folds over frame selectors to reach the innermost same-origin document (or returns a frame_cross_origin / frame_not_found error). resolveLocatorCandidates uses it to pick the query root instead of hardcoding document; queryRelative(root, …) already takes a root, so all resolveSingle* wrappers and every primitive inherit frame targeting. Revert the paste-specific pasteTargetKind auto-descent (superseded).
Tech Stack: Vanilla browser JS (content script, isolated world), node:test source-slice unit tests.
Global Constraints
- Content script, isolated world; handlers return via
primitiveSuccess/primitiveError. frameisstring | string[]; a single string is treated as[string]. No frame → query the topdocument(byte-for-byte current behavior).- Cross-origin frame (contentDocument throws or is null) →
frame_cross_originerror naming the selector. Frame selector matching no<iframe>/<frame>→frame_not_found. - Unit tests slice a pure helper from
content.jssource withnew Function(repo idiom; seetests/clipboard-selection-primitives.test.mjssliceConst). - No behavior change for locators without a
frame.
File Structure
extensions/chrome-overlay-runtime/src/content.js— addresolveFrameRoot(pure), wire it intoresolveLocatorCandidates(line ~2726), record a module-scopedlastLocatorFrameError, surface it inlocatorElementInfo’s empty path, and REVERTpasteTargetKind(lines ~3319-3341) to the simple form.extensions/chrome-overlay-runtime/tests/frame-aware-locator.test.mjs— NEW: source-slice unit tests forresolveFrameRoot.extensions/chrome-overlay-runtime/tests/clipboard-selection-primitives.test.mjs— MODIFY: update thepasteTargetKindtests back to the simple form after the revert.
Task 1: resolveFrameRoot pure helper
The fold that walks frame selectors to the innermost document, with the two error shapes. Pure and source-sliceable.
Files:
- Modify:
extensions/chrome-overlay-runtime/src/content.js(add helper just aboveresolveLocatorCandidates, ~line 2725) - Test:
extensions/chrome-overlay-runtime/tests/frame-aware-locator.test.mjs(new)
Interfaces:
-
Produces:
resolveFrameRoot(frame, topDocument)→{ ok: true, root: Document }or{ ok: false, error: { code, frame, message? } }.code∈"frame_cross_origin" | "frame_not_found". -
Step 1: Write the failing test (create the file)
import assert from "node:assert/strict";
import { readFile } from "node:fs/promises";
import test from "node:test";
const contentSource = await readFile(
new URL("../src/content.js", import.meta.url),
"utf8",
);
const sliceConst = (name) => {
const start = contentSource.indexOf(`const ${name} =`);
assert.ok(start >= 0, `${name} must exist in content.js`);
const marker = "\n };";
const end = contentSource.indexOf(marker, start);
assert.ok(end > start, `${name} body end not found`);
return contentSource.slice(start, end + marker.length);
};
const buildResolveFrameRoot = () =>
new Function(`${sliceConst("resolveFrameRoot")}\n return resolveFrameRoot;`)();
// Minimal fake iframe/document graph.
const makeDoc = (frames = {}) => ({
__isDoc: true,
querySelector(sel) {
return Object.prototype.hasOwnProperty.call(frames, sel) ? frames[sel] : null;
},
});
const makeIframe = (contentDocument) => ({ tagName: "IFRAME", contentDocument });
const makeCrossOriginIframe = () => ({
tagName: "IFRAME",
get contentDocument() {
throw new Error("cross-origin");
},
});
test("no frame returns the top document", () => {
const resolveFrameRoot = buildResolveFrameRoot();
const top = makeDoc();
assert.deepEqual(resolveFrameRoot(undefined, top), { ok: true, root: top });
});
test("single same-origin frame returns the inner document", () => {
const resolveFrameRoot = buildResolveFrameRoot();
const inner = makeDoc();
const top = makeDoc({ ".f": makeIframe(inner) });
assert.deepEqual(resolveFrameRoot(".f", top), { ok: true, root: inner });
});
test("nested frames fold outer-to-inner", () => {
const resolveFrameRoot = buildResolveFrameRoot();
const innermost = makeDoc();
const mid = makeDoc({ ".inner": makeIframe(innermost) });
const top = makeDoc({ ".outer": makeIframe(mid) });
assert.deepEqual(resolveFrameRoot([".outer", ".inner"], top), { ok: true, root: innermost });
});
test("cross-origin frame errors", () => {
const resolveFrameRoot = buildResolveFrameRoot();
const top = makeDoc({ ".x": makeCrossOriginIframe() });
const r = resolveFrameRoot(".x", top);
assert.equal(r.ok, false);
assert.equal(r.error.code, "frame_cross_origin");
assert.equal(r.error.frame, ".x");
});
test("missing frame selector errors frame_not_found", () => {
const resolveFrameRoot = buildResolveFrameRoot();
const top = makeDoc({});
const r = resolveFrameRoot(".nope", top);
assert.equal(r.ok, false);
assert.equal(r.error.code, "frame_not_found");
assert.equal(r.error.frame, ".nope");
});
- Step 2: Run to verify it fails
Run: node --test extensions/chrome-overlay-runtime/tests/frame-aware-locator.test.mjs Expected: FAIL — “resolveFrameRoot must exist in content.js”.
- Step 3: Add the helper to content.js just above
resolveLocatorCandidates(~line 2725)
// Resolve the document a locator should query, given an optional `frame`.
// `frame` is a CSS selector (or array, outer->inner) for iframe(s) to step
// into. Same-origin only: a cross-origin frame's contentDocument is
// unreachable from page JS -> frame_cross_origin. Returns {ok:true, root} or
// {ok:false, error:{code, frame, message?}}.
const resolveFrameRoot = (frame, topDocument) => {
if (frame === undefined || frame === null || frame === "") {
return { ok: true, root: topDocument };
}
const selectors = Array.isArray(frame) ? frame : [frame];
let root = topDocument;
for (const sel of selectors) {
const el = root.querySelector(sel);
const isFrame = el && (el.tagName === "IFRAME" || el.tagName === "FRAME");
if (!isFrame) {
return { ok: false, error: { code: "frame_not_found", frame: sel } };
}
let innerDoc = null;
try {
innerDoc = el.contentDocument;
} catch (_error) {
innerDoc = null;
}
if (!innerDoc) {
return {
ok: false,
error: {
code: "frame_cross_origin",
frame: sel,
message: "Frame is cross-origin; its contents cannot be targeted from page JS.",
},
};
}
root = innerDoc;
}
return { ok: true, root };
};
- Step 4: Run to verify it passes
Run: node --test extensions/chrome-overlay-runtime/tests/frame-aware-locator.test.mjs Expected: PASS (5 tests).
- Step 5: Commit
git add extensions/chrome-overlay-runtime/src/content.js extensions/chrome-overlay-runtime/tests/frame-aware-locator.test.mjs
git commit -m "feat(locator): resolveFrameRoot helper (folds frame selectors to inner document)"
Task 2: Wire resolveFrameRoot into resolveLocatorCandidates
Make the resolver query the frame’s document and record a frame error for surfacing.
Files:
- Modify:
extensions/chrome-overlay-runtime/src/content.js(resolveLocatorCandidates~line 2726; add a module-scopedlastLocatorFrameError)
Interfaces:
- Consumes:
resolveFrameRoot(Task 1), existingqueryRelative. -
Produces:
resolveLocatorCandidatesqueries insidelocator.frame; setslastLocatorFrameError(module-scopedlet, reset to null each call, set to the error object on frame failure). - Step 1: Add the module-scoped error holder near the other locator helpers (just above
resolveLocatorCandidates, afterresolveFrameRoot)
let lastLocatorFrameError = null;
- Step 2: Replace the body of
resolveLocatorCandidates(current lines ~2726-2750). The current first lines are:
const resolveLocatorCandidates = (locator) => {
if (!locator || typeof locator !== "object") return [];
let candidates = [];
if (typeof locator.selector === "string" && locator.selector.trim()) {
candidates = queryRelative(document, locator.selector.trim(), { visible_only: false });
} else {
candidates = Array.from(
document.querySelectorAll("button, a, input, textarea, select, [role], [aria-label], [data-testid], [data-test], [data-actions-json-target]")
);
}
Change to resolve the frame root first and query against it:
const resolveLocatorCandidates = (locator) => {
lastLocatorFrameError = null;
if (!locator || typeof locator !== "object") return [];
const frameResult = resolveFrameRoot(locator.frame, document);
if (!frameResult.ok) {
lastLocatorFrameError = frameResult.error;
return [];
}
const root = frameResult.root;
let candidates = [];
if (typeof locator.selector === "string" && locator.selector.trim()) {
candidates = queryRelative(root, locator.selector.trim(), { visible_only: false });
} else {
candidates = Array.from(
root.querySelectorAll("button, a, input, textarea, select, [role], [aria-label], [data-testid], [data-test], [data-actions-json-target]")
);
}
(Leave the rest of the function — the text filtering — unchanged.)
- Step 3: Verify content.js parses
Run: node --check extensions/chrome-overlay-runtime/src/content.js Expected: no output.
- Step 4: Run the full extension suite (no regressions on the no-frame path)
Run: node --test "extensions/chrome-overlay-runtime/tests/*.test.mjs" Expected: PASS (all existing tests; frame path unused by them so unchanged).
- Step 5: Commit
git add extensions/chrome-overlay-runtime/src/content.js
git commit -m "feat(locator): resolveLocatorCandidates queries inside locator.frame"
Task 3: Surface frame_* errors in locator.element_info
When candidates are empty because of a frame error, report it instead of a bare target_not_found.
Files:
- Modify:
extensions/chrome-overlay-runtime/src/content.js(locatorElementInfoempty-result branch)
Interfaces:
-
Consumes:
lastLocatorFrameError(Task 2). -
Step 1: Update the empty branch of
locatorElementInfo. Current:
if (!element) {
return primitiveError("locator.element_info", "target_not_found", "No visible element matched the locator.", {
locator
});
}
Change to prefer a recorded frame error:
if (!element) {
if (lastLocatorFrameError) {
return primitiveError(
"locator.element_info",
lastLocatorFrameError.code,
lastLocatorFrameError.message || `Frame '${lastLocatorFrameError.frame}' could not be targeted.`,
{ locator, frame: lastLocatorFrameError.frame },
);
}
return primitiveError("locator.element_info", "target_not_found", "No visible element matched the locator.", {
locator
});
}
- Step 2: Verify content.js parses
Run: node --check extensions/chrome-overlay-runtime/src/content.js Expected: no output.
- Step 3: Run the full extension suite
Run: node --test "extensions/chrome-overlay-runtime/tests/*.test.mjs" Expected: PASS.
- Step 4: Commit
git add extensions/chrome-overlay-runtime/src/content.js
git commit -m "feat(locator): surface frame_cross_origin/frame_not_found in element_info"
Task 4: Revert the paste-specific pasteTargetKind auto-descent
The frame-aware locator supersedes it; paste resolves its target through the locator like everything else.
Files:
- Modify:
extensions/chrome-overlay-runtime/src/content.js(isIframeElement+pasteTargetKind, ~lines 3319-3341) - Modify:
extensions/chrome-overlay-runtime/tests/clipboard-selection-primitives.test.mjs(the pasteTargetKind tests)
Interfaces:
-
Produces:
pasteTargetKind(resolved, activeElement)→{ target, target_kind }, simple form: resolved non-null → resolved (resolved-locator); else activeElement (activeElement). No iframe descent. -
Step 1: Replace
isIframeElement+pasteTargetKind(the whole block added in 0.1.150) with the simple form:
// Where a clipboard/selection event dispatches: the resolved locator target,
// or the focused element when no locator was given. Frame targeting (reaching
// inside an iframe) is handled by the locator's `frame` field, not here.
const pasteTargetKind = (resolved, activeElement) => {
if (resolved) {
return { target: resolved, target_kind: "resolved-locator" };
}
return { target: activeElement, target_kind: "activeElement" };
};
- Step 2: Update the pasteTargetKind tests in
clipboard-selection-primitives.test.mjs. Replace thebuildPasteTargetKindhelper + the four iframe tests with the simple pair (there is no longer anisIframeElementto slice):
test("pasteTargetKind uses the resolved element", () => {
const src = sliceConst("pasteTargetKind");
const pasteTargetKind = new Function(`${src} return pasteTargetKind;`)();
const input = { tagName: "INPUT" };
const active = { tagName: "DIV" };
assert.deepEqual(pasteTargetKind(input, active), {
target: input,
target_kind: "resolved-locator",
});
});
test("pasteTargetKind falls back to activeElement when unresolved", () => {
const src = sliceConst("pasteTargetKind");
const pasteTargetKind = new Function(`${src} return pasteTargetKind;`)();
const active = { tagName: "DIV" };
assert.deepEqual(pasteTargetKind(null, active), {
target: active,
target_kind: "activeElement",
});
});
- Step 3: Verify content.js parses + run the clipboard tests
Run: node --check extensions/chrome-overlay-runtime/src/content.js && node --test extensions/chrome-overlay-runtime/tests/clipboard-selection-primitives.test.mjs Expected: PASS.
- Step 4: Commit
git add extensions/chrome-overlay-runtime/src/content.js extensions/chrome-overlay-runtime/tests/clipboard-selection-primitives.test.mjs
git commit -m "refactor(clipboard.paste): drop iframe auto-descent (superseded by frame-aware locator)"
Task 5: Full suite + live validation
Files:
-
Test: full extension + runtime suites
-
Step 1: Run the whole extension suite
Run: node --test "extensions/chrome-overlay-runtime/tests/*.test.mjs" Expected: PASS.
- Step 2: Run the runtime suite
Run: node --test "runtime/actions-json-runtime/tests/*.test.mjs" Expected: PASS.
- Step 3: Run the packaging test
Run: node --test tests/package-extension.test.mjs Expected: PASS.
- Step 4: Live validation (supervised, needs rebuilt extension loaded). After releasing + reloading:
clipboard.paste { text: "frame-locator probe", target: { frame: ".docs-texteventtarget-iframe", selector: "[contenteditable='true']" } }on a Google Doc → VERIFY BY SCREENSHOT the text landed (docs.read is canvas-blind — do NOT trust it).locator.element_info { locator: { frame: ".docs-texteventtarget-iframe", selector: "[contenteditable='true']" } }returns the inner element (not target_not_found).- A cross-origin frame target returns
frame_cross_origin.
Self-Review
Spec coverage: frame string | array (Task 1) ✓; central resolve in resolveLocatorCandidates (Task 2) ✓; frame_cross_origin + frame_not_found (Tasks 1,3) ✓; no-frame backward compat (Task 2, current behavior preserved) ✓; revert paste auto-descent (Task 4) ✓; live screenshot validation (Task 5) ✓. Coordinates note (viewport-relative) is a live-verify in Task 5, not a code task — consistent with the spec flagging it as verify-not-assume. No gaps. |
Placeholder scan: every code step shows the code; every run step shows the command + expected output; no TBD/TODO.
Type consistency: resolveFrameRoot(frame, topDocument) → {ok, root}|{ok:false, error:{code, frame, message?}} used identically in Tasks 1-3. lastLocatorFrameError set in Task 2, read in Task 3. pasteTargetKind(resolved, activeElement) → {target, target_kind} consistent across Task 4 and its tests.
Implementer note: content.js line numbers are approximate — locate by the named anchors (resolveLocatorCandidates, locatorElementInfo, pasteTargetKind). Only the pure resolveFrameRoot is unit-tested directly; the wiring is covered by the no-regression suite + live Task 5 (browser-only behavior can’t be unit-tested in node).