Clipboard & Selection Primitive Family — 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 five browser-runtime primitives — text.select, clipboard.copy, clipboard.paste, clipboard.read, clipboard.write — so agents can select page text, move it to/from the system clipboard, and write into iframe-hosted editors (Google Docs/Sheets/Slides).
Architecture: Each primitive is a handler in extensions/chrome-overlay-runtime/src/content.js, wired into the executeAction dispatch and declared in both overlay.actions.json tool surfaces (tools[] for the bridge, primitive_dictionary.primitives[] for the hosted-agent catalog). Handlers reuse existing helpers (syntheticClipboardEvent, clipboardHtmlFromText, selectEditableContents, resolveEditableTarget). Tests follow the repo idiom: slice a pure helper out of content.js source with new Function and assert on it (see tests/clipboard-html-newlines.test.mjs).
Tech Stack: Vanilla browser JS (content script, isolated world), node:test, the actions.json overlay manifest.
Global Constraints
- Content script runs in the browser isolated world; handlers are async and return via
primitiveSuccess(name, obj)/primitiveError(name, code, message, evidence)(existing helpers in content.js). - A new generic primitive MUST be declared in BOTH
overlay.actions.jsontools[]ANDprimitive_dictionary.primitives[], AND wired intoexecuteAction; missing any surface =unknown_actionor catalog-invisible. (verbatim project rule) primitive_dictionaryentries require:support: "supported", non-emptysummary, objectinput_schema,capability_class: "portable",portable: true.- iframe guard (family-wide): if a resolved target is an
<iframe>, discard it and usedocument.activeElement; never piercecontentDocument. - Success flags mean “the event/API call was issued,” not “the effect is confirmed.”
- Bare
clipboard.paste/clipboard.readusenavigator.clipboard.readText();clipboard.write/clipboard.copyusenavigator.clipboard.writeText(). On rejection returnclipboard_read_denied/clipboard_write_deniedwith the browser reason — never silently succeed empty. - No change to
text.insert.
File Structure
extensions/chrome-overlay-runtime/src/content.js— add 5 handlers + 5 dispatch arms; add one pure helperpasteTargetKind(target, activeElement)and oneresolvePasteTarget(...)factored so tests can slice them. Reuse existingsyntheticClipboardEvent,clipboardHtmlFromText,selectEditableContents,resolveEditableTarget,isEditableElement,primitiveSuccess,primitiveError.extensions/chrome-overlay-runtime/actions/overlay.actions.json— 5 entries intools[], 5 inprimitive_dictionary.primitives[].extensions/chrome-overlay-runtime/tests/clipboard-selection-primitives.test.mjs— NEW test file (source-slice tests for the pure helpers + manifest-shape assertions).extensions/chrome-overlay-runtime/tests/bridge-background-action-routing.test.mjs— MODIFY if it has a content-route allow-list, add the 5 names.
Task 1: Manifest declarations for all five primitives
Declares the five primitives in both manifest surfaces so the bridge advertises them and the hosted catalog exposes them. This is inert (no handler yet) but independently reviewable: a reviewer can accept the tool contracts before any behavior exists.
Files:
- Modify:
extensions/chrome-overlay-runtime/actions/overlay.actions.json - Test:
extensions/chrome-overlay-runtime/tests/clipboard-selection-primitives.test.mjs
Interfaces:
-
Produces: five tool names —
text.select,clipboard.copy,clipboard.paste,clipboard.read,clipboard.write— each present intools[]andprimitive_dictionary.primitives[]. -
Step 1: Write the failing test (create the test file)
import assert from "node:assert/strict";
import { readFile } from "node:fs/promises";
import test from "node:test";
const manifest = JSON.parse(
await readFile(
new URL("../actions/overlay.actions.json", import.meta.url),
"utf8",
),
);
const FAMILY = ["text.select", "clipboard.copy", "clipboard.paste", "clipboard.read", "clipboard.write"];
test("all five primitives are advertised in tools[]", () => {
const names = new Set(manifest.tools.map((t) => t.name));
for (const n of FAMILY) assert.ok(names.has(n), `tools[] missing ${n}`);
});
test("all five primitives are in primitive_dictionary with required fields", () => {
const prims = manifest.primitive_dictionary.primitives;
const byName = new Map(prims.map((p) => [p.name, p]));
for (const n of FAMILY) {
const p = byName.get(n);
assert.ok(p, `primitive_dictionary missing ${n}`);
assert.equal(p.support, "supported", `${n} must be supported`);
assert.ok(typeof p.summary === "string" && p.summary.length, `${n} needs summary`);
assert.equal(typeof p.input_schema, "object", `${n} needs input_schema`);
}
});
test("clipboard.read and clipboard.write appear exactly once per surface", () => {
for (const n of ["clipboard.read", "clipboard.write"]) {
assert.equal(manifest.tools.filter((t) => t.name === n).length, 1, `duplicate ${n} in tools[]`);
assert.equal(
manifest.primitive_dictionary.primitives.filter((p) => p.name === n).length,
1,
`duplicate ${n} in primitive_dictionary`,
);
}
});
- Step 2: Run test to verify it fails
Run: node --test extensions/chrome-overlay-runtime/tests/clipboard-selection-primitives.test.mjs Expected: FAIL — missing text.select, clipboard.copy, clipboard.paste; and (if pre-existing) possibly duplicate/handlerless clipboard.read/clipboard.write.
- Step 3: Add the five
tools[]entries
Add to overlay.actions.json tools[] (reconcile any pre-existing clipboard.read/clipboard.write to exactly one entry each):
{ "name": "text.select",
"description": "Select a range on the page (a target's editable contents, or the focused element's contents). Precursor to clipboard.copy.",
"input_schema": { "type": "object", "properties": {
"target": { "type": "object", "description": "Optional locator. Omit to use the focused element." },
"mode": { "type": "string", "enum": ["all"], "default": "all" } },
"additionalProperties": false } },
{ "name": "clipboard.copy",
"description": "Move the current page selection into the system clipboard (page -> clipboard). Dispatches a synthetic copy event so page-side copy handlers run and writes the selection text to the system clipboard.",
"input_schema": { "type": "object", "properties": {
"target": { "type": "object", "description": "Optional locator whose selection to copy. Omit to use the current selection / focused element." } },
"additionalProperties": false } },
{ "name": "clipboard.paste",
"description": "Paste into a DOM element (clipboard -> page). With text: paste that text. Without text: paste the current system clipboard. Dispatches a synthetic paste event at the target (default: focused element); this is the way to write into iframe-hosted editors like Google Docs where text.insert cannot reach.",
"input_schema": { "type": "object", "properties": {
"text": { "type": "string", "description": "Optional. Text to paste. Omit to paste the current system clipboard." },
"target": { "type": "object", "description": "Optional locator to paste into. Omit to use the focused element. An iframe target falls back to the focused inner element." } },
"additionalProperties": false } },
{ "name": "clipboard.read",
"description": "Read the current system clipboard text. Pure clipboard I/O; does not touch the page.",
"input_schema": { "type": "object", "properties": {}, "additionalProperties": false } },
{ "name": "clipboard.write",
"description": "Write text to the system clipboard. Pure clipboard I/O; does not touch the page.",
"input_schema": { "type": "object", "required": ["text"], "properties": {
"text": { "type": "string" } }, "additionalProperties": false } }
- Step 4: Add the five
primitive_dictionary.primitives[]entries
For each, add (mirroring the text.insert dictionary shape) with support: "supported", capability_class: "portable", portable: true, reason: null, a summary, and the same input_schema as the tools entry. Example for clipboard.paste:
{ "name": "clipboard.paste", "support": "supported", "reason": null,
"capability_class": "portable", "portable": true,
"summary": "Paste text (given, or the system clipboard) into a DOM element via a synthetic paste event; reaches iframe-hosted editors.",
"input_schema": { "type": "object", "properties": {
"text": { "type": "string" },
"target": { "type": "object", "description": "Optional. Omit to use the focused element." } },
"additionalProperties": false } }
Repeat for text.select, clipboard.copy, clipboard.read, clipboard.write with their matching schemas and one-line summaries.
- Step 5: Run test to verify it passes
Run: node --test extensions/chrome-overlay-runtime/tests/clipboard-selection-primitives.test.mjs Expected: PASS (3 manifest tests).
- Step 6: Commit
git add extensions/chrome-overlay-runtime/actions/overlay.actions.json extensions/chrome-overlay-runtime/tests/clipboard-selection-primitives.test.mjs
git commit -m "feat(primitives): declare clipboard/selection family in both manifest surfaces"
Task 2: Pure target-resolution helper + iframe guard
The one piece of non-trivial branching (which element to dispatch at, with the iframe guard) is factored into a pure function so it can be unit-tested by source-slicing, matching the repo’s test idiom.
Files:
- Modify:
extensions/chrome-overlay-runtime/src/content.js(addpasteTargetKind) - Test:
extensions/chrome-overlay-runtime/tests/clipboard-selection-primitives.test.mjs
Interfaces:
-
Produces:
pasteTargetKind(resolved, activeElement)→ returns{ target, target_kind }wheretarget_kindis"resolved-locator"whenresolvedis a non-iframe element, else"activeElement"(used whenresolvedis null OR an iframe). -
Step 1: Write the failing test (append to the test file)
const contentSource = await readFile(new URL("../src/content.js", import.meta.url), "utf8");
const slice = (name) => {
const start = contentSource.indexOf(`const ${name} =`);
assert.ok(start >= 0, `${name} must exist in content.js`);
const end = contentSource.indexOf("\n };", start);
return contentSource.slice(start, end + 4);
};
test("pasteTargetKind falls back to activeElement for null or iframe", () => {
const src = slice("pasteTargetKind");
const pasteTargetKind = new Function(`${src} return pasteTargetKind;`)();
const active = { tagName: "DIV" };
const iframe = { tagName: "IFRAME" };
const input = { tagName: "INPUT" };
assert.deepEqual(pasteTargetKind(null, active), { target: active, target_kind: "activeElement" });
assert.deepEqual(pasteTargetKind(iframe, active), { target: active, target_kind: "activeElement" });
assert.deepEqual(pasteTargetKind(input, active), { target: input, target_kind: "resolved-locator" });
});
- Step 2: Run to verify it fails
Run: node --test extensions/chrome-overlay-runtime/tests/clipboard-selection-primitives.test.mjs Expected: FAIL — “pasteTargetKind must exist in content.js”.
- Step 3: Add the helper to content.js (near
syntheticClipboardEvent, ~line 3308)
const pasteTargetKind = (resolved, activeElement) => {
const isIframe = resolved && (resolved.tagName === "IFRAME" || resolved.tagName === "iframe");
if (!resolved || isIframe) {
return { target: activeElement, target_kind: "activeElement" };
}
return { target: resolved, target_kind: "resolved-locator" };
};
- Step 4: Run to verify it passes
Run: node --test extensions/chrome-overlay-runtime/tests/clipboard-selection-primitives.test.mjs Expected: PASS.
- Step 5: Commit
git add extensions/chrome-overlay-runtime/src/content.js extensions/chrome-overlay-runtime/tests/clipboard-selection-primitives.test.mjs
git commit -m "feat(primitives): pure paste-target resolver with iframe guard"
Task 3: clipboard.paste handler + dispatch
Implements the highest-value primitive (the Google write unblock) end to end, wired into executeAction.
Files:
- Modify:
extensions/chrome-overlay-runtime/src/content.js
Interfaces:
- Consumes:
pasteTargetKind(Task 2),syntheticClipboardEvent,resolveEditableTarget,primitiveSuccess,primitiveError. -
Produces:
clipboardPaste(args)→ success{ pasted: true, inserted_length, input_method: "synthetic-paste", default_prevented, target_kind, source }; errorsno_paste_target,clipboard_read_denied. - Step 1: Add the handler (after
textInsert, ~line 3380)
const clipboardPaste = async (args = {}) => {
const resolved = args.target ? resolveEditableTarget(args.target) : null;
const { target, target_kind } = pasteTargetKind(resolved, document.activeElement);
if (!target) {
return primitiveError("clipboard.paste", "no_paste_target",
"No focused or resolvable element to paste into; click into the editor first.", {});
}
let payload = args.text;
let source = "argument";
if (payload === undefined || payload === null) {
source = "system-clipboard";
try {
payload = await navigator.clipboard.readText();
} catch (error) {
return primitiveError("clipboard.paste", "clipboard_read_denied",
`Could not read the system clipboard: ${error?.message || error}`, {});
}
}
payload = String(payload);
target.focus?.();
const pasteEvent = syntheticClipboardEvent(payload);
target.dispatchEvent(pasteEvent);
return primitiveSuccess("clipboard.paste", {
pasted: true,
inserted_length: payload.length,
input_method: "synthetic-paste",
default_prevented: pasteEvent.defaultPrevented,
target_kind,
source,
});
};
- Step 2: Add the dispatch arm in
executeAction(near thetext.insertarm, ~line 3576)
} else if (message.name === "clipboard.paste") {
output = await clipboardPaste(message.arguments || {});
- Step 3: Verify content.js still parses
Run: node --check extensions/chrome-overlay-runtime/src/content.js Expected: no output (valid syntax).
- Step 4: Commit
git add extensions/chrome-overlay-runtime/src/content.js
git commit -m "feat(primitives): clipboard.paste handler (iframe write path)"
Task 4: clipboard.read and clipboard.write handlers + dispatch
The two pure clipboard-I/O primitives.
Files:
- Modify:
extensions/chrome-overlay-runtime/src/content.js
Interfaces:
-
Produces:
clipboardRead()→{ text, length }orclipboard_read_denied;clipboardWrite(args)→{ written: true, length }orclipboard_write_denied. -
Step 1: Add both handlers (after
clipboardPaste)
const clipboardRead = async () => {
try {
const text = await navigator.clipboard.readText();
return primitiveSuccess("clipboard.read", { text, length: text.length });
} catch (error) {
return primitiveError("clipboard.read", "clipboard_read_denied",
`Could not read the system clipboard: ${error?.message || error}`, {});
}
};
const clipboardWrite = async (args = {}) => {
const text = String(args.text ?? "");
try {
await navigator.clipboard.writeText(text);
return primitiveSuccess("clipboard.write", { written: true, length: text.length });
} catch (error) {
return primitiveError("clipboard.write", "clipboard_write_denied",
`Could not write the system clipboard: ${error?.message || error}`, {});
}
};
- Step 2: Add the dispatch arms in
executeAction
} else if (message.name === "clipboard.read") {
output = await clipboardRead();
} else if (message.name === "clipboard.write") {
output = await clipboardWrite(message.arguments || {});
- Step 3: Verify content.js parses
Run: node --check extensions/chrome-overlay-runtime/src/content.js Expected: no output.
- Step 4: Commit
git add extensions/chrome-overlay-runtime/src/content.js
git commit -m "feat(primitives): clipboard.read and clipboard.write handlers"
Task 5: text.select and clipboard.copy handlers + dispatch
The page-selection primitive and the selection→clipboard bridge.
Files:
- Modify:
extensions/chrome-overlay-runtime/src/content.js
Interfaces:
- Consumes:
selectEditableContents,resolveEditableTarget,pasteTargetKind. -
Produces:
textSelect(args)→{ selected: true, selected_length, target_kind };clipboardCopy(args)→{ copied: true, copied_length, clipboard_write }. - Step 1: Add both handlers (after
clipboardWrite)
const textSelect = (args = {}) => {
const resolved = args.target ? resolveEditableTarget(args.target) : null;
const { target, target_kind } = pasteTargetKind(resolved, document.activeElement);
if (!target) {
return primitiveError("text.select", "no_select_target",
"No focused or resolvable element to select.", {});
}
target.focus?.();
const selected = selectEditableContents(target, "replace");
return primitiveSuccess("text.select", {
selected: true,
selected_length: (selected || "").length,
target_kind,
});
};
const clipboardCopy = async (args = {}) => {
const resolved = args.target ? resolveEditableTarget(args.target) : null;
const { target } = pasteTargetKind(resolved, document.activeElement);
// page-side copy handlers (e.g. Google) run on the synthetic event
const copyEvent = new ClipboardEvent("copy", { bubbles: true, cancelable: true, composed: true });
target?.dispatchEvent?.(copyEvent);
const selectionText = String(document.getSelection?.() || "");
let clipboard_write = "ok";
try {
if (selectionText) await navigator.clipboard.writeText(selectionText);
else clipboard_write = "empty_selection";
} catch (error) {
clipboard_write = "denied";
}
return primitiveSuccess("clipboard.copy", {
copied: true,
copied_length: selectionText.length,
clipboard_write,
});
};
- Step 2: Add the dispatch arms in
executeAction
} else if (message.name === "text.select") {
output = textSelect(message.arguments || {});
} else if (message.name === "clipboard.copy") {
output = await clipboardCopy(message.arguments || {});
- Step 3: Verify content.js parses
Run: node --check extensions/chrome-overlay-runtime/src/content.js Expected: no output.
- Step 4: Commit
git add extensions/chrome-overlay-runtime/src/content.js
git commit -m "feat(primitives): text.select and clipboard.copy handlers"
Task 6: Routability allow-list + packaging + full suite
Ensures the five primitives route to the content script and ship in the package, and the whole suite is green.
Files:
- Modify:
extensions/chrome-overlay-runtime/tests/bridge-background-action-routing.test.mjs(if it has a content-route allow-list) -
Test: whole extension test suite
- Step 1: Check for a content-route allow-list
Run: grep -n "text.insert\|content.*route\|allow" extensions/chrome-overlay-runtime/tests/bridge-background-action-routing.test.mjs Expected: shows whether text.insert (a content primitive) is in an explicit list. If yes, the five new names must join it.
- Step 2: Add the five names to the allow-list (only if Step 1 found one)
Add "text.select", "clipboard.copy", "clipboard.paste", "clipboard.read", "clipboard.write" alongside text.insert in that list.
- Step 3: Run the full extension test suite
Run: node --test extensions/chrome-overlay-runtime/tests/ Expected: PASS — all existing tests plus the new clipboard-selection-primitives.test.mjs.
- Step 4: Run the packaging test
Run: node --test tests/package-extension.test.mjs Expected: PASS (content.js/manifest changes are in already-packaged files; no new files to add to the package list, so this should stay green).
- Step 5: Commit
git add -A extensions/chrome-overlay-runtime/tests/
git commit -m "test(primitives): route + suite coverage for clipboard/selection family"
Task 7: Live validation on Google Docs (the acceptance bar)
The unit tests prove wiring and pure logic; the real acceptance is a live paste into a Google Doc. This task is manual/supervised (needs a running browser on 0.1.148+ with the rebuilt extension) and is the gate before promoting any productivity map’s write action.
Steps (supervised, not automated):
- Step 1: Rebuild + reload the extension from this branch (the released zip or an unpacked checkout — a bridge restart alone does not reload content.js).
- Step 2: Open a Google Doc;
pointer.clickinto the canvas to focus the iframe target. - Step 3: Call
clipboard.paste { text: "hello from clipboard.paste" }; then readdocs.readand assert the body contains the text. Record the result. - Step 4: Cross-app:
clipboard.write { text: "transfer probe" }, click the Docs canvas,clipboard.paste {}(bare),docs.readcontains it. - Step 5: iframe guard: call
clipboard.paste { text, target: <the iframe selector> }; assert it still pastes (does not returntarget_not_editable). - Step 6: Record findings in the map/notes; only after this passes do the productivity maps gain write actions (task #55).
Self-Review
Spec coverage: All five primitives (Tasks 1,3,4,5) ✓; iframe guard (Task 2, reused in 3/5) ✓; optional text + system-clipboard bare mode (Task 3) ✓; read/write implemented for real + reconciled to one declaration (Tasks 1,4) ✓; both manifest surfaces (Task 1) ✓; error codes no_paste_target/clipboard_read_denied/clipboard_write_denied (Tasks 3,4) ✓; routability + packaging (Task 6) ✓; live Docs acceptance (Task 7) ✓. No gaps.
Placeholder scan: No TBD/TODO; every code step shows the code; every run step shows the command + expected output.
Type consistency: pasteTargetKind(resolved, activeElement) returns {target, target_kind} — consumed identically in Tasks 3 and 5. Handler names (clipboardPaste, clipboardRead, clipboardWrite, textSelect, clipboardCopy) match their dispatch arms. Success/error field names consistent across tasks and the spec.
Note for implementer: Line numbers are approximate (content.js is large and evolves) — locate by the named anchors (syntheticClipboardEvent, textInsert, the text.insert dispatch arm) rather than trusting exact line numbers. Verify each new handler by node --check; the browser-only handlers are validated live in Task 7, not by unit tests (only the pure pasteTargetKind and the manifest shapes are unit-tested, matching the repo idiom).