clipboard.paste optional html argument — Design
Date: 2026-07-05 Author: Tempest (Zara Chen) Status: Approved (Yaniv, voice, 2026-07-05) — “the paste HTML is a wonderful idea… in a document is precisely what we need.” Ready for implementation plan. Repo: actions.json.dev (extension runtime primitive)
Goal
Let a clipboard.paste caller supply the exact text/html clipboard flavor, instead of the primitive always deriving it from the plain text as <p>/<br>. This unblocks pasting structured content that the receiving editor expands according to HTML semantics — most importantly a <table> into Google Sheets (which becomes a real multi-column range) and rich runs into Slides/Docs.
Motivation (live-verified 2026-07-05)
Pasting a TSV block (\t cols, \n rows) into Google Sheets via clipboard.paste put ALL data into column A — Sheets ignored the tabs. Root cause, traced in content.js: syntheticClipboardEvent(text) sets the text/html flavor via clipboardHtmlFromText(text), which emits only <p>…<br>…</p> — never a <table>. Google Sheets reads that html flavor as a single paragraph with literal tab characters, so every row collapses into one cell of column A (screenshot-confirmed: range came in as A1:A3, “Count: 3”).
Sheets’ paste handler DOES expand an HTML <table> into a real range (<tr>→row, <td>→column). The same is true for Slides text boxes and Docs rich content. So the fix is not Sheets-specific: give the caller a way to hand clipboard.paste the exact text/html payload.
Design Decision (locked)
Add an optional html string arg to clipboard.paste:
- When
htmlis provided, the synthetic paste event’stext/htmlflavor is exactly that string (not derived).text/plainremainsargs.text(the plain fallback the editor uses if it ignores html). - When
htmlis omitted, behavior is unchanged —text/htmlis derived from the plain text via the existingclipboardHtmlFromText(back-compat: the Docsdocs.appendpath and every current caller keep working identically). htmlis a raw string the caller controls; the caller is responsible for its correctness (e.g. a valid<table>). The primitive stays generic and dumb — app-specific HTML construction lives in the MAP (mirrors thepage.fetchdecision: parsing/generation belongs in maps, not primitives).textbecomes effectively optional WHENhtmlis given, but for the system-clipboard fallback path (textomitted →navigator.clipboard.readText) we keeptextas the plain flavor. If bothtextandhtmlare omitted, the plain text is read from the system clipboard and html is derived from it (fully unchanged path).
Contract
clipboard.paste {
text?: string, // plain flavor; omitted => read system clipboard
html?: string, // NEW: exact text/html flavor; omitted => derived from text
target?: locator
}
Behavior change is isolated to how the text/html DataTransfer entry is set:
syntheticClipboardEvent(text, html)— whenhtmlis a string, use it verbatim forsetData("text/html", html); otherwisesetData("text/html", clipboardHtmlFromText(text))as today.clipboardPastethreadsargs.htmlthrough tosyntheticClipboardEvent.
Return payload gains one field: html_provided: boolean (whether the caller supplied an explicit html flavor), so callers/tests can confirm the path taken. Everything else in the return is unchanged.
Architecture / Wiring (surfaces to touch)
- content.js
syntheticClipboardEvent: add a second paramhtml; when it’s a non-null string,setData("text/html", html)instead of the derived value. Keep the single call site ininsertTextIntoEditablepassing onlytext(that path never wants a custom html flavor —text.insertis plain). - content.js
clipboardPaste: readargs.html; pass it tosyntheticClipboardEvent(payload, args.html). Addhtml_providedto the success payload. The system-clipboard fallback (notext) still passesargs.html(which may itself be provided independently oftext). - overlay.actions.json
tools[]:clipboard.pasteinput_schema gains an optionalhtmlstring property (description: exact text/html flavor; use for tables/rich runs).textstays optional. - overlay.actions.json
primitive_dictionary.primitives[]: theclipboard.pasteentry’sinput_schemagains the same optionalhtml. - Routing: unchanged —
clipboard.pasteis already a content-script primitive.
How the maps consume it (shape, not in this primitive’s scope)
sheets.range.paste_tsv (a workflow action, next task) will build BOTH flavors from its tsv input:
- plain
text= the TSV as-is (tab/newline); html= a<table>where each\n-row is a<tr>and each\t-cell is a<td>(HTML-escaped). Thenclipboard.paste { text, html, target: <anchor> }. Sheets picks the<table>and expands the range. Slides/Docs rich paste will use the samehtmlarg with their own HTML.
Testing
- Unit (source-slice
syntheticClipboardEvent):- given
htmlstring → the constructed DataTransfer’stext/htmlequals that string exactly, andtext/plainequals the text arg. - given
htmlomitted →text/htmlequalsclipboardHtmlFromText(text)(back-compat). - The function is source-sliceable the way the page-fetch test slices
isSameOrigin; if DataTransfer isn’t constructible in the test env, assert on the branch logic via a thin injectable shim (see plan).
- given
- Manifest-shape:
clipboard.pastein both surfaces has anhtmlproperty of type string in its input_schema (extend the existing manifest-shape test). - Routing:
clipboard.pastestill NOT in the background action set (content-routed) — unchanged assertion. - Live (screenshot): paste a
<table>html into the test Sheet at an anchor → screenshot shows a real multi-column range (B/C populated, not column A). Thensheets.readreturns multiple cells per row (also validates the multi-column read parse that is currently unproven). - Packaging test stays green (content.js/manifest are already-packaged files).
Out of Scope
- The
sheets.range.paste_tsv/ Slides / Docs map actions that CONSUME this — their own work (task #55). - Any change to
text.insert(stays plain). - Reading the system clipboard’s html flavor (we only WRITE a custom html flavor; reading richer clipboard types is unneeded here).
- Changing the derived-html default (
clipboardHtmlFromTextstays exactly as-is for the omitted-htmlpath — back-compat is a hard requirement).