@plannotator/ui 0.53.0 → 0.54.0

package/utils/parser.ts

@@ -2,6 +2,7 @@ import type { Block, Annotation, CodeAnnotation, EditorAnnotation, ImageAttachme
 import { planDenyFeedback } from '@plannotator/core/feedback-templates';
 import { resolveReplyParents } from '@plannotator/core/annotation-threads';
 import { diagramAnchorLocationLine, parseDiagramAnchor } from '@plannotator/core/diagram-anchor';
+import { imageRegionLocationLines, parseImageRegion, type ImageRegion } from '@plannotator/core/image-region';
 import {
   formatQuestionAnswerLines,
   formatQuestionAnswerText,
@@ -779,6 +780,8 @@ const isElementPlaceholderQuote = (text: unknown): boolean =>
  *  element instead (`Feedback on the <nav> element — "Primary"`); every other
  *  annotation keeps the quote line exactly as before. */
 const commentHeadingLine = (ann: any): string => {
+  const region = imageRegionOf(ann);
+  if (region) return `Feedback on a region of the image ${safeInline(region.src, 600)}`;
   const element = elementSubject(ann);
   return element ? `Feedback on ${element}` : `Feedback on: "${ann.originalText}"`;
 };
@@ -1001,6 +1004,8 @@ export const exportAnnotationEntry = (ann: any, opts: ElementContextExportOption
     default:
       if (ann?.isQuickLabel) {
         output += `[${ann.text}] ${commentHeadingLine(ann)}\n`;
+        const region = imageRegionOf(ann);
+        if (region) output += imageRegionExportLines(region);
         if (ann.quickLabelTip) output += `> ${ann.quickLabelTip}\n`;
       } else {
         output += `${commentHeadingLine(ann)}\n${diagramLocationExportLine(ann)}> ${ann?.text ?? ''}\n`;
@@ -1021,12 +1026,28 @@ export const exportAnnotationEntry = (ann: any, opts: ElementContextExportOption
   return output;
 };
 
+/** The validated region of a comment on part of an image (#2100), or null
+ *  for every other annotation and for a malformed one (an older or foreign
+ *  writer), which then exports as the ordinary comment it also is. */
+const imageRegionOf = (ann: any): ImageRegion | null =>
+  ann?.imageRegion == null ? null : parseImageRegion(ann.imageRegion);
+
+/** The two location lines under a region comment (the approved prototype):
+ *  `Image: figures/status-colors.png (line 63)` then
+ *  `Region: x=1820 y=380 w=420 h=160 (of 3664×1453)` — the image as written,
+ *  its line, and the box in the image's own pixels. The src is collapsed to
+ *  one line and defused like every page-controlled string. */
+const imageRegionExportLines = (region: ImageRegion): string =>
+  `${imageRegionLocationLines({ ...region, src: safeInline(region.src, 600) })}\n`;
+
 /** The location line under a comment made on a rendered diagram part:
  *  `Diagram node Approve? (D), line 4` — the part's own id (what the agent
  *  greps the fence for) and the DOCUMENT line that declares it. Emits
  *  nothing for every other annotation, keeping their output byte-identical;
  *  a malformed anchor (an older or foreign writer) is skipped, never thrown. */
 const diagramLocationExportLine = (ann: any): string => {
+  const region = imageRegionOf(ann);
+  if (region) return imageRegionExportLines(region);
   const anchor = ann?.diagramAnchor === undefined ? null : parseDiagramAnchor(ann.diagramAnchor);
   if (anchor !== null) return `${safeInline(diagramAnchorLocationLine(anchor), 600)}\n`;
   return hostLocationExportLine(ann);
@@ -1043,6 +1064,9 @@ const hostLocationExportLine = (ann: any): string => {
 
 const lineLabelForAnnotation = (blocks: Block[], ann: any): string | null => {
   if (!ann.blockId || ann.type === 'GLOBAL_COMMENT') return null;
+  // A region names the line its image is written on, not its block's span.
+  const region = imageRegionOf(ann);
+  if (region?.sourceLine != null) return `line ${region.sourceLine}`;
   if (typeof ann.blockId === 'string' && ann.blockId.startsWith('diff-block-')) return null;
   const block = blocks.find(b => b.id === ann.blockId);
   if (!block || typeof block.startLine !== 'number') return null;
@@ -1615,7 +1639,10 @@ export const formatDraftAnnotationsForAsk = (input: DraftAnnotationsForAsk): str
     } else {
       const subject = elementSubject(ann) ?? quote(ann.originalText);
       const anchor = ann.diagramAnchor === undefined ? null : parseDiagramAnchor(ann.diagramAnchor);
-      const target = anchor ? `${subject} [${safeInline(diagramAnchorLocationLine(anchor), 300)}]` : subject;
+      const region = imageRegionOf(ann);
+      const target = region
+        ? `a region of the image ${quote(region.src)} [${safeInline(imageRegionLocationLines(region).replace('\n', '; '), 300)}]`
+        : anchor ? `${subject} [${safeInline(diagramAnchorLocationLine(anchor), 300)}]` : subject;
       body = ann.isQuickLabel
         ? `label ${quote(ann.text)} on ${target}`
         : `comment on ${target} — ${text(ann.text)}`;

package/utils/platform.ts

@@ -14,6 +14,11 @@ export const submitHint = isMac ? '⌘↵' : 'Ctrl+Enter';
  * use `modKey` in key hints and shortcut chips.
  */
 export const modKeyWord = isMac ? 'Cmd' : 'Ctrl';
+/**
+ * The primary modifier as a screen reader should say it in a sentence
+ * ("hold Command and scroll"), for live-region text.
+ */
+export const modKeySpoken = isMac ? 'Command' : 'Control';
 /**
  * The primary modifier's own `KeyboardEvent.key` name, for features that arm
  * on the modifier being HELD rather than on a chord. Pair with `isModKeyHeld`:
@@ -25,3 +30,44 @@ export function isModKeyHeld(event: { metaKey: boolean; ctrlKey: boolean }): boo
   return isMac ? event.metaKey : event.ctrlKey;
 }
 export const isWindows = typeof navigator !== 'undefined' && /^Win/.test(navigator.platform);
+
+/** What `rootPlatform` reads off `navigator` (User-Agent Client Hints are Chromium-only). */
+export interface RootPlatformNavigator {
+  userAgent?: string;
+  platform?: string;
+  userAgentData?: { platform?: string } | null;
+}
+
+export type RootPlatform = 'apple' | 'windows' | 'android' | 'chromeos' | 'linux' | 'other';
+
+/**
+ * The operating system, coarse: what the page's CSS may need to know. Android
+ * and ChromeOS are told apart from desktop Linux (their user agents say
+ * "Linux" too); iPadOS in desktop mode says "Macintosh" and counts as apple.
+ */
+export function rootPlatform(nav: RootPlatformNavigator | undefined | null): RootPlatform {
+  if (!nav) return 'other';
+  const s = `${nav.userAgentData?.platform ?? ''} ${nav.platform ?? ''} ${nav.userAgent ?? ''}`;
+  if (/Android/i.test(s)) return 'android';
+  if (/CrOS|Chrome OS/i.test(s)) return 'chromeos';
+  if (/Mac|iPhone|iPad|iPod/i.test(s)) return 'apple';
+  if (/Win/i.test(s)) return 'windows';
+  if (/Linux|X11|BSD/i.test(s)) return 'linux';
+  return 'other';
+}
+
+/**
+ * Put `pn-os-<platform>` on <html>, once. theme.css scopes platform-specific
+ * rules to it: on desktop Linux the monospace fallback (Ubuntu Mono) draws
+ * `ss02` as superscript digits, so only there are Inter's feature tags kept
+ * off other fonts (#1961). ThemeProvider calls this synchronously in render,
+ * with the theme classes, so the class is on the root before the first paint.
+ * The marketing site and the guides.show landing page set the same class
+ * from an inline script (keep their patterns in step with this one).
+ */
+export function markRootPlatform(doc: Document | undefined = typeof document !== 'undefined' ? document : undefined): void {
+  if (!doc) return;
+  const root = doc.documentElement;
+  for (const cls of Array.from(root.classList)) if (cls.startsWith('pn-os-')) return;
+  root.classList.add(`pn-os-${rootPlatform(typeof navigator !== 'undefined' ? navigator : null)}`);
+}

package/utils/refCard.ts

@@ -0,0 +1,82 @@
+/**
+ * Where an issue / PR / MR hover card's data comes from (`components/RefHoverCard`).
+ *
+ * A host seam in the `configurePlannotatorUI` style: the default is NO
+ * transport, so a host that installs none (every `@plannotator/ui` consumer
+ * that does not opt in) draws no card and makes no request: byte for byte as
+ * before. A host that can fetch installs one with `setRefCardTransport` or
+ * `configurePlannotatorUI({ refCardTransport })`: the Inbox over its
+ * `/api/inbox/ref` route, plan review, annotate and code review over
+ * `GET /api/ref` (`refCardRouteTransport` below).
+ *
+ * The client keeps answers for `REF_CARD_CLIENT_FRESH_MS` per ref and shares
+ * one request between hovers of the same ref. The server keeps its own cache;
+ * this one only spares the round trip while a person moves between links.
+ */
+
+import { forgeRefKey, parseForgeRefUrl, type ForgeRef, type ForgeRefCardResult } from '@plannotator/core/forge-ref-card';
+
+export type { ForgeRef, ForgeRefCardResult } from '@plannotator/core/forge-ref-card';
+
+/** Fetch the card for a link. Resolve null when the host does not read that link. */
+export type RefCardTransport = (href: string, ref: ForgeRef, signal: AbortSignal) => Promise<ForgeRefCardResult | null>;
+
+let transport: RefCardTransport | null = null;
+
+export function setRefCardTransport(next: RefCardTransport | null): void {
+  transport = next;
+  cache.clear();
+}
+
+export function getRefCardTransport(): RefCardTransport | null {
+  return transport;
+}
+
+/**
+ * A transport over a server route answering like Plannotator's `GET /api/ref`
+ * (and the Inbox's `/api/inbox/ref`): `?url=<link>` → `{ ok, data | error,
+ * fetchedAt }`. A 404 means the route is not there (an older server) or is off
+ * (a session other devices can reach): the transport then stops asking for
+ * the life of the page and answers null. Any other failure answers null.
+ */
+export function refCardRouteTransport(route: string): RefCardTransport {
+  let off = false;
+  return async (href, _ref, signal) => {
+    if (off) return null;
+    const res = await fetch(`${route}?url=${encodeURIComponent(href)}`, { signal, headers: { accept: 'application/json' } });
+    if (res.status === 404) {
+      off = true;
+      return null;
+    }
+    if (!res.ok) return null;
+    const body = (await res.json()) as unknown;
+    return body && typeof body === 'object' && typeof (body as { ok?: unknown }).ok === 'boolean' ? (body as ForgeRefCardResult) : null;
+  };
+}
+
+export const REF_CARD_CLIENT_FRESH_MS = 30_000;
+
+const cache = new Map<string, { at: number; promise: Promise<ForgeRefCardResult | null> }>();
+
+/** The ref a link names, when a transport is installed to fetch it; else null (no card). */
+export function refCardTarget(href: string | null | undefined): ForgeRef | null {
+  if (!transport || !href) return null;
+  return parseForgeRefUrl(href);
+}
+
+/** The card for a link, through the installed transport (shared and cached per ref). */
+export function loadRefCard(href: string, ref: ForgeRef): Promise<ForgeRefCardResult | null> {
+  const t = transport;
+  if (!t) return Promise.resolve(null);
+  const key = forgeRefKey(ref);
+  const hit = cache.get(key);
+  if (hit && Date.now() - hit.at < REF_CARD_CLIENT_FRESH_MS) return hit.promise;
+  // Never aborted by one hover leaving: another hover may share it, and the server caches it anyway.
+  const controller = new AbortController();
+  const promise = t(href, ref, controller.signal).catch(() => null);
+  cache.set(key, { at: Date.now(), promise });
+  void promise.then((r) => {
+    if (!r) cache.delete(key);
+  });
+  return promise;
+}

package/utils/richClipboard.ts

@@ -0,0 +1,380 @@
+import { copyTextToClipboard } from './clipboard';
+import { restoreClipboardLists } from './richClipboardLists';
+
+/** Cap on markup carried across the HTML-viewer bridge (and on its range text). */
+export const MAX_RICH_CLIPBOARD_HTML_LENGTH = 256 * 1024;
+/** Cap on the sanitized HTML put on the clipboard; past it the copy is plain text. */
+export const MAX_RICH_CLIPBOARD_OUTPUT_LENGTH = 512 * 1024;
+
+/**
+ * What the toolbar's Copy button copies when rich copy is on, built when it is
+ * pressed: sanitized HTML plus its plain text (`html: ''` when no markup came
+ * back), the selection marked too large for rich text, or null when nothing
+ * could be built. `truncated` marks `text` as not the whole selection.
+ */
+export type RichCopySource =
+  | { html: string; text: string; truncated?: boolean }
+  | { tooLarge: true; text: string; truncated?: boolean }
+  | null;
+
+/** What the button actually put on the clipboard, for its tooltip. */
+export interface RichCopyOutcome {
+  copied: 'rich' | 'plain';
+  /** Why plain: no rich clipboard here, too large for rich text, or no markup came back. */
+  reason?: 'unavailable' | 'too-large' | 'no-markup';
+  /** Set when the copied text is cut: its length in characters. */
+  truncatedTo?: number;
+}
+
+/** The button's tooltip after a copy: says exactly what went on the clipboard. */
+export function richCopyOutcomeLabel(outcome: RichCopyOutcome): string {
+  const notes: string[] = [];
+  if (outcome.copied === 'plain') {
+    notes.push(
+      outcome.reason === 'too-large' ? 'too large for rich text'
+      : outcome.reason === 'no-markup' ? 'formatting not available'
+      : 'rich clipboard unavailable',
+    );
+  }
+  if (outcome.truncatedTo !== undefined) {
+    notes.push(`first ${outcome.truncatedTo.toLocaleString('en-US')} characters only`);
+  }
+  const base = outcome.copied === 'rich' ? 'Copied as rich text' : 'Copied as plain text';
+  return notes.length > 0 ? `${base} (${notes.join('; ')})` : base;
+}
+
+const ALLOWED_TAGS = new Set([
+  'a', 'b', 'blockquote', 'br', 'code', 'del', 'div', 'em', 'h1', 'h2', 'h3',
+  'h4', 'h5', 'h6', 'hr', 'i', 'li', 'ol', 'p', 'pre', 's', 'span', 'strong',
+  'sub', 'sup', 'table', 'tbody', 'td', 'tfoot', 'th', 'thead', 'tr', 'u', 'ul',
+]);
+
+const DROP_WITH_CONTENT = new Set([
+  'AUDIO', 'BUTTON', 'CANVAS', 'EMBED', 'FORM', 'IFRAME', 'INPUT', 'OBJECT',
+  'OPTION', 'SCRIPT', 'SELECT', 'STYLE', 'SVG', 'TEMPLATE', 'TEXTAREA', 'VIDEO',
+]);
+
+const DROP_SELECTORS = [
+  '.annotation-exclude',
+  '.annotation-toolbar',
+  '[data-comment-popover="true"]',
+  '[data-floating-picker="true"]',
+  '[data-print-hide]',
+  'button',
+].join(',');
+
+function safeIntegerAttribute(element: Element, name: string, minimum: number): string | null {
+  const value = element.getAttribute(name);
+  if (!value || !/^-?\d+$/.test(value)) return null;
+  const number = Number(value);
+  return Number.isSafeInteger(number) && number >= minimum ? String(number) : null;
+}
+
+/** A hostname that names this machine, whatever its spelling (URL-parsed). */
+export function isLoopbackHostname(hostname: string): boolean {
+  const host = hostname.toLowerCase().replace(/\.$/, '');
+  return host === 'localhost'
+    || host.endsWith('.localhost')
+    || /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host)
+    || host === '0.0.0.0'
+    || host === '[::1]'
+    || host === '[::]'
+    // IPv4-mapped and IPv4-compatible loopback, as the URL parser serializes
+    // them ([::ffff:7f00:1], [::7f00:1]).
+    || /^\[::(ffff:)?7f[0-9a-f]{2}:[0-9a-f]{1,4}\]$/.test(host);
+}
+
+function safeLinkHref(href: string): string | null {
+  try {
+    const baseUrl = new URL(document.baseURI);
+    const url = new URL(href, baseUrl);
+    if (!['http:', 'https:', 'mailto:', 'tel:'].includes(url.protocol)) return null;
+    // A link to this session's own server or to this machine is dead once the
+    // session ends, and some carry a per-document access token
+    // (/api/html-assets/<token>/) or a local path: never exported. The link
+    // text stays.
+    if (
+      (url.protocol === 'http:' || url.protocol === 'https:')
+      && (url.origin === baseUrl.origin || isLoopbackHostname(url.hostname))
+    ) return null;
+    url.username = '';
+    url.password = '';
+    return url.href;
+  } catch {
+    return null;
+  }
+}
+
+function appendSanitizedNode(source: Node, target: Node): void {
+  if (source.nodeType === Node.TEXT_NODE) {
+    target.appendChild(document.createTextNode(source.textContent ?? ''));
+    return;
+  }
+  if (!(source instanceof Element)) return;
+  if (DROP_WITH_CONTENT.has(source.tagName.toUpperCase()) || source.matches(DROP_SELECTORS)) return;
+
+  const tag = source.tagName.toLowerCase();
+  if (!ALLOWED_TAGS.has(tag)) {
+    source.childNodes.forEach((child) => appendSanitizedNode(child, target));
+    return;
+  }
+
+  const clean = document.createElement(tag);
+  const element = source;
+  if (tag === 'a') {
+    const href = element.getAttribute('href');
+    const safeHref = href ? safeLinkHref(href) : null;
+    if (safeHref) clean.setAttribute('href', safeHref);
+  }
+  if (tag === 'ol') {
+    const start = safeIntegerAttribute(element, 'start', -2147483648);
+    if (start) clean.setAttribute('start', start);
+  }
+  if (tag === 'li') {
+    const value = safeIntegerAttribute(element, 'value', -2147483648);
+    if (value) clean.setAttribute('value', value);
+  }
+  if (tag === 'td' || tag === 'th') {
+    for (const name of ['colspan', 'rowspan']) {
+      const span = safeIntegerAttribute(element, name, 1);
+      if (span && Number(span) <= 1000) clean.setAttribute(name, span);
+    }
+    const scope = element.getAttribute('scope');
+    if (scope && ['row', 'col', 'rowgroup', 'colgroup'].includes(scope)) {
+      clean.setAttribute('scope', scope);
+    }
+  }
+  if (tag === 'ol' || tag === 'ul' || tag === 'li') {
+    const dir = element.getAttribute('dir');
+    if (dir && ['ltr', 'rtl', 'auto'].includes(dir)) clean.setAttribute('dir', dir);
+  }
+  source.childNodes.forEach((child) => appendSanitizedNode(child, clean));
+  target.appendChild(clean);
+}
+
+function sanitizeFragment(fragment: ParentNode): string {
+  const clean = document.createElement('div');
+  fragment.childNodes.forEach((node) => appendSanitizedNode(node, clean));
+  return clean.innerHTML;
+}
+
+/**
+ * Snapshot selected DOM as safe, theme-free rich clipboard HTML. Null when the
+ * selection is too large for rich text (its text or the sanitized HTML past
+ * MAX_RICH_CLIPBOARD_OUTPUT_LENGTH).
+ */
+export function selectionRangeToHtml(range: Range): string | null {
+  if (range.toString().length > MAX_RICH_CLIPBOARD_OUTPUT_LENGTH) return null;
+  const fragment = range.cloneContents();
+  // cloneContents omits the common ancestor, including formatting when both
+  // endpoints are inside the same heading, link, or bold text node.
+  let ancestor = range.commonAncestorContainer instanceof Element
+    ? range.commonAncestorContainer
+    : range.commonAncestorContainer.parentElement;
+  while (ancestor && ancestor !== document.body) {
+    if (ancestor.matches('a,b,blockquote,code,del,em,h1,h2,h3,h4,h5,h6,i,li,ol,p,pre,s,strong,sub,sup,table,tbody,td,tfoot,th,thead,tr,u,ul,[data-rich-list-level]')) {
+      const wrapper = ancestor.cloneNode(false);
+      while (fragment.firstChild) wrapper.appendChild(fragment.firstChild);
+      fragment.appendChild(wrapper);
+    }
+    ancestor = ancestor.parentElement;
+  }
+  restoreClipboardLists(fragment);
+  const html = sanitizeFragment(fragment);
+  return html.length <= MAX_RICH_CLIPBOARD_OUTPUT_LENGTH ? html : null;
+}
+
+/** The button's source for a live range, built at press time. Never throws. */
+export function richCopySourceFromRange(range: Range, text: string): RichCopySource {
+  try {
+    const html = selectionRangeToHtml(range);
+    if (html === null) return { tooLarge: true, text };
+    return html ? { html, text } : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Sanitize HTML received across the HTML-viewer bridge before clipboard use. */
+export function sanitizeRichHtml(html: string): string | null {
+  if (!html || html.length > MAX_RICH_CLIPBOARD_HTML_LENGTH) return null;
+  try {
+    const parsed = new DOMParser().parseFromString(html, 'text/html');
+    return sanitizeFragment(parsed.body);
+  } catch {
+    return null;
+  }
+}
+
+function copyRichTextWithFallback(html: string, text: string): boolean {
+  const activeElement = document.activeElement instanceof HTMLElement
+    ? document.activeElement
+    : null;
+  const selection = window.getSelection();
+  const savedRanges = selection
+    ? Array.from({ length: selection.rangeCount }, (_, index) =>
+        selection.getRangeAt(index).cloneRange())
+    : [];
+  let copied = false;
+
+  // Only this button's own execCommand('copy') passes through here: the
+  // listener exists for that one synchronous call, at window capture, and
+  // stops the event so no page copy handler (Viewer's plain-text one) runs.
+  const handleCopy = (event: ClipboardEvent) => {
+    event.stopImmediatePropagation();
+    const clipboardData = event.clipboardData;
+    if (!clipboardData) return;
+    try {
+      clipboardData.setData('text/html', html);
+      clipboardData.setData('text/plain', text);
+      event.preventDefault();
+      copied = true;
+    } catch {
+      copied = false;
+    }
+  };
+
+  window.addEventListener('copy', handleCopy, true);
+  try {
+    copied = document.execCommand('copy') && copied;
+  } catch {
+    copied = false;
+  } finally {
+    window.removeEventListener('copy', handleCopy, true);
+  }
+
+  if (activeElement?.isConnected) {
+    activeElement.focus({ preventScroll: true });
+  }
+  if (selection && savedRanges.length > 0) {
+    selection.removeAllRanges();
+    savedRanges.forEach((range) => selection.addRange(range));
+  }
+  return copied;
+}
+
+/** 'too-large': plain text was copied because the HTML is past the output cap. */
+export type RichClipboardResult = 'rich' | 'plain' | 'too-large' | false;
+
+/** Prefer both MIME types; report an honest plain fallback when the host is text-only. */
+export async function copyRichTextToClipboard(html: string, text: string): Promise<RichClipboardResult> {
+  if (html.length > MAX_RICH_CLIPBOARD_OUTPUT_LENGTH) {
+    return await copyTextToClipboard(text) ? 'too-large' : false;
+  }
+  if (!html) {
+    return await copyTextToClipboard(text) ? 'plain' : false;
+  }
+  try {
+    if (typeof ClipboardItem !== 'undefined' && navigator.clipboard?.write) {
+      const item = new ClipboardItem({
+        'text/html': new Blob([html], { type: 'text/html' }),
+        'text/plain': new Blob([text], { type: 'text/plain' }),
+      });
+      await navigator.clipboard.write([item]);
+      return 'rich';
+    }
+  } catch {
+    // Fall back only if the legacy copy event can set both MIME types.
+  }
+  try {
+    if (copyRichTextWithFallback(html, text)) return 'rich';
+  } catch {
+    // Try the host's text-only clipboard below.
+  }
+  try {
+    if (navigator.clipboard?.writeText) {
+      await navigator.clipboard.writeText(text);
+      return 'plain';
+    }
+  } catch {
+    // Clipboard access is unavailable.
+  }
+  return false;
+}
+
+/** What one copy writes: rich HTML (or none) and the plain text, plus why. */
+interface CopyPlan {
+  html: string | null;
+  text: string;
+  reason?: 'too-large' | 'no-markup';
+  truncatedTo?: number;
+}
+
+function planCopy(source: RichCopySource, fallbackText: string): CopyPlan {
+  if (!source) return { html: null, text: fallbackText, reason: 'no-markup' };
+  const text = source.text || fallbackText;
+  const truncatedTo = source.truncated ? text.length : undefined;
+  if ('tooLarge' in source) return { html: null, text, reason: 'too-large', truncatedTo };
+  if (!source.html) return { html: null, text, reason: 'no-markup', truncatedTo };
+  if (source.html.length > MAX_RICH_CLIPBOARD_OUTPUT_LENGTH) {
+    return { html: null, text, reason: 'too-large', truncatedTo };
+  }
+  return { html: source.html, text, truncatedTo };
+}
+
+/** Plain text as clipboard HTML: escaped, in a <pre>, so the html part of a
+ *  promised clipboard item can always resolve. */
+export function plainTextClipboardHtml(text: string): string {
+  const escaped = text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+  return `<pre>${escaped}</pre>`;
+}
+
+async function copyPlanned(plan: CopyPlan): Promise<RichCopyOutcome | false> {
+  if (plan.html === null) {
+    return await copyTextToClipboard(plan.text)
+      ? { copied: 'plain', reason: plan.reason, truncatedTo: plan.truncatedTo }
+      : false;
+  }
+  const result = await copyRichTextToClipboard(plan.html, plan.text);
+  if (result === 'rich') return { copied: 'rich', truncatedTo: plan.truncatedTo };
+  if (result === 'plain') return { copied: 'plain', reason: 'unavailable', truncatedTo: plan.truncatedTo };
+  if (result === 'too-large') return { copied: 'plain', reason: 'too-large', truncatedTo: plan.truncatedTo };
+  return false;
+}
+
+/**
+ * The toolbar button's copy: builds the rich HTML only now, through `build`
+ * (synchronous for the markdown Viewer, a bridge round trip on HTML surfaces).
+ * An asynchronous source is handed to the clipboard as ONE item with promised
+ * blobs inside the click, so browsers that need the write to start in the
+ * gesture (Safari, WKWebView) keep it. Neither promise ever rejects: with no
+ * rich markup (too large, none came back, a timeout) the html part is the
+ * plain text, escaped, and the outcome says plain.
+ */
+export async function copyRichSelection(
+  build: () => RichCopySource | Promise<RichCopySource>,
+  fallbackText: string,
+): Promise<RichCopyOutcome | false> {
+  let source: RichCopySource | Promise<RichCopySource>;
+  try {
+    source = build();
+  } catch {
+    source = null;
+  }
+  if (!(source instanceof Promise)) return copyPlanned(planCopy(source, fallbackText));
+
+  const plan = source.then(
+    (value) => planCopy(value, fallbackText),
+    () => planCopy(null, fallbackText),
+  );
+  if (typeof ClipboardItem !== 'undefined' && navigator.clipboard?.write) {
+    try {
+      const item = new ClipboardItem({
+        'text/html': plan.then((p) =>
+          new Blob([p.html ?? plainTextClipboardHtml(p.text)], { type: 'text/html' })),
+        'text/plain': plan.then((p) => new Blob([p.text], { type: 'text/plain' })),
+      });
+      await navigator.clipboard.write([item]);
+      const done = await plan;
+      return done.html !== null
+        ? { copied: 'rich', truncatedTo: done.truncatedTo }
+        : { copied: 'plain', reason: done.reason, truncatedTo: done.truncatedTo };
+    } catch {
+      // The write itself was refused: the plain paths below (best effort).
+    }
+  }
+  return copyPlanned(await plan);
+}

package/utils/richClipboardLists.ts

@@ -0,0 +1,57 @@
+interface ListFrame {
+  level: number;
+  kind: 'ol' | 'ul';
+  list: HTMLOListElement | HTMLUListElement;
+  lastItem: HTMLLIElement | null;
+}
+
+/** Restore semantic lists in a cloned Markdown selection before sanitization. */
+export function restoreClipboardLists(fragment: ParentNode): void {
+  const output = document.createDocumentFragment();
+  const stack: ListFrame[] = [];
+
+  for (const node of Array.from(fragment.childNodes)) {
+    const levelText = node instanceof Element ? node.getAttribute('data-rich-list-level') : null;
+    const kind = node instanceof Element ? node.getAttribute('data-rich-list-kind') : null;
+    const level = levelText === null ? -1 : Number(levelText);
+    if (!(node instanceof Element) || !Number.isSafeInteger(level) || level < 0 || (kind !== 'ol' && kind !== 'ul')) {
+      stack.length = 0;
+      if (node instanceof Element) restoreClipboardLists(node);
+      output.appendChild(node);
+      continue;
+    }
+
+    while (stack.length && stack[stack.length - 1].level > level) stack.pop();
+    let current = stack[stack.length - 1];
+    if (current?.level === level && current.kind !== kind) {
+      stack.pop();
+      current = stack[stack.length - 1];
+    }
+
+    const indexText = node.getAttribute('data-rich-list-index');
+    const index = indexText === null ? null : Number(indexText);
+    if (!current || current.level < level) {
+      const list = document.createElement(kind);
+      if (kind === 'ol' && index !== null && Number.isSafeInteger(index)) {
+        list.setAttribute('start', String(index));
+      }
+      (current?.lastItem ?? output).appendChild(list);
+      current = { level, kind, list, lastItem: null };
+      stack.push(current);
+    }
+
+    const item = document.createElement('li');
+    if (kind === 'ol' && index !== null && Number.isSafeInteger(index)) {
+      item.setAttribute('value', String(index));
+    }
+    const checked = node.getAttribute('data-rich-list-checked');
+    if (checked === 'true' || checked === 'false') {
+      item.appendChild(document.createTextNode(checked === 'true' ? '☑ ' : '☐ '));
+    }
+    while (node.firstChild) item.appendChild(node.firstChild);
+    current.list.appendChild(item);
+    current.lastItem = item;
+  }
+
+  fragment.replaceChildren(output);
+}

package/utils/richCopyPolicy.ts

@@ -0,0 +1,22 @@
+/**
+ * Whether the selection toolbar's Copy button copies rich text (text/html plus
+ * text/plain in one write) (#1972, #2191).
+ *
+ * Default: false, so a host that does not opt in (Workspaces) keeps the
+ * toolbar and its plain-text Copy exactly as before. Plannotator's own apps (plan review and annotate,
+ * code review, the Inbox window) pass `configurePlannotatorUI({ richCopy: true })`.
+ * Read when the Viewer and HtmlViewer render their toolbar.
+ */
+let richCopy = false;
+
+export function setRichCopyEnabled(on: boolean): void {
+  richCopy = on;
+}
+
+export function resetRichCopyEnabled(): void {
+  richCopy = false;
+}
+
+export function getRichCopyEnabled(): boolean {
+  return richCopy;
+}