Clipboard & Selection Primitive Family — Design
Date: 2026-07-05 Author: Tempest (Zara Chen) Status: Approved (Yaniv, voice, 2026-07-05) — build all five together — ready for plan Repo: actions.json.dev (extension runtime primitives)
Goal
Add a complete, orthogonal family of clipboard/selection primitives so agents can select text on a page, move it to and from the system clipboard, and write it into editors — including editors whose real input target lives inside an iframe (Google Docs / Sheets / Slides). This unblocks the Google-productivity write path (task #55) and provides the pure cross-app transfer flow (select → copy → paste).
The model (what each primitive touches)
Yaniv’s organizing principle — primitives split by whether they touch the page, the system clipboard, or bridge the two:
| Primitive | Moves | Touches |
|---|---|---|
text.select | — | the PAGE only (selects a range) |
clipboard.copy | selection → clipboard | PAGE + clipboard |
clipboard.paste | clipboard → DOM element | clipboard + PAGE |
clipboard.read | clipboard → out | CLIPBOARD only (no page) |
clipboard.write | in → clipboard | CLIPBOARD only (no page) |
read/write are pure clipboard I/O — no page interaction. copy/paste are the bridges. select is the page-side prerequisite for copy. Left-to-right, the cross-app transfer path is: select → copy → (switch app) → paste.
Motivation
Google’s editors render the editable surface inside an iframe event-target. text.insert fails on them: it resolves the target to the <iframe> element, fails the isEditableElement gate, and returns target_not_editable (tag_name: iframe) before dispatching. content.js already contains the paste machinery — syntheticClipboardEvent + clipboardHtmlFromText build a real ClipboardEvent("paste") carrying text/plain + text/html — but it is gated and only reachable inside text.insert. Google’s editor listens for paste (and copy) on its internal target and does the work itself. So the unlock is primitives that dispatch those events at the FOCUSED target without the editable gate. read/write are already advertised in the manifest but have no handler; this implements them for real.
Design Decisions (locked)
- Build all five together — they are small and only make sense as a group; paste alone would leave
copy/selectas obvious holes in the transfer flow. - Namespacing:
text.select(page-selection, sibling oftext.insert);clipboard.copy/clipboard.paste/clipboard.read/clipboard.write. - Optional target + optional payload where sensible (details per primitive below). The iframe guard applies to every primitive that resolves a target: if a resolved target is an
<iframe>, do NOT bail and do NOT piercecontentDocument(cross-origin risk) — fall through todocument.activeElement.
Contracts
text.select { target?, mode? }
Select a range on the page.
targetgiven → resolve + focus, select its editable contents (reuseselectEditableContents); if it’s an input/textarea, select its value range.targetomitted → select the current focused element’s contents.mode:"all"(default) selects the whole element; future modes reserved.- Returns
{ selected: true, selected_length, target_kind }.
clipboard.copy { target? }
Move the current selection into the system clipboard (page → clipboard).
- Reads the current DOM selection (or the given target’s selection after select), then writes it to the system clipboard via
navigator.clipboard.writeText(). Also dispatches a syntheticcopyClipboardEventat the target so page-side copy handlers (e.g. Google) run. targetomitted → operate ondocument.activeElement/ current selection.- Returns
{ copied: true, copied_length, source: "selection", clipboard_write: <ok|denied> }. If the system-clipboard write is denied, the synthetic copy event may still have populated it page-side — report both.
clipboard.paste { text?, target? }
Move the clipboard (or given text) into a DOM element (clipboard → page).
textgiven → paste that exact text (synthetic event carries the data; no clipboard read needed).textomitted → paste the CURRENT system clipboard vianavigator.clipboard.readText(). If denied/blocked →clipboard_read_deniedwith the browser reason; never silently paste empty.targetgiven → resolve + focus (iframe guard applies); omitted →document.activeElement. If none →no_paste_target.- Build with
syntheticClipboardEvent(payload)(plain + HTML), dispatch at target. Returns{ pasted: true, inserted_length, input_method: "synthetic-paste", default_prevented, target_kind, source: "argument"|"system-clipboard" }.pasted:true= dispatched, not guaranteed inserted — caller VERIFIES with a read.
clipboard.read {}
Pure clipboard read — no page interaction.
await navigator.clipboard.readText(). Returns{ text, length }orclipboard_read_denied.
clipboard.write { text }
Pure clipboard write — no page interaction.
await navigator.clipboard.writeText(text). Returns{ written: true, length }orclipboard_write_denied.
Architecture / Wiring (three surfaces per primitive)
Each of the five is a generic primitive → declared in BOTH manifest tool surfaces and wired into content-script dispatch (the standard two-surface rule):
- content.js — five handlers (
textSelect,clipboardCopy,clipboardPaste,clipboardRead,clipboardWrite), reusingsyntheticClipboardEvent/clipboardHtmlFromText/selectEditableContentswhere applicable, plus five dispatch arms inexecuteAction. - overlay.actions.json
tools[]— five entries with input schemas (optionaltext/targetwhere specified). - overlay.actions.json
primitive_dictionary.primitives[]— five entries, each withsummary,support: "supported", objectinput_schema,x_actions.handler. - Content-route allow-list in the routability test updated for all five.
Note: clipboard.read/clipboard.write already appear advertised somewhere in the manifest but lack a content.js handler — reconcile so there is exactly one declaration per surface and a real handler.
Data Flow
Google write (known string): pointer.click into the Docs canvas (focuses the iframe target) → clipboard.paste { text } → Google inserts → verify via docs.read.
Cross-app transfer (Sheets → Docs): text.select the source range in Sheets → clipboard.copy (selection → clipboard) → switch/click into the Docs canvas → clipboard.paste {} (bare, reads clipboard) → verify.
Pure clipboard staging: clipboard.write { text } to seed the clipboard → later clipboard.paste {} anywhere.
Error Handling
no_paste_target— nothing focused/resolvable to paste into.clipboard_read_denied/clipboard_write_denied— the async clipboard API was blocked (permission/focus/not-allowed); surface the browser reason. Never silently succeed with empty data.default_prevented: false+ unchanged content after paste/copy means the page did not accept the event; caller verifies and reports, does not assume success.- Every mutation primitive’s success flag means “the event/API call was issued,” not “the effect is confirmed” — verification is the caller’s job (project discipline).
Testing
- Docs write (primary acceptance): click canvas →
clipboard.paste { text }→docs.readbody contains the text. - Cross-app transfer:
text.select+clipboard.copyon a source →clipboard.paste {}on a target → assert the text moved. - Pure clipboard:
clipboard.write { text }thenclipboard.readreturns it. - Normal input:
<textarea>with explicittarget→ select/copy/paste → assert value. - iframe guard: pass an
<iframe>selector astarget→ still operates on the focused inner target, notarget_not_editable. - Denied clipboard:
navigator.clipboard.readText/writeTextrejection →clipboard_read_denied/clipboard_write_denied, not silent success. - Packaging + routability tests updated so all five ship and route.
Out of Scope
- The Sheets/Slides READ projections and the productivity maps’ write actions (task #55) — they CONSUME these primitives but are their own work.
- Any change to
text.insert(left as-is;clipboard.pasteis the iframe path). - Rich non-text clipboard formats (images, files) — text/plain + text/html only.