@plannotator/ui 0.52.0 → 0.53.0

package/types.ts

@@ -386,6 +386,28 @@ export interface CodeAnnotation {
    * inline on the current diff and never posted as an inline PR comment.
    */
   outdated?: boolean;
+  /**
+   * Code review only: a comment made by selecting text in a Markdown file's
+   * rendered preview. Always file-scoped (`scope: 'file'`); `lineStart` /
+   * `lineEnd` are the file-comment sentinels, not source lines. Exported with
+   * the quoted text; in PR mode it goes into the review body, never inline.
+   * Additive: annotations without it behave exactly as before.
+   */
+  markdownPreview?: MarkdownPreviewAnchor;
+}
+
+/** Where a comment made in a rendered Markdown preview points (see `CodeAnnotation.markdownPreview`). */
+export interface MarkdownPreviewAnchor {
+  /** The rendered text the reviewer selected. */
+  originalText: string;
+  /** The preview view it was made in: the rendered diff or the whole new version. */
+  view: 'diff' | 'whole';
+  /** In the rendered diff: the kind of section the selection started in. */
+  diffContext?: 'added' | 'removed' | 'modified' | 'unchanged';
+  /** web-highlighter positions, valid only in the view it was made in;
+   *  other views re-anchor by text. */
+  startMeta?: AnnotationTextMeta;
+  endMeta?: AnnotationTextMeta;
 }
 
 /** Token-level metadata passed from selection to annotation creation. */
@@ -520,3 +542,29 @@ export type {
   MentionSource,
   MentionTrigger,
 } from './utils/mentions';
+
+/**
+ * The composer handed to the host (opt-in `onHostDraft` on `Viewer` and
+ * `HtmlViewer`; Plannotator supplies neither). With it a viewer draws no
+ * toolbar or composer of its own: it reports what a comment would be on, and
+ * the host writes the comment, saves it, and draws it as saved through
+ * `annotations` or `applySharedAnnotations`.
+ */
+export interface HostDraft {
+  /** The annotation a comment here would carry, with an empty `text`. */
+  annotation: Annotation;
+  /**
+   * `'selection'`: a text selection settled; the host offers its own Comment
+   * (a phone's edit menu). `'compose'`: open the composer now (a pinpoint
+   * tap, Comment mode, an HTML pin).
+   */
+  intent: 'selection' | 'compose';
+  /** What it is on, as a composer names it (Plannotator's pinpoint label: "Button", a heading's words). Absent for text. */
+  label?: string;
+  /**
+   * Drop the draft: its pending highlight or pin goes. The host calls it when
+   * the person cancels, and after the save, before it draws the saved
+   * annotation. A draft already replaced by a newer one ignores it.
+   */
+  cancel: () => void;
+}

package/utils/agentClosed.ts

@@ -31,3 +31,29 @@ export function agentClosedSubtitle(unsentAnnotations: number, surface: AgentClo
   const comments = unsentAnnotations === 1 ? 'Your comment is' : `Your ${unsentAnnotations} comments are`;
   return `The agent closed this review. ${comments} saved as a draft. ${RESTORE[surface]}`;
 }
+
+/**
+ * Copy for a plan review closed because plan mode or the agent session ended
+ * (`session-closed` with `by: "session"`, Pi's plan review), not because the
+ * agent asked to close it. Neutral on purpose: it also runs on /reload and
+ * session switches, after which plan mode may come back.
+ */
+export const SESSION_CLOSED_TITLE = 'Review Closed';
+
+export function sessionClosedSubtitle(unsentAnnotations: number): string {
+  const ended = 'The agent session that opened this plan review ended.';
+  if (unsentAnnotations <= 0) return ended;
+  const comments = unsentAnnotations === 1 ? 'Your comment is' : `Your ${unsentAnnotations} comments are`;
+  return `${ended} ${comments} saved.`;
+}
+
+/** Title and subtitle for a closed review, by who closed it. */
+export function closedReviewCopy(
+  closed: { unsentAnnotations: number; by?: 'agent' | 'session' },
+  surface: AgentClosedSurface = 'document',
+): { title: string; subtitle: string } {
+  if (closed.by === 'session') {
+    return { title: SESSION_CLOSED_TITLE, subtitle: sessionClosedSubtitle(closed.unsentAnnotations) };
+  }
+  return { title: AGENT_CLOSED_TITLE, subtitle: agentClosedSubtitle(closed.unsentAnnotations, surface) };
+}

package/utils/agentToolSetting.ts

@@ -4,13 +4,16 @@
  * the POST /api/config write that changes it.
  *
  * Only a Plannotator server that knows the session's tool host sends
- * `agentToolHost` (the Claude Code mod, Pi, OpenCode 2). Everything else, an
+ * `agentToolHost` (the Claude Code mod, Pi, Oh My Pi, OpenCode 2). Everything else, an
  * older server, OpenCode 1, Codex, a `@plannotator/ui` host such as
  * Workspaces, parses to undefined, and no toggle or offer is shown.
  */
 
-/** The hosts that register the `plannotator` agent tool. */
-export type AgentToolHost = 'claude-code' | 'pi' | 'opencode';
+/**
+ * The hosts that register the `plannotator` agent tool. `oh-my-pi` is the Pi
+ * extension running inside Oh My Pi, where the tool is on by default.
+ */
+export type AgentToolHost = 'claude-code' | 'pi' | 'oh-my-pi' | 'opencode';
 
 export interface AgentToolSetting {
   readonly host: AgentToolHost;
@@ -23,7 +26,7 @@ export interface AgentToolSetting {
 }
 
 function isAgentToolHost(value: unknown): value is AgentToolHost {
-  return value === 'claude-code' || value === 'pi' || value === 'opencode';
+  return value === 'claude-code' || value === 'pi' || value === 'oh-my-pi' || value === 'opencode';
 }
 
 /** Reads the agent tool fields out of a `serverConfig` payload, or undefined when the server reports no tool host. */
@@ -79,6 +82,7 @@ export async function saveAgentToolSetting(
 const HOST_NAMES: Record<AgentToolHost, string> = {
   'claude-code': 'Claude Code',
   pi: 'Pi',
+  'oh-my-pi': 'Oh My Pi',
   opencode: 'OpenCode',
 };
 
@@ -90,7 +94,8 @@ export function agentToolHostName(host: AgentToolHost): string {
  * When a change takes effect on this host: the tool list is part of the
  * model's prompt, so each host reads the setting once. Pi reads it per
  * session; the Claude Code mod and the OpenCode plugin decide once per
- * process (when the module or plugin loads), so those take a restart.
+ * process (when the module or plugin loads), so those take a restart, and so
+ * does Oh My Pi, which may keep the extension loaded across its sessions.
  */
 export function agentToolAppliesWhen(host: AgentToolHost): string {
   return host === 'pi' ? 'the next Pi session' : `the next time ${HOST_NAMES[host]} starts`;
@@ -99,10 +104,12 @@ export function agentToolAppliesWhen(host: AgentToolHost): string {
 /**
  * What the tool costs in context. Pi and OpenCode send its full definition
  * with every request; Claude Code defers it behind tool search, so it costs
- * about its name until it is used.
+ * about its name until it is used; Oh My Pi lists it as one line of its
+ * system prompt (about 210 characters, measured on OMP 18.10) and loads the
+ * schema only when the model reads it.
  */
 export function agentToolCostNote(host: AgentToolHost): string {
-  return host === 'claude-code'
-    ? 'Claude Code loads it only when needed.'
-    : 'Adds about 780 tokens to every request.';
+  if (host === 'claude-code') return 'Claude Code loads it only when needed.';
+  if (host === 'oh-my-pi') return 'Oh My Pi lists it in one short line (about 50 tokens) and loads the rest only when needed.';
+  return 'Adds about 780 tokens to every request.';
 }

package/utils/aiProvider.ts

@@ -38,6 +38,13 @@ export interface SessionBridgeInfo {
   host: string;
   status: 'ready' | 'busy' | 'blocked' | 'gone';
   modes: { turn: boolean; transient: boolean };
+  /** `false` when the host never interrupts the session (Stop only stops listening). Absent = it can. */
+  interruptible?: boolean;
+}
+
+/** Whether any listed "Ask this session" provider says it cannot interrupt its session. */
+export function hasNonInterruptibleSession(providers: readonly { sessionBridge?: SessionBridgeInfo }[]): boolean {
+  return providers.some((provider) => provider.sessionBridge?.interruptible === false);
 }
 
 /** Error codes "Ask this session" answers with that the panel turns into actions. */

package/utils/askSessionSetupHint.ts

@@ -0,0 +1,27 @@
+import type { Origin } from '@plannotator/core/agents';
+import { isSessionBridgeProvider, type AIProviderOption } from './aiProvider';
+
+/**
+ * The command that installs the Plannotator extension into Oh My Pi. OMP loads
+ * Pi extensions as OMP plugins; this is the one place the UI names it.
+ */
+export const OMP_EXTENSION_INSTALL_COMMAND = 'omp plugin install @plannotator/pi-extension';
+
+/**
+ * A one-line note for Ask AI when the agent that opened Plannotator COULD
+ * answer "Ask this session" but this session has no bridge to it (#1814).
+ *
+ * Only Oh My Pi qualifies today: origin `oh-my-pi` means the CLI ran from
+ * OMP's shell (OMP exports `OMPCODE` to its bash children), which never has a
+ * bridge, while the Plannotator extension loaded into OMP does. Every other
+ * origin without a bridge either has no way to get one or is already covered,
+ * so it gets no note. A session that has a bridge never shows it.
+ */
+export function askSessionSetupHint(
+  origin: Origin | null | undefined,
+  providers: ReadonlyArray<Pick<AIProviderOption, 'name' | 'sessionBridge'>>,
+): string | null {
+  if (origin !== 'oh-my-pi') return null;
+  if (providers.some(isSessionBridgeProvider)) return null;
+  return `To ask your Oh My Pi session instead, install the Plannotator extension (${OMP_EXTENSION_INSTALL_COMMAND}) and open reviews with its /plannotator-* commands.`;
+}

package/utils/blockTargeting.ts

@@ -247,11 +247,22 @@ export function buildSemanticTargetGraph(container: HTMLElement): SemanticTarget
       continue;
     }
 
-    const codeElement = block.querySelector<HTMLElement>('pre > code.pn-code');
+    // A quote is one text block even when it holds a code fence or a table:
+    // its fence is not a code-block target (whose click would annotate only
+    // the fence), and its table rows are not cells of the quote.
+    const isQuote = block.tagName === 'BLOCKQUOTE';
+    const codeElement = isQuote ? null : block.querySelector<HTMLElement>('pre > code.pn-code');
+    // Inline math in a quote keeps the paragraph rule (the quote targets the
+    // formula, as a paragraph with inline math does); a display-math block
+    // inside a quote is not the quote.
     const mathElement = block.matches('.math-annotatable,[data-math-tex]')
       ? block
-      : block.querySelector<HTMLElement>('.math-annotatable,[data-math-tex]');
-    const table = block.querySelector<HTMLTableElement>('table');
+      : block.querySelector<HTMLElement>(
+          isQuote
+            ? '.math-annotatable:not([data-math-display="true"]),[data-math-tex]:not([data-math-display="true"])'
+            : '.math-annotatable,[data-math-tex]',
+        );
+    const table = isQuote ? null : block.querySelector<HTMLTableElement>('table');
 
     if (codeElement) {
       const target: SemanticTarget = {

package/utils/parser.ts

@@ -382,10 +382,13 @@ export const parseMarkdownToBlocks = (markdown: string, options?: ParseMarkdownO
     const prevLineWasBlank = lastLineWasBlank;
     lastLineWasBlank = false;
 
-    // Headings
-    if (trimmed.startsWith('#')) {
+    // Headings: one to six `#` followed by a space or the end of the line
+    // (CommonMark ATX). `#123 fixed`, `#hashtag` and `#!/bin/sh` are text,
+    // so an issue ref that starts a line keeps its link.
+    const headingMatch = trimmed.match(/^(#{1,6})(?:\s|$)/);
+    if (headingMatch) {
       flush();
-      const level = trimmed.match(/^#+/)?.[0].length || 1;
+      const level = headingMatch[1].length;
       blocks.push({
         id: `block-${currentId++}`,
         type: 'heading',
@@ -449,62 +452,63 @@ export const parseMarkdownToBlocks = (markdown: string, options?: ParseMarkdownO
       continue;
     }
 
-    // Blockquotes — consecutive `>` lines merge into one block so wrapped
-    // paragraph quotes render as a single continuous quote box. A blank line
-    // breaks the blockquote so the next `>` starts a fresh one.
+    // Blockquotes: a run of consecutive `>` lines (blank `>` lines included)
+    // is ONE quote block, the way GitHub renders it: one quote, one bar. A
+    // truly blank line ends the run, so the next `>` starts a fresh quote; a
+    // line without `>` is not a lazy continuation (it starts a paragraph).
     //
-    // Exception: if the stripped content starts with a block-level marker
-    // (list item, heading, code fence, nested blockquote) we do NOT merge.
-    // Our flat block model can't render a list-inside-a-quote as an actual
-    // nested list, so merging would flatten the markers into run-on inline
-    // text. Leaving them as separate blockquote blocks preserves each line's
-    // visual identity (a stacked-box layout) — imperfect but legible. A
-    // proper recursive blockquote parser is tracked as a follow-up.
+    // `content` is the quote's own markdown: each line with its `>` marker and
+    // one following space or tab removed (deeper indentation is kept, so a
+    // fenced code block or a nested list inside the quote keeps its shape) and
+    // trailing whitespace trimmed, one content line per source line. Blank
+    // lines at the quote's edges are dropped (`startLine` moves past leading
+    // ones), so the block's line span is the quote's text. The renderer
+    // (`BlockquoteBlock`) parses `content` again with this function and draws
+    // the inner blocks (paragraphs, code fences, lists, nested quotes) inside
+    // the one quote, while the quote stays a single annotatable block with a
+    // single `data-block-id`.
+    //
+    // GitHub alerts (`> [!KIND]` as the run's first line) are unchanged: the
+    // marker line tags the block, and the body is every later line fully
+    // `>`-stripped and trimmed, empty leading lines skipped, exactly as the
+    // line-by-line merge produced it. AlertBlock renders it.
     if (trimmed.startsWith('>')) {
       flush();
-      const stripped = trimmed.replace(/^>\s*/, '');
-      // List markers require trailing whitespace to avoid matching inline
-      // text like "-hyphen" or "1.5 seconds"; headings, code fences, and
-      // nested blockquote markers don't require it (``` can be followed
-      // directly by a language tag, # can start a dense heading).
-      const blockMarkerRe = /^(?:(?:\*|-|\d+\.)\s|#|```|>)/;
-      const hasBlockMarker = blockMarkerRe.test(stripped);
-      const prevBlock = blocks.length > 0 ? blocks[blocks.length - 1] : null;
-      // Don't merge into a previous blockquote whose content itself starts
-      // with a block marker — otherwise a `> some text` line following a
-      // `> 1. item` line would get glued onto the list-item block.
-      const prevIsMarkerQuote =
-        prevBlock?.type === 'blockquote' && blockMarkerRe.test(prevBlock.content);
-      // Alerts own their body: once a blockquote is tagged as an alert,
-      // subsequent `>` lines always merge into it (until a blank line).
-      // Without this, `> [!NOTE]\n> - item` splits the list item off into
-      // a separate plain quote, losing the callout.
-      const prevIsAlert = prevBlock?.type === 'blockquote' && !!prevBlock.alertKind;
-      const shouldMergeIntoAlert = prevIsAlert && !prevLineWasBlank;
-      const shouldMergeNormal =
-        !hasBlockMarker &&
-        !prevIsMarkerQuote &&
-        !prevLineWasBlank &&
-        prevBlock?.type === 'blockquote';
-      if (shouldMergeIntoAlert || shouldMergeNormal) {
-        prevBlock!.content = prevBlock!.content
-          ? prevBlock!.content + '\n' + stripped
-          : stripped;
-      } else {
-        // GitHub alert marker: a blockquote whose first line is [!KIND].
-        // We strip the marker from content and tag the block; rendering decides the style.
-        const alertMatch = stripped.match(/^\[!(NOTE|TIP|WARNING|CAUTION|IMPORTANT)\]\s*$/i);
+      let runEnd = i;
+      while (runEnd + 1 < lines.length && lines[runEnd + 1].trim().startsWith('>')) runEnd++;
+      const run = lines.slice(i, runEnd + 1);
+      const quoteStartLine = currentLineNum;
+      i = runEnd;
+      const alertMatch = trimmed
+        .replace(/^>\s*/, '')
+        .match(/^\[!(NOTE|TIP|WARNING|CAUTION|IMPORTANT)\]\s*$/i);
+      if (alertMatch) {
+        const body = run.slice(1).reduce((acc, raw) => {
+          const stripped = raw.trim().replace(/^>\s*/, '');
+          return acc ? acc + '\n' + stripped : stripped;
+        }, '');
         blocks.push({
           id: `block-${currentId++}`,
           type: 'blockquote',
-          content: alertMatch ? '' : stripped,
-          alertKind: alertMatch
-            ? (alertMatch[1].toLowerCase() as 'note' | 'tip' | 'warning' | 'caution' | 'important')
-            : undefined,
+          content: body,
+          alertKind: alertMatch[1].toLowerCase() as 'note' | 'tip' | 'warning' | 'caution' | 'important',
           order: currentId,
-          startLine: currentLineNum
+          startLine: quoteStartLine,
         });
+        continue;
       }
+      const inner = run.map((raw) => raw.replace(/^\s*>[ \t]?/, '').trimEnd());
+      let first = 0;
+      while (first < inner.length - 1 && inner[first] === '') first++;
+      let last = inner.length - 1;
+      while (last > first && inner[last] === '') last--;
+      blocks.push({
+        id: `block-${currentId++}`,
+        type: 'blockquote',
+        content: inner.slice(first, last + 1).join('\n'),
+        order: currentId,
+        startLine: quoteStartLine + first,
+      });
       continue;
     }
     
@@ -1024,7 +1028,17 @@ export const exportAnnotationEntry = (ann: any, opts: ElementContextExportOption
  *  a malformed anchor (an older or foreign writer) is skipped, never thrown. */
 const diagramLocationExportLine = (ann: any): string => {
   const anchor = ann?.diagramAnchor === undefined ? null : parseDiagramAnchor(ann.diagramAnchor);
-  return anchor === null ? '' : `${safeInline(diagramAnchorLocationLine(anchor), 600)}\n`;
+  if (anchor !== null) return `${safeInline(diagramAnchorLocationLine(anchor), 600)}\n`;
+  return hostLocationExportLine(ann);
+};
+
+/** A host's own location line for an entry (the Inbox's "At 1:42 (102.4 s of
+ *  7:41)" on a video comment): `exportLocation`, a string the HOST sets on the
+ *  copy it hands the exporter, never stored and never set by Plannotator, so
+ *  every other annotation's output is byte-identical. One line, capped. */
+const hostLocationExportLine = (ann: any): string => {
+  const line = ann?.exportLocation;
+  return typeof line === 'string' && line.trim() !== '' ? `${safeInline(line, 300)}\n` : '';
 };
 
 const lineLabelForAnnotation = (blocks: Block[], ann: any): string | null => {

package/utils/pasteInsert.ts

@@ -0,0 +1,234 @@
+/**
+ * Plain-text paste into our own text fields, inserted by the page.
+ *
+ * Works around a Chrome 155 to 156 bug on macOS, and runs only there
+ * (`chromiumPasteBugAffected`). Remove after Chrome 157 is the stable channel
+ * (it ships the fix).
+ *
+ * Chrome 155 added a check after the `paste` event (Chromium CL 8217390,
+ * commit 4f9d868279, "Ensure default paste behavior doesn't leak changed
+ * clipboard content"): the browser's own insertion is skipped when the
+ * clipboard's sequence token changed while the event ran. On macOS an older
+ * race in ClipboardMac can give the same NSPasteboard changeCount a second
+ * token when a paste starts right after an app wrote the pasteboard and
+ * posted a synthetic ⌘V. Dictation apps (Hex) and text expanders do exactly
+ * that. The `paste` event still carries the right `text/plain`, but
+ * `beforeinput` arrives with empty data and nothing is inserted: the first
+ * dictation after a page load lands, later ones vanish. Fixed in Chromium
+ * main (CL 8503629, commit fc5529f522, crbug 568453825), not before 157.
+ *
+ * So, for a paste into a plain-text field we own (a textarea or a text-like
+ * input) that nothing else handled, that carries no files and has text, the
+ * page cancels the browser's insertion and inserts the text itself with
+ * `execCommand('insertText')` (keeps undo, fires `input`, so React's onChange
+ * runs), else `setRangeText` plus an `input` event. That is what the browser
+ * would have done. It is gated to the affected engine: Safari's execCommand
+ * merges the insertion with the typing before it in the undo stack, so
+ * everywhere else the browser's own paste is kept. Only trusted (real) paste
+ * events are acted on.
+ *
+ * Left native: a paste that a handler already cancelled (image paste to
+ * attach), one that carries files (paste-to-attach keeps working; the
+ * browser inserts the text beside them), an empty one, a field that is
+ * read-only or disabled, one that is not focused, one mid IME composition,
+ * contenteditable and code editors (CodeMirror, Pierre's editor, the agent
+ * terminal's helper textarea), and a field marked `data-native-paste`.
+ */
+
+/** Input types the page can insert into with a caret (email and number have no selection API). */
+const TEXT_INPUT_TYPES = new Set(['text', 'search', 'url', 'tel', 'password']);
+
+/** Editors that read the paste themselves through a hidden textarea or own their own model. */
+const NATIVE_PASTE = '[data-native-paste], .xterm, .cm-editor, .monaco-editor';
+
+export type PlainTextField = HTMLTextAreaElement | HTMLInputElement;
+
+export interface PasteInsertion {
+  field: PlainTextField;
+  text: string;
+  start: number;
+  end: number;
+}
+
+type PasteLike = Pick<ClipboardEvent, 'defaultPrevented' | 'clipboardData' | 'target'> & {
+  composedPath?: () => EventTarget[];
+};
+
+function plainTextField(target: EventTarget | null | undefined): PlainTextField | null {
+  if (!target || typeof (target as Node).nodeType !== 'number') return null;
+  const el = target as Element;
+  const view = el.ownerDocument?.defaultView;
+  if (!view) return null;
+  if (el instanceof view.HTMLTextAreaElement) return el;
+  if (el instanceof view.HTMLInputElement && TEXT_INPUT_TYPES.has(el.type)) return el;
+  return null;
+}
+
+function carriesFiles(data: DataTransfer): boolean {
+  if ((data.files?.length ?? 0) > 0) return true;
+  for (const item of Array.from(data.items ?? [])) {
+    if (item.kind === 'file') return true;
+  }
+  return false;
+}
+
+function focused(field: PlainTextField): boolean {
+  const root = field.getRootNode() as Document | ShadowRoot;
+  return 'activeElement' in root && root.activeElement === field;
+}
+
+/** Cut to `room` UTF-16 units without splitting a surrogate pair. */
+function truncate(text: string, room: number): string {
+  if (text.length <= room) return text;
+  let cut = room;
+  const last = text.charCodeAt(cut - 1);
+  if (cut > 0 && last >= 0xd800 && last <= 0xdbff) cut -= 1;
+  return text.slice(0, cut);
+}
+
+/**
+ * What the page should insert for this paste, or null to leave it to the
+ * browser. Pure apart from reading the event and the field.
+ */
+export function plainTextPasteInsertion(event: PasteLike, composing = false): PasteInsertion | null {
+  if (event.defaultPrevented || composing) return null;
+  const data = event.clipboardData;
+  if (!data) return null;
+  const path = event.composedPath?.() ?? [];
+  const field = plainTextField(path[0] ?? event.target);
+  if (!field) return null;
+  if (field.readOnly || field.disabled) return null;
+  if (field.closest(NATIVE_PASTE)) return null;
+  if (!focused(field)) return null;
+  if (carriesFiles(data)) return null;
+  let text = data.getData('text/plain');
+  if (!text) return null;
+  // What Chrome does with line breaks: a textarea keeps each as \n, a one-line input turns each into a space.
+  text = text.replace(/\r\n?/g, '\n');
+  if (field.tagName !== 'TEXTAREA') text = text.replace(/\n/g, ' ');
+  if (!text) return null;
+  const start = field.selectionStart;
+  const end = field.selectionEnd;
+  if (start === null || end === null) return null;
+  if (field.maxLength >= 0) {
+    const room = field.maxLength - (field.value.length - (end - start));
+    if (room <= 0) return null; // the browser inserts nothing either
+    text = truncate(text, room);
+    if (!text) return null;
+  }
+  return { field, text, start, end };
+}
+
+/** Insert as typing would: an undo step and an `input` event. */
+export function insertPastedText({ field, text, start, end }: PasteInsertion): void {
+  const doc = field.ownerDocument;
+  let inserted = false;
+  try {
+    inserted = typeof doc.execCommand === 'function' && doc.execCommand('insertText', false, text) === true;
+  } catch {
+    inserted = false;
+  }
+  if (inserted) return;
+  field.setRangeText(text, start, end, 'end');
+  const caret = start + text.length;
+  field.setSelectionRange(caret, caret); // some engines put the caret elsewhere after setRangeText
+  const view = doc.defaultView;
+  const event =
+    view && typeof view.InputEvent === 'function'
+      ? new view.InputEvent('input', { bubbles: true, inputType: 'insertFromPaste', data: text })
+      : new Event('input', { bubbles: true });
+  field.dispatchEvent(event);
+}
+
+/** What the gate reads off `navigator` (User-Agent Client Hints are Chromium-only). */
+export interface PasteEngineNavigator {
+  userAgent?: string;
+  platform?: string;
+  userAgentData?: { brands?: ReadonlyArray<{ brand: string; version: string }>; platform?: string } | null;
+}
+
+/** The Chromium majors with the bug: 155 added the check, 157 ships the fix. */
+const AFFECTED_CHROMIUM = new Set([155, 156]);
+
+/**
+ * Only Chromium 155 and 156 on macOS have the bug, so only they get the
+ * workaround: it turns itself off when 157 arrives, and Safari, Firefox and
+ * older Chromium (VS Code's webview) keep the browser's own paste. Safari
+ * matters most: there `execCommand('insertText')` merges with the typing
+ * before it, so one ⌘Z after a paste would also erase what was typed.
+ * Chrome, Edge, Brave, Arc and other Chromium browsers are told by the
+ * "Chromium" brand of User-Agent Client Hints, else by `Chrome/<major>` in
+ * the UA string (Safari and Firefox carry no `Chrome/`; Chrome on iOS is
+ * WebKit and says `CriOS/`).
+ */
+export function chromiumPasteBugAffected(nav: PasteEngineNavigator | undefined | null): boolean {
+  if (!nav) return false;
+  const ua = nav.userAgent ?? '';
+  const data = nav.userAgentData ?? null;
+  let major = Number.NaN;
+  const brand = data?.brands?.find((b) => b.brand === 'Chromium');
+  if (brand) major = Number.parseInt(brand.version, 10);
+  if (Number.isNaN(major)) {
+    const match = /Chrome\/(\d+)/.exec(ua);
+    if (match) major = Number.parseInt(match[1]!, 10);
+  }
+  if (!AFFECTED_CHROMIUM.has(major)) return false;
+  // Client hints name the platform when present; else navigator.platform or the UA string.
+  if (data?.platform) return /^mac/i.test(data.platform);
+  return /^mac/i.test(nav.platform ?? '') || /Macintosh|Mac OS X/.test(ua);
+}
+
+/**
+ * Tests (the e2e simulation, in a Chromium that is not 155 or 156) set this
+ * to `true` on the window to turn the workaround on whatever the engine.
+ */
+export const FORCE_PLAIN_TEXT_PASTE_FLAG = '__plannotatorForcePlainTextPaste';
+
+export interface PlainTextPasteOptions {
+  /** Whether the workaround runs. Default: the engine gate, or the window's force flag. */
+  enabled?: boolean;
+  /** Act on script-dispatched (untrusted) paste events too; for tests. Default false. */
+  allowUntrusted?: boolean;
+}
+
+/**
+ * Install on a window; returns the uninstall. Listens in the bubble phase on
+ * the window, so every handler on the page (React's, the image-paste ones)
+ * runs first and can claim the paste. Does nothing outside the affected
+ * engine (`chromiumPasteBugAffected`).
+ */
+export function installPlainTextPaste(win: Window = window, options: PlainTextPasteOptions = {}): () => void {
+  const doc = win.document;
+  const engine = chromiumPasteBugAffected(win.navigator as unknown as PasteEngineNavigator);
+  const forced = () => (win as unknown as Record<string, unknown>)[FORCE_PLAIN_TEXT_PASTE_FLAG] === true;
+  const enabled = () => options.enabled ?? (engine || forced());
+  let composing = false;
+  const onCompositionStart = () => {
+    composing = true;
+  };
+  // Also on focus moving and the window losing focus: a compositionend that never arrives must not
+  // leave the workaround off until reload.
+  const onCompositionEnd = () => {
+    composing = false;
+  };
+  const onPaste = (event: ClipboardEvent) => {
+    if (!enabled()) return;
+    if (!event.isTrusted && !options.allowUntrusted) return; // a script's paste event inserts nothing
+    const insertion = plainTextPasteInsertion(event, composing);
+    if (!insertion) return;
+    event.preventDefault();
+    insertPastedText(insertion);
+  };
+  doc.addEventListener('compositionstart', onCompositionStart, true);
+  doc.addEventListener('compositionend', onCompositionEnd, true);
+  doc.addEventListener('focusin', onCompositionEnd, true);
+  win.addEventListener('blur', onCompositionEnd);
+  win.addEventListener('paste', onPaste);
+  return () => {
+    doc.removeEventListener('compositionstart', onCompositionStart, true);
+    doc.removeEventListener('compositionend', onCompositionEnd, true);
+    doc.removeEventListener('focusin', onCompositionEnd, true);
+    win.removeEventListener('blur', onCompositionEnd);
+    win.removeEventListener('paste', onPaste);
+  };
+}