@plannotator/ui 0.53.1 → 0.54.0

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;
+}

package/utils/scrollAnchor.ts

@@ -0,0 +1,82 @@
+/**
+ * Remember where a reader was in a rendered document, and put them back there.
+ *
+ * Raw pixels are a poor bookmark: images that finish loading, highlights that
+ * are re-applied, or a sidebar that changes the reading column's width all move
+ * the text under a fixed scrollTop. So the anchor is the first block
+ * (`data-block-id`) still visible at the top of the scroll viewport, plus how
+ * far its top sat from the viewport's top. Restoring scrolls that block back to
+ * the same offset; the raw scrollTop is only the fallback when the block is
+ * gone.
+ */
+
+import {
+  getScrollViewportRect,
+  getScrollViewportTop,
+  offsetScrollViewport,
+  scrollViewportTo,
+} from '../hooks/useScrollViewport';
+
+export interface ScrollAnchor {
+  /** The first block visible at the top of the viewport, null when none is. */
+  blockId: string | null;
+  /** That block's top minus the viewport's top, in CSS pixels (≤ 0 when the
+   *  block starts above the viewport). */
+  offset: number;
+  /** The viewport's scrollTop when captured — the fallback. */
+  scrollTop: number;
+}
+
+function blocksIn(viewport: HTMLElement): HTMLElement[] {
+  return Array.from(viewport.querySelectorAll<HTMLElement>('[data-block-id]'));
+}
+
+/** Capture where the reader is in `viewport`. */
+export function captureScrollAnchor(viewport: HTMLElement): ScrollAnchor {
+  const scrollTop = getScrollViewportTop(viewport);
+  const viewportTop = getScrollViewportRect(viewport).top;
+  for (const block of blocksIn(viewport)) {
+    const rect = block.getBoundingClientRect();
+    if (rect.height <= 0 && rect.width <= 0) continue;
+    if (rect.bottom > viewportTop + 1) {
+      return {
+        blockId: block.getAttribute('data-block-id'),
+        offset: rect.top - viewportTop,
+        scrollTop,
+      };
+    }
+  }
+  return { blockId: null, offset: 0, scrollTop };
+}
+
+function findBlock(viewport: HTMLElement, blockId: string): HTMLElement | null {
+  for (const block of blocksIn(viewport)) {
+    if (block.getAttribute('data-block-id') === blockId) return block;
+  }
+  return null;
+}
+
+/**
+ * Whether the anchor's block is in the viewport's DOM yet. A document that is
+ * still mounting has none of its blocks, so a caller can wait for this.
+ */
+export function scrollAnchorReady(viewport: HTMLElement, anchor: ScrollAnchor): boolean {
+  if (anchor.blockId === null) return blocksIn(viewport).length > 0 || anchor.scrollTop === 0;
+  return findBlock(viewport, anchor.blockId) !== null;
+}
+
+/**
+ * Put the reader back at `anchor`. Returns the viewport's scrollTop afterwards.
+ * When the anchor's block is gone, falls back to the captured scrollTop.
+ */
+export function restoreScrollAnchor(viewport: HTMLElement, anchor: ScrollAnchor): number {
+  const block = anchor.blockId === null ? null : findBlock(viewport, anchor.blockId);
+  if (block) {
+    const viewportTop = getScrollViewportRect(viewport).top;
+    const delta = block.getBoundingClientRect().top - viewportTop - anchor.offset;
+    if (Math.abs(delta) >= 1) offsetScrollViewport(viewport, delta);
+  } else if (Math.abs(getScrollViewportTop(viewport) - anchor.scrollTop) >= 1) {
+    scrollViewportTo(viewport, { top: anchor.scrollTop, behavior: 'auto' });
+  }
+  return getScrollViewportTop(viewport);
+}