@plannotator/ui 0.27.0 → 0.29.0

package/utils/clipboard.ts

@@ -0,0 +1,110 @@
+function copyTextWithFallback(text: string, focusOwner?: HTMLElement): 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;
+
+  const handleCopy = (event: ClipboardEvent) => {
+    // Without clipboardData there is nothing to write into; leave the native
+    // copy untouched (preventDefault would only suppress it) and stay
+    // unsuccessful so the textarea path below runs.
+    if (!event.clipboardData) return;
+    event.preventDefault();
+    event.clipboardData.setData('text/plain', text);
+    copied = true;
+  };
+  document.addEventListener('copy', handleCopy);
+  try {
+    // Success requires BOTH: our handler actually wrote the payload via
+    // setData, AND execCommand reported the copy command ran.
+    copied = document.execCommand('copy') && copied;
+  } catch {
+    copied = false;
+  } finally {
+    document.removeEventListener('copy', handleCopy);
+  }
+
+  if (!copied) {
+    const textarea = document.createElement('textarea');
+    textarea.style.cssText = 'position:fixed;opacity:0;pointer-events:none';
+    // Marker so focus-sensitive surfaces (PopoutDialog's focus-out close
+    // guard) can recognize the transient fallback textarea and not treat the
+    // focus shift as leaving the dialog.
+    textarea.setAttribute('data-clipboard-fallback', 'true');
+    textarea.value = text;
+    document.body.appendChild(textarea);
+    textarea.select();
+    try {
+      copied = document.execCommand('copy');
+    } catch {
+      // Clipboard access can be denied by the embedding browser. The caller
+      // still regains the same document focus and selection below.
+      copied = false;
+    }
+    textarea.remove();
+  }
+
+  if (activeElement?.isConnected) {
+    activeElement.focus({ preventScroll: true });
+  } else if (focusOwner?.isConnected) {
+    focusOwner.focus({ preventScroll: true });
+  }
+  if (selection && savedRanges.length > 0) {
+    selection.removeAllRanges();
+    savedRanges.forEach((range) => selection.addRange(range));
+  }
+
+  return copied;
+}
+
+/**
+ * Copy text without stealing focus or discarding the host document's native
+ * selection. Falls back to the copy event for restricted browser contexts.
+ */
+export function copyTextPreservingFocus(
+  text: string,
+  focusOwner: HTMLElement,
+): void {
+  try {
+    const clipboardWrite = navigator.clipboard?.writeText(text);
+    if (clipboardWrite) {
+      void clipboardWrite.catch(() => {
+        copyTextWithFallback(text, focusOwner);
+      });
+      return;
+    }
+  } catch {
+    // Fall through when a browser exposes Clipboard but rejects access
+    // synchronously (for example, in a restricted embedded document).
+  }
+  copyTextWithFallback(text, focusOwner);
+}
+
+/**
+ * Copy text to the clipboard, falling back to the legacy copy-event /
+ * execCommand path when the async Clipboard API is unavailable (insecure
+ * contexts such as remote-mode plain HTTP) or rejects. Resolves `true` when
+ * a copy strategy succeeded and `false` otherwise. Never throws.
+ */
+export async function copyTextToClipboard(text: string): Promise<boolean> {
+  try {
+    const clipboardWrite = navigator.clipboard?.writeText(text);
+    if (clipboardWrite) {
+      await clipboardWrite;
+      return true;
+    }
+  } catch {
+    // Clipboard API absent, threw synchronously, or rejected — fall back to
+    // the legacy copy-event path below.
+  }
+  try {
+    return copyTextWithFallback(text);
+  } catch {
+    return false;
+  }
+}

package/utils/codeBlockMark.ts

@@ -0,0 +1,50 @@
+/**
+ * The annotation `<mark>` that covers a whole fenced code block.
+ *
+ * `web-highlighter` cannot select inside a `<pre>`, so fenced code is annotated
+ * as an all-or-nothing block: one `<mark data-bind-id>` that is the `<code>`
+ * element's only child and holds everything the fence renders. Several places
+ * need to (re)paint exactly that shape — creating an annotation, and restoring
+ * one after `applyHighlight` replaced the element's children — so the DOM
+ * contract lives here rather than being written out twice.
+ *
+ * The children are MOVED into the mark, never flattened to text. Highlighted
+ * fences render as Shiki token `<span>`s, and flattening would drop the
+ * palette's colours on the floor the moment a block was annotated or
+ * re-themed.
+ */
+import { AnnotationType } from '../types';
+
+export function codeBlockMarkClassName(type: AnnotationType): string {
+  return `annotation-highlight ${
+    type === AnnotationType.DELETION ? 'deletion' : type === AnnotationType.COMMENT ? 'comment' : ''
+  }`.trim();
+}
+
+/**
+ * Wrap everything inside `codeEl` in a single annotation mark and return it.
+ *
+ * Any mark a previous annotation left behind is unwrapped first, so a second
+ * annotation on the same block replaces the first (what has always happened)
+ * instead of nesting inside it.
+ */
+export function paintCodeBlockMark(
+  codeEl: Element,
+  id: string,
+  type: AnnotationType,
+): HTMLElement {
+  codeEl.querySelectorAll('mark[data-bind-id]').forEach((existing) => {
+    const parent = existing.parentNode;
+    if (!parent) return;
+    while (existing.firstChild) parent.insertBefore(existing.firstChild, existing);
+    existing.remove();
+  });
+
+  const doc = codeEl.ownerDocument ?? document;
+  const wrapper = doc.createElement('mark');
+  wrapper.className = codeBlockMarkClassName(type);
+  wrapper.dataset.bindId = id;
+  while (codeEl.firstChild) wrapper.appendChild(codeEl.firstChild);
+  codeEl.replaceChildren(wrapper);
+  return wrapper;
+}

package/utils/codeHighlight.ts

@@ -0,0 +1,293 @@
+/**
+ * Syntax highlighting for markdown fences and suggestion snippets.
+ *
+ * There is exactly ONE highlighter in the app: the Shiki instance
+ * `@pierre/diffs` already runs for the code-review diff pane
+ * (`getSharedHighlighter`, driven by Shiki's JavaScript regex engine). Reusing
+ * it rather than standing up a second one buys three things:
+ *
+ *   - Fences render in the SAME resolved theme as the diff pane, so a code
+ *     block and a diff hunk finally agree about what "Kanagawa Wave" looks
+ *     like. See `./syntaxTheme.ts`.
+ *   - Zero added bundle weight. Pierre imports Shiki's full bundle, so every
+ *     grammar and theme is already inlined; a separate fine-grained highlighter
+ *     would have duplicated a subset of what is already there.
+ *   - Every language Shiki bundles, not a hand-curated shortlist.
+ *
+ * The API is deliberately imperative (`applyHighlight(el, ...)`) because that is
+ * exactly the shape the removed `hljs.highlightElement(el)` had. The annotation
+ * layer reaches into these `<code>` elements to wrap `<mark>`s and to restore
+ * plain text afterwards, so keeping the DOM contract identical keeps that code
+ * working untouched.
+ *
+ * Language-less fences are never highlighted and never guessed at — see #1212.
+ * There is no auto-detection anywhere in this module.
+ */
+
+type PierreModule = typeof import('@pierre/diffs');
+
+/**
+ * Structural class on every fenced-code `<code>` element.
+ *
+ * `blockTargeting`, the vim navigation layer and the print stylesheet all
+ * address code blocks through `pre > code.pn-code`. It used to be `.hljs`,
+ * which named a library the app no longer ships; the hook itself is unchanged,
+ * only the name is. The `language-*` class alongside it is still how
+ * `blockTargeting` reads a block's language back out of the DOM.
+ */
+export const CODE_BLOCK_CLASS = 'pn-code';
+
+export function codeBlockClassName(language?: string): string {
+  return `${CODE_BLOCK_CLASS} font-mono${language ? ` language-${language}` : ''}`;
+}
+
+/** Shiki's `FontStyle` bitmask. Inlined so this module needs no shiki types. */
+const FONT_STYLE_ITALIC = 1;
+const FONT_STYLE_BOLD = 2;
+const FONT_STYLE_UNDERLINE = 4;
+const FONT_STYLE_STRIKETHROUGH = 8;
+
+let pierre: PierreModule | undefined;
+let pierreLoad: Promise<PierreModule | undefined> | undefined;
+
+/** `${lang} ${theme}` pairs attached to the shared highlighter. */
+const ready = new Set<string>();
+/** Pairs the highlighter refused (unknown grammar or theme). Never retried. */
+const rejected = new Set<string>();
+const inflight = new Map<string, Promise<boolean>>();
+
+const pairKey = (lang: string, theme: string) => `${lang} ${theme}`;
+
+function loadPierre(): Promise<PierreModule | undefined> {
+  pierreLoad ??= import('@pierre/diffs').then(
+    (mod) => {
+      pierre = mod;
+      return mod;
+    },
+    () => undefined,
+  );
+  return pierreLoad;
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+interface ThemedTokenish {
+  content: string;
+  color?: string;
+  bgColor?: string;
+  fontStyle?: number;
+  htmlStyle?: Record<string, string> | string;
+}
+
+function tokenStyle(token: ThemedTokenish): string {
+  if (typeof token.htmlStyle === 'string') return token.htmlStyle;
+  const parts: string[] = [];
+  if (token.htmlStyle) {
+    for (const [prop, value] of Object.entries(token.htmlStyle)) parts.push(`${prop}:${value}`);
+  }
+  if (token.color) parts.push(`color:${token.color}`);
+  if (token.bgColor) parts.push(`background-color:${token.bgColor}`);
+  const fontStyle = token.fontStyle ?? 0;
+  if (fontStyle > 0) {
+    if (fontStyle & FONT_STYLE_ITALIC) parts.push('font-style:italic');
+    if (fontStyle & FONT_STYLE_BOLD) parts.push('font-weight:bold');
+    const decorations: string[] = [];
+    if (fontStyle & FONT_STYLE_UNDERLINE) decorations.push('underline');
+    if (fontStyle & FONT_STYLE_STRIKETHROUGH) decorations.push('line-through');
+    if (decorations.length) parts.push(`text-decoration:${decorations.join(' ')}`);
+  }
+  return parts.join(';');
+}
+
+/**
+ * Highlighted markup for `code`, or `null` when it cannot be produced right now
+ * (highlighter not loaded yet, grammar/theme not attached yet, or the tokens do
+ * not reconstruct the input exactly).
+ *
+ * Synchronous by design: once a (lang, theme) pair is attached, every later
+ * block using it highlights during the same tick, so there is no flicker on
+ * cached highlights.
+ */
+export function highlightToHtml(code: string, lang: string, theme: string): string | null {
+  const mod = pierre;
+  if (!mod || !ready.has(pairKey(lang, theme))) return null;
+  const highlighter = mod.getHighlighterIfLoaded();
+  if (!highlighter) {
+    // The shared highlighter was disposed out from under us; everything we
+    // believed was attached is gone with it.
+    ready.clear();
+    return null;
+  }
+  let lines: ThemedTokenish[][];
+  try {
+    lines = highlighter.codeToTokens(code, { lang, theme }).tokens as ThemedTokenish[][];
+  } catch {
+    ready.delete(pairKey(lang, theme));
+    return null;
+  }
+
+  // Invariant: the rendered text must be byte-identical to the source. The
+  // annotation layer addresses these blocks by text offset, so a tokenizer that
+  // normalised line endings (or dropped a trailing newline) would silently
+  // misplace every highlight in the block. Bail to plain text instead.
+  let html = '';
+  let plain = '';
+  for (let i = 0; i < lines.length; i++) {
+    if (i > 0) {
+      html += '\n';
+      plain += '\n';
+    }
+    for (const token of lines[i]!) {
+      plain += token.content;
+      const style = tokenStyle(token);
+      html += style
+        ? `<span style="${style}">${escapeHtml(token.content)}</span>`
+        : escapeHtml(token.content);
+    }
+  }
+  return plain === code ? html : null;
+}
+
+/**
+ * Attach `lang` + `theme` to the shared highlighter. Resolves `false` for
+ * grammars or themes Shiki does not know, which is a normal outcome for a fence
+ * tagged with something made up: that block simply stays plain.
+ */
+export function ensureHighlight(lang: string, theme: string): Promise<boolean> {
+  const key = pairKey(lang, theme);
+  if (ready.has(key)) return Promise.resolve(true);
+  if (rejected.has(key)) return Promise.resolve(false);
+  const existing = inflight.get(key);
+  if (existing) return existing;
+
+  const load = loadPierre()
+    .then(async (mod) => {
+      if (!mod) return false;
+      await mod.getSharedHighlighter({
+        themes: [theme],
+        langs: [lang],
+        preferredHighlighter: 'shiki-js',
+      });
+      ready.add(key);
+      return true;
+    })
+    .catch(() => {
+      rejected.add(key);
+      return false;
+    })
+    .then((ok) => {
+      inflight.delete(key);
+      return ok;
+    });
+
+  inflight.set(key, load);
+  return load;
+}
+
+/** Monotonic stamp per element so a slow async highlight from a previous
+ *  content/theme never lands on top of a newer one. */
+const renderSeq = new WeakMap<HTMLElement, number>();
+let seqCounter = 0;
+
+type HighlightSwapListener = (el: HTMLElement) => void;
+const swapListeners = new Set<HighlightSwapListener>();
+
+/**
+ * Observe every write `applyHighlight` makes to a `<code>` element.
+ *
+ * Each write REPLACES the element's children, which destroys anything the
+ * annotation layer wrapped inside it — a whole-fence `<mark data-bind-id>` is
+ * gone the moment the palette changes or the first async grammar attach lands.
+ * Listeners run SYNCHRONOUSLY, immediately after the write, so re-applying a
+ * mark from a listener is ordered by construction rather than by a timer: a
+ * restore that ran before the swap is re-established in the same task the swap
+ * happened in, and a restore that runs after it finds the mark already there.
+ *
+ * Returns an unsubscribe function.
+ */
+export function onCodeHighlightSwap(listener: HighlightSwapListener): () => void {
+  swapListeners.add(listener);
+  return () => {
+    swapListeners.delete(listener);
+  };
+}
+
+function notifyHighlightSwap(el: HTMLElement): void {
+  if (swapListeners.size === 0) return;
+  for (const listener of Array.from(swapListeners)) {
+    // A misbehaving observer must never take syntax highlighting down with it.
+    try {
+      listener(el);
+    } catch {}
+  }
+}
+
+/**
+ * Drop-in replacement for `hljs.highlightElement(el)`.
+ *
+ * Writes plain text immediately so the block has its final size and content on
+ * the very first paint (no layout shift, no empty flash), then swaps in
+ * highlighted markup when the grammar is attached. When the grammar is already
+ * attached the highlighted markup is written straight away with no intermediate
+ * plain state.
+ */
+export function applyHighlight(
+  el: HTMLElement,
+  code: string,
+  lang: string | undefined,
+  theme: string,
+): void {
+  const seq = ++seqCounter;
+  renderSeq.set(el, seq);
+
+  // #1212: a fence with no language stays plain. Never guess.
+  if (!lang) {
+    el.textContent = code;
+    notifyHighlightSwap(el);
+    return;
+  }
+
+  const immediate = highlightToHtml(code, lang, theme);
+  if (immediate !== null) {
+    el.innerHTML = immediate;
+    notifyHighlightSwap(el);
+    return;
+  }
+
+  el.textContent = code;
+  notifyHighlightSwap(el);
+  void ensureHighlight(lang, theme).then((ok) => {
+    if (!ok || renderSeq.get(el) !== seq || !el.isConnected) return;
+    const html = highlightToHtml(code, lang, theme);
+    if (html === null) return;
+    el.innerHTML = html;
+    notifyHighlightSwap(el);
+  });
+}
+
+/** Test seam: forget every cached attachment and module handle. */
+export function __resetCodeHighlightCacheForTests(): void {
+  ready.clear();
+  rejected.clear();
+  inflight.clear();
+  pierre = undefined;
+  pierreLoad = undefined;
+}
+
+/**
+ * Test seam: stand in for `@pierre/diffs` so a test can drive real swaps
+ * (including WHEN the async one lands) without loading Shiki's full bundle.
+ * Pass `undefined` to go back to the real dynamic import.
+ */
+export function __setCodeHighlightModuleForTests(mod: PierreModule | undefined): void {
+  ready.clear();
+  rejected.clear();
+  inflight.clear();
+  pierre = mod;
+  pierreLoad = mod ? Promise.resolve(mod) : undefined;
+}

package/utils/codexModels.ts

@@ -0,0 +1,79 @@
+/**
+ * Codex Model Catalog
+ *
+ * Single source of truth for the Codex models offered by the launch panels
+ * (AgentsTab + GuideEmptyState) and their per-model reasoning efforts.
+ * Aligned with the Codex CLI's own model catalog (codex-cli 0.144): each
+ * entry carries the efforts that model actually accepts plus the CLI's
+ * default effort for it, so the UI never offers (or launches) an effort the
+ * model would reject. Lives in utils/ rather than AgentsTab so
+ * useAgentSettings can clamp saved efforts without importing a component.
+ */
+
+export interface CodexModelOption {
+  value: string;
+  label: string;
+  /** Reasoning efforts this model supports, per the Codex CLI catalog. */
+  efforts: string[];
+  /** The CLI's default effort for this model — the clamp target when a saved
+   *  effort isn't in `efforts`. */
+  defaultEffort: string;
+}
+
+// The two effort ladders in the current catalog. No model supports `minimal`
+// anymore (saved picks migrate to `low` — see useAgentSettings).
+const EFFORTS_THROUGH_XHIGH = ['low', 'medium', 'high', 'xhigh'];
+const EFFORTS_THROUGH_MAX = [...EFFORTS_THROUGH_XHIGH, 'max'];
+const EFFORTS_THROUGH_ULTRA = [...EFFORTS_THROUGH_MAX, 'ultra'];
+
+export const CODEX_MODELS: CodexModelOption[] = [
+  // GPT-5.6 naming scheme: `-sol` is the flagship, `-terra` is the mid
+  // price/performance tier, and `-luna` is the efficient high-volume tier.
+  { value: 'gpt-5.6-sol', label: 'GPT-5.6 Sol', efforts: EFFORTS_THROUGH_ULTRA, defaultEffort: 'low' },
+  { value: 'gpt-5.6-terra', label: 'GPT-5.6 Terra', efforts: EFFORTS_THROUGH_ULTRA, defaultEffort: 'medium' },
+  { value: 'gpt-5.6-luna', label: 'GPT-5.6 Luna', efforts: EFFORTS_THROUGH_MAX, defaultEffort: 'medium' },
+  { value: 'gpt-5.5', label: 'GPT-5.5', efforts: EFFORTS_THROUGH_XHIGH, defaultEffort: 'medium' },
+  { value: 'gpt-5.4', label: 'GPT-5.4', efforts: EFFORTS_THROUGH_XHIGH, defaultEffort: 'medium' },
+  { value: 'gpt-5.3-codex-spark', label: 'GPT-5.3 Codex Spark', efforts: EFFORTS_THROUGH_XHIGH, defaultEffort: 'high' },
+  // gpt-5.2 is retained: it was retired from the ChatGPT product (steered to
+  // 5.5) but the API still serves it, so API-key Codex users keep it. The
+  // rest of the 5.2/5.1 family (gpt-5.2-codex, gpt-5.1-codex-max,
+  // gpt-5.1-codex-mini — and gpt-5.3-codex before them) is API-shut-down per
+  // OpenAI's deprecations page (2026-07-23), dead for ALL auth modes; saved
+  // picks migrate in useAgentSettings. gpt-5.2 predates max/ultra, so it
+  // gets the safe historical effort set.
+  { value: 'gpt-5.2', label: 'GPT-5.2', efforts: EFFORTS_THROUGH_XHIGH, defaultEffort: 'medium' },
+  { value: 'gpt-5.4-mini', label: 'GPT-5.4 Mini', efforts: EFFORTS_THROUGH_XHIGH, defaultEffort: 'medium' },
+];
+
+/** Display labels for the reasoning-effort ids across every model. */
+export const CODEX_EFFORT_LABELS: Record<string, string> = {
+  low: 'Low',
+  medium: 'Medium',
+  high: 'High',
+  xhigh: 'XHigh',
+  max: 'Max',
+  ultra: 'Ultra',
+};
+
+// Fallback effort set for a model we don't know (a saved pick of a future
+// model id passes through migration untouched, so the picker still needs
+// SOMETHING to offer). low..xhigh is supported by every catalog model.
+const UNKNOWN_MODEL_EFFORTS = EFFORTS_THROUGH_XHIGH;
+
+/** The reasoning-effort picker options for one model — only the efforts that
+ *  model actually supports. */
+export function codexReasoningOptions(model: string): Array<{ value: string; label: string }> {
+  const entry = CODEX_MODELS.find((m) => m.value === model);
+  const efforts = entry?.efforts ?? UNKNOWN_MODEL_EFFORTS;
+  return efforts.map((value) => ({ value, label: CODEX_EFFORT_LABELS[value] ?? value }));
+}
+
+/** Clamp a saved reasoning effort to what the model supports: an unsupported
+ *  effort snaps to the model's catalog default effort. Unknown models pass
+ *  through unchanged (we can't know their supported set). */
+export function clampCodexReasoning(model: string, reasoning: string): string {
+  const entry = CODEX_MODELS.find((m) => m.value === model);
+  if (!entry) return reasoning;
+  return entry.efforts.includes(reasoning) ? reasoning : entry.defaultEffort;
+}

package/utils/domSelection.ts

@@ -0,0 +1,84 @@
+/** Elements whose text must not become part of a document annotation range. */
+const NON_ANNOTATABLE_SELECTOR = [
+  'button',
+  'input',
+  'textarea',
+  'select',
+  'script',
+  'style',
+  '[contenteditable]:not([contenteditable="false"])',
+  '[data-pinpoint-ignore]',
+  '.select-none',
+  '.annotation-toolbar',
+  '.katex',
+].join(',');
+
+const DOCUMENT_KEYBOARD_CONTROL_SELECTOR = [
+  'button',
+  'input',
+  'textarea',
+  'select',
+  'a[href]',
+  'summary',
+  '[contenteditable]:not([contenteditable="false"])',
+  '[role="button"]',
+  '[role="link"]',
+  '[role="textbox"]',
+  '[role="dialog"]',
+].join(',');
+
+/**
+ * Return the annotatable text nodes under an element in document order.
+ * Existing highlight wrappers remain eligible so Vim selections can overlap
+ * annotations just like pointer selections.
+ */
+export function getAnnotatableTextNodes(element: Element): Text[] {
+  const nodes: Text[] = [];
+  const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT, {
+    acceptNode(node) {
+      const parent = node.parentElement;
+      if (!parent || parent.closest(NON_ANNOTATABLE_SELECTOR)) {
+        return NodeFilter.FILTER_REJECT;
+      }
+      return node.textContent?.length
+        ? NodeFilter.FILTER_ACCEPT
+        : NodeFilter.FILTER_REJECT;
+    },
+  });
+
+  let node = walker.nextNode();
+  while (node) {
+    if (node instanceof Text) nodes.push(node);
+    node = walker.nextNode();
+  }
+  return nodes;
+}
+
+/**
+ * Return whether a keyboard event originated in an editable or interactive
+ * control that must retain ownership of ordinary typing keys.
+ */
+export function isDocumentKeyboardControl(target: EventTarget | null): boolean {
+  if (!(target instanceof Element)) return false;
+  return target.matches(DOCUMENT_KEYBOARD_CONTROL_SELECTOR)
+    || target.closest(DOCUMENT_KEYBOARD_CONTROL_SELECTOR) !== null
+    || (target instanceof HTMLElement && target.isContentEditable);
+}
+
+/**
+ * Create a text-node-anchored range spanning an element's annotatable text.
+ * Web-highlighter cannot paint element-node endpoints, so callers share this
+ * conversion instead of synthesizing subtly different ranges.
+ */
+export function createTextRange(element: HTMLElement): Range | null {
+  const nodes = getAnnotatableTextNodes(element);
+  const firstNode = nodes[0];
+  const lastNode = nodes[nodes.length - 1];
+
+  if (!firstNode || !lastNode) return null;
+
+  const range = document.createRange();
+  range.setStart(firstNode, 0);
+  range.setEnd(lastNode, lastNode.length);
+  return range;
+}

package/utils/htmlChrome.ts

@@ -0,0 +1,73 @@
+import { storage } from './storage';
+import { isStalePreference } from './preferenceTtl';
+
+/**
+ * Cross-session chrome visibility for raw-HTML annotate sessions.
+ *
+ * A raw-HTML session should open as close to "just the page" as possible, so
+ * the default is minimal paint: tools hidden, sidebar closed, annotations
+ * drawer closed. An explicit change the user makes (showing tools, opening the
+ * drawer) persists for later HTML sessions, but only while they keep using
+ * HTML annotate: state not refreshed within the staleness TTL (explicit
+ * changes or annotation activity re-stamp it) expires back to the minimal
+ * defaults. Persisted as a cookie (like every other cross-session UI pref;
+ * hook servers run on random ports, and cookies are scoped by domain, not
+ * port). Markdown sessions are untouched. A legacy record without a timestamp
+ * has an unknowable age and is treated as expired, which one-time resets
+ * everyone to the minimal defaults.
+ */
+
+const STORAGE_KEY = 'plannotator-html-chrome';
+
+export interface HtmlChromeState {
+  /** The header "Hide tools" toggle — true hides all annotation chrome. */
+  toolsHidden: boolean;
+  /** Whether the left sidebar was open when the user last left. */
+  sidebarOpen: boolean;
+  /** Whether the right annotations drawer was open when the user last left. */
+  panelOpen: boolean;
+}
+
+/** Default: minimal paint — everything hidden, both side surfaces closed. */
+export const DEFAULT_HTML_CHROME_STATE: HtmlChromeState = {
+  toolsHidden: true,
+  sidebarOpen: false,
+  panelOpen: false,
+};
+
+/** Pure resolution logic (exported for tests): raw cookie value → state. */
+export function resolveHtmlChromeState(
+  raw: string | null,
+  now: number = Date.now(),
+): HtmlChromeState {
+  if (!raw) return DEFAULT_HTML_CHROME_STATE;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null) {
+      return DEFAULT_HTML_CHROME_STATE;
+    }
+    const record = parsed as Record<string, unknown>;
+    if (isStalePreference(record.savedAt, now)) return DEFAULT_HTML_CHROME_STATE;
+    return {
+      toolsHidden: typeof record.toolsHidden === 'boolean'
+        ? record.toolsHidden
+        : DEFAULT_HTML_CHROME_STATE.toolsHidden,
+      sidebarOpen: typeof record.sidebarOpen === 'boolean'
+        ? record.sidebarOpen
+        : DEFAULT_HTML_CHROME_STATE.sidebarOpen,
+      panelOpen: typeof record.panelOpen === 'boolean'
+        ? record.panelOpen
+        : DEFAULT_HTML_CHROME_STATE.panelOpen,
+    };
+  } catch {
+    return DEFAULT_HTML_CHROME_STATE;
+  }
+}
+
+export function getHtmlChromeState(): HtmlChromeState {
+  return resolveHtmlChromeState(storage.getItem(STORAGE_KEY));
+}
+
+export function saveHtmlChromeState(state: HtmlChromeState): void {
+  storage.setItem(STORAGE_KEY, JSON.stringify({ ...state, savedAt: Date.now() }));
+}