@plannotator/ui 0.53.1 → 0.55.0

package/theme.css

@@ -4,6 +4,7 @@
 
 /* Theme files — each defines .theme-{name} (dark) and .theme-{name}.light */
 @import "./themes/plannotator.css";
+@import "./themes/plannotator-graphite.css";
 @import "./themes/claude-plus.css";
 @import "./themes/soft-pop.css";
 @import "./themes/adwaita.css";
@@ -63,10 +64,17 @@
  * selection stay on the textarea: the caret takes the foreground token, and
  * the selection uses a translucent primary wash so the overlay text stays
  * readable through it. During IME composition `.pn-ref-composing` restores
- * the native text so composition underlines render normally. */
+ * the native text so composition underlines render normally.
+ *
+ * No transition: the overlay's `visibility` flips instantly, so the global
+ * `*` 150ms color transition would fade the textarea's glyphs in (blank text
+ * at every composition start) and out (doubled text at every end). With
+ * Korean/Japanese/Chinese IMEs that swap happens on nearly every keystroke,
+ * and the whole field flickers. */
 .pn-ref-input {
   color: transparent;
   caret-color: var(--foreground);
+  transition: none;
 }
 .pn-ref-input::selection {
   background: color-mix(in oklab, var(--primary) 30%, transparent);
@@ -719,6 +727,14 @@
     --card-ring: rgba(255, 255, 255, 0.08);
     --card-shadow:
       0 0 0 1px var(--card-ring), 0 1px 3px 0 rgba(0, 0, 0, 0.2), 0 2px 8px -2px rgba(0, 0, 0, 0.3);
+    /* Floating surfaces with no border (the tooltip): a faint ring in the
+     * shadow plus a soft drop. The ink is the background taken toward black in
+     * its own hue (the Inbox's Soft float shadow, same formula). Hosts override
+     * --float-shadow to restyle every borderless float at once. */
+    --float-shadow-ink: var(--background);
+    --float-shadow:
+      0 0 0 1px color-mix(in oklch, var(--foreground) 8%, transparent),
+      0 16px 40px -10px color-mix(in oklch, var(--float-shadow-ink) 70%, transparent);
   }
 
   html {
@@ -760,6 +776,16 @@
     --card-shadow:
       0 0 0 1px var(--card-ring), 0 1px 3px 0 rgba(0, 0, 0, 0.04),
       0 2px 8px -2px rgba(0, 0, 0, 0.06);
+    --float-shadow-ink: var(--foreground);
+    --float-shadow:
+      0 0 0 1px color-mix(in oklch, var(--border) 70%, transparent),
+      0 12px 32px -8px color-mix(in oklch, var(--float-shadow-ink) 22%, transparent);
+  }
+
+  @supports (color: oklch(from red l c h)) {
+    :root:not(.light) {
+      --float-shadow-ink: oklch(from var(--background) calc(l * 0.2) calc(c * 0.5) h);
+    }
   }
 
   * {
@@ -767,6 +793,28 @@
   }
 }
 
+/* Inter's stylistic sets: ss01 (open digits), ss02 (disambiguation: I, l, 0)
+ * and cv01 (alternate one), set on body with font-feature-settings. That
+ * property is inherited by every font on the page, and feature tags mean
+ * different things in each font. On macOS, iOS and Windows that is the look
+ * users know (SF Pro, the system-ui themes' font, draws an open 4 and
+ * straight 6 and 9 with them), so it stays. On desktop Linux, Ubuntu Mono, the
+ * monospace fallback that code review diffs and gutters reach, draws ss02 as
+ * superscript digits (#1961). There (`pn-os-linux`, put on <html> before the
+ * first paint by ThemeProvider: see markRootPlatform in utils/platform.ts) the
+ * sets are named for Inter's families and applied with
+ * font-variant-alternates instead: a named value applies only to text a listed
+ * family renders, so monospace text, Pierre's diffs (inside their shadow
+ * roots), system-ui themes and any fallback font get none of them. */
+@font-feature-values "Inter Variable", "Inter", "InterVariable" {
+  @styleset {
+    pn-inter: 1 2;
+  }
+  @character-variant {
+    pn-inter-one: 1;
+  }
+}
+
 body {
   font-family: var(--font-sans);
   background: var(--background);
@@ -774,6 +822,11 @@ body {
   font-feature-settings: "ss01", "ss02", "cv01";
 }
 
+:root.pn-os-linux body {
+  font-feature-settings: normal;
+  font-variant-alternates: styleset(pn-inter) character-variant(pn-inter-one);
+}
+
 /* Safari extends the page canvas beneath its floating browser controls. The
  * plan document is a card-colored nested scroller, so leaving the outer canvas
  * on `--background` produces an opaque dark band around those controls. Match
@@ -1654,6 +1707,31 @@ body:has([data-popout="true"]) [data-sidebar-tabs="true"] {
   padding-left: 0.6rem;
   color: var(--muted-foreground);
 }
+/* GFM tables in Ask AI answers. The chat panel is narrow, so a wide table
+   scrolls sideways inside itself instead of widening the message. */
+.ai-markdown table {
+  display: block;
+  max-width: 100%;
+  overflow-x: auto;
+  border-collapse: collapse;
+  margin: 0.5rem 0;
+  font-size: 0.95em;
+}
+.ai-markdown th,
+.ai-markdown td {
+  border: 1px solid var(--border);
+  padding: 0.25rem 0.5rem;
+  text-align: left;
+  vertical-align: top;
+}
+.ai-markdown th {
+  background: color-mix(in oklab, var(--muted) 55%, transparent);
+  font-weight: 600;
+}
+.ai-markdown th[align="center"],
+.ai-markdown td[align="center"] { text-align: center; }
+.ai-markdown th[align="right"],
+.ai-markdown td[align="right"] { text-align: right; }
 
 /* Annotation highlights — shared by the plan editor and the code-review
    description annotations. (Moved here from packages/editor/index.css so both
@@ -1714,6 +1792,106 @@ body:has([data-popout="true"]) [data-sidebar-tabs="true"] {
   cursor: pointer;
 }
 
+/* Document text size (Settings → Display → Text size, #2066; see
+   utils/documentTextSize). The app sets data-doc-text-size and
+   --doc-text-scale (size / 15) on the document element only away from the
+   default, so at the default none of this applies and the document draws
+   exactly as it always has. Scoped to the blocks of a document container
+   (data-doc-text-root: the Viewer's article and the plan diff's): every block
+   carries data-block-id, the plan diff's blocks data-diff-block-index, the
+   frontmatter card and the raw diff data-doc-text. So the header, panels,
+   badges, menus and popovers keep their size; diagrams draw themselves and the
+   table / diagram popouts are app chrome, so both are left out. Named sizes
+   scale through Tailwind's type scale, the inherited size through each block
+   root, the renderers' fixed sizes one by one (sizes under 12 px, the card's
+   pills and the diff gutters, stay as they are), and the list markers,
+   checkboxes and the question card's controls with the text they sit beside.
+   Unlayered, so it outranks Tailwind's utilities, except the inherited size,
+   which sits in the base layer so a block's own size class still wins. */
+[data-doc-text-size] [data-doc-text-root] :is([data-block-id], [data-diff-block-index], [data-doc-text]):not([data-diagram-block], [data-diagram-block] *, [data-popout], [data-popout] *) {
+  --text-xs: max(11px, calc(0.75rem * var(--doc-text-scale, 1)));
+  --text-sm: calc(0.875rem * var(--doc-text-scale, 1));
+  --text-base: calc(1rem * var(--doc-text-scale, 1));
+  --text-lg: calc(1.0625rem * var(--doc-text-scale, 1));
+  --text-xl: calc(1.1875rem * var(--doc-text-scale, 1));
+  --text-2xl: calc(1.375rem * var(--doc-text-scale, 1));
+  --text-3xl: calc(1.625rem * var(--doc-text-scale, 1));
+  --text-4xl: calc(1.875rem * var(--doc-text-scale, 1));
+  --text-5xl: calc(2rem * var(--doc-text-scale, 1));
+}
+@layer base {
+  /* The size a block inherits (a list row and its marker, an alert's title):
+     only on the outermost block, so a nested one never compounds it. */
+  [data-doc-text-size] [data-doc-text-root] :is([data-block-id], [data-diff-block-index], [data-doc-text]):not([data-diagram-block], [data-diagram-block] *, [data-popout], [data-popout] *):not(:is([data-block-id], [data-diff-block-index], [data-doc-text]) *) {
+    font-size: calc(1em * var(--doc-text-scale, 1));
+  }
+}
+[data-doc-text-size] [data-doc-text-root] :is([data-block-id], [data-diff-block-index], [data-doc-text], [data-block-id] *, [data-diff-block-index] *, [data-doc-text] *):not([data-diagram-block], [data-diagram-block] *, [data-popout], [data-popout] *).text-\[15px\] {
+  font-size: calc(15px * var(--doc-text-scale, 1));
+}
+[data-doc-text-size] [data-doc-text-root] :is([data-block-id], [data-diff-block-index], [data-doc-text], [data-block-id] *, [data-diff-block-index] *, [data-doc-text] *):not([data-diagram-block], [data-diagram-block] *, [data-popout], [data-popout] *).text-\[13\.5px\] {
+  font-size: calc(13.5px * var(--doc-text-scale, 1));
+}
+[data-doc-text-size] [data-doc-text-root] :is([data-block-id], [data-diff-block-index], [data-doc-text], [data-block-id] *, [data-diff-block-index] *, [data-doc-text] *):not([data-diagram-block], [data-diagram-block] *, [data-popout], [data-popout] *).text-\[13px\] {
+  font-size: calc(13px * var(--doc-text-scale, 1));
+}
+[data-doc-text-size] [data-doc-text-root] :is([data-block-id], [data-diff-block-index], [data-doc-text], [data-block-id] *, [data-diff-block-index] *, [data-doc-text] *):not([data-diagram-block], [data-diagram-block] *, [data-popout], [data-popout] *).text-\[12\.5px\] {
+  font-size: calc(12.5px * var(--doc-text-scale, 1));
+}
+/* Fenced code (`pre code.pn-code`, 0.8125rem in the app's stylesheet). */
+[data-doc-text-size] [data-doc-text-root] :is([data-block-id], [data-diff-block-index], [data-doc-text]):not([data-diagram-block], [data-diagram-block] *, [data-popout], [data-popout] *) pre code.pn-code {
+  font-size: calc(0.8125rem * var(--doc-text-scale, 1));
+}
+/* A question card's context (QuestionContext's own stylesheet). */
+[data-doc-text-size] [data-doc-text-root] [data-block-id] .question-context :is(p, .text-sm) {
+  font-size: calc(13px * var(--doc-text-scale, 1));
+}
+[data-doc-text-size] [data-doc-text-root] [data-block-id] .question-context :is(h1, h2) {
+  font-size: calc(14px * var(--doc-text-scale, 1));
+}
+[data-doc-text-size] [data-doc-text-root] [data-block-id] .question-context h3 {
+  font-size: calc(13.5px * var(--doc-text-scale, 1));
+}
+/* List markers (ListMarker): the numeral's column and the task circle. */
+[data-doc-text-size] [data-doc-text-root] [data-list-numeral] {
+  min-width: calc(1.5rem * var(--doc-text-scale, 1)) !important;
+}
+[data-doc-text-size] [data-doc-text-root] [data-list-check] {
+  width: calc(1rem * var(--doc-text-scale, 1));
+  height: calc(1rem * var(--doc-text-scale, 1));
+  margin-top: calc(3px * var(--doc-text-scale, 1));
+}
+/* A question card's choice controls (QuestionBlock), beside 13.5 px text. */
+[data-doc-text-size] [data-doc-text-root] [data-question-control] {
+  width: calc(15px * var(--doc-text-scale, 1));
+  height: calc(15px * var(--doc-text-scale, 1));
+}
+[data-doc-text-size] [data-doc-text-root] [data-question-control]:is(input) {
+  margin-top: calc(3px * var(--doc-text-scale, 1));
+}
+[data-doc-text-size] [data-doc-text-root] [data-question-control]:not(input) {
+  font-size: calc(11px * var(--doc-text-scale, 1));
+}
+
+/* Document font (Settings → Display → Document font, #1657; see
+   utils/documentFont). The app sets data-doc-font and --doc-font-family on the
+   document element only away from the default, so at the default none of this
+   applies. Same scope as Text size: the outermost blocks of a document
+   container, leaving out diagrams and the popouts. Headings, lists, tables and
+   question cards inherit it; code keeps its monospace font because Tailwind's
+   preflight sets it on code / pre and font-mono marks inline code, the raw
+   diff and the gutters. In the base layer so a block's own font utility
+   (font-mono on the raw diff) still wins. */
+@layer base {
+  [data-doc-font] [data-doc-text-root] :is([data-block-id], [data-diff-block-index], [data-doc-text]):not([data-diagram-block], [data-diagram-block] *, [data-popout], [data-popout] *):not(:is([data-block-id], [data-diff-block-index], [data-doc-text]) *) {
+    font-family: var(--doc-font-family);
+  }
+  /* The HTML embed's and SVG fence's captions and Show more are controls. */
+  [data-doc-font] [data-doc-text-root] :is(figcaption, [data-html-embed-more]) {
+    font-family: var(--font-sans);
+  }
+}
+
 /* Reduced motion: Base UI popups (dialogs, menus, popovers, tooltips) animate
    via [data-starting-style]/[data-ending-style] transitions — those attributes
    only exist during the enter/exit phases, so zeroing transitions here makes

package/themes/plannotator-graphite.css

@@ -0,0 +1,66 @@
+/* Plannotator Graphite. Dark half: a near-neutral graphite tuned to stay readable
+   in daylight (lifted ground, larger surface steps, secondary text at APCA Lc 60+,
+   the purple primary kept inside sRGB). Light half: Plannotator's light, unchanged.
+   Approved 2026-10-24 (.product/approved/plannotator-graphite/). */
+.theme-plannotator-graphite {
+  --background: oklch(0.225 0.006 286);
+  --foreground: oklch(0.945 0.003 286);
+  --card: oklch(0.295 0.006 286);
+  --card-foreground: oklch(0.945 0.003 286);
+  --popover: oklch(0.375 0.006 286);
+  --popover-foreground: oklch(0.945 0.003 286);
+  --primary: oklch(0.765 0.124 283);
+  --primary-foreground: oklch(0.20 0.01 286);
+  --secondary: oklch(0.740 0.123 180);
+  --secondary-foreground: oklch(0.20 0.01 286);
+  --muted: oklch(0.355 0.006 286);
+  --muted-foreground: oklch(0.820 0.007 286);
+  --accent: oklch(0.765 0.156 60);
+  --accent-foreground: oklch(0.20 0.01 286);
+  --destructive: oklch(0.770 0.124 25);
+  --destructive-foreground: oklch(0.20 0.01 286);
+  --border: oklch(0.435 0.006 286);
+  --input: oklch(0.355 0.006 286);
+  --ring: oklch(0.765 0.124 283);
+  --success: oklch(0.735 0.170 150);
+  --success-foreground: oklch(0.20 0.01 286);
+  --warning: oklch(0.760 0.144 85);
+  --warning-foreground: oklch(0.20 0.01 286);
+
+  --font-sans: 'Inter Variable', 'Inter', system-ui, sans-serif;
+  --font-mono: 'Geist Mono Variable', 'Geist Mono', 'JetBrains Mono', 'Fira Code', ui-monospace, monospace;
+  --radius: 0.625rem;
+
+  --code-bg: oklch(0.355 0.006 286);
+  --focus-highlight: oklch(0.745 0.116 200);
+}
+
+.theme-plannotator-graphite.light {
+  /* Plannotator light inherits this from its own dark block; keep the same value. */
+  --focus-highlight: oklch(0.70 0.20 200);
+  --background: oklch(0.97 0.005 260);
+  --foreground: oklch(0.18 0.02 260);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.18 0.02 260);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.18 0.02 260);
+  --primary: oklch(0.50 0.25 280);
+  --primary-foreground: oklch(1 0 0);
+  --secondary: oklch(0.50 0.18 180);
+  --secondary-foreground: oklch(1 0 0);
+  --muted: oklch(0.92 0.01 260);
+  --muted-foreground: oklch(0.40 0.02 260);
+  --accent: oklch(0.60 0.22 50);
+  --accent-foreground: oklch(0.18 0.02 260);
+  --destructive: oklch(0.50 0.25 25);
+  --destructive-foreground: oklch(1 0 0);
+  --border: oklch(0.88 0.01 260);
+  --input: oklch(0.92 0.01 260);
+  --ring: oklch(0.50 0.25 280);
+  --success: oklch(0.45 0.20 150);
+  --success-foreground: oklch(1 0 0);
+  --warning: oklch(0.55 0.18 85);
+  --warning-foreground: oklch(0.18 0.02 260);
+
+  --code-bg: oklch(0.92 0.01 260);
+}

package/types.ts

@@ -1,18 +1,21 @@
 import type { DiagramAnchor } from '@plannotator/core/diagram-anchor';
-import type { DiagramRenderKind } from '@plannotator/core/annotatable';
+import type { ImageRegion } from '@plannotator/core/image-region';
+import type { DocumentRenderKind } from '@plannotator/core/annotatable';
 import type { QuestionAnswer } from '@plannotator/core/question-block';
 
 export type { DiagramAnchor } from '@plannotator/core/diagram-anchor';
+export type { ImageRegion, ImageRegionBox } from '@plannotator/core/image-region';
 export type { QuestionAnswer } from '@plannotator/core/question-block';
-export type { DiagramRenderKind } from '@plannotator/core/annotatable';
+export type { DiagramRenderKind, DocumentRenderKind } from '@plannotator/core/annotatable';
 
 /**
  * How a document's body is rendered. `markdown` and `html` are the original
  * pair; the two diagram kinds are whole-file diagram sources (.mmd/.mermaid,
  * .dot/.gv) that render as ONE diagram through the same engine a ```mermaid
- * fence uses — see diagramDocumentBlocks in utils/parser.
+ * fence uses — see diagramDocumentBlocks in utils/parser. `asciidoc` is an
+ * .adoc source parsed by utils/asciidocParser into the same block model.
  */
-export type DocumentRenderAs = 'markdown' | 'html' | DiagramRenderKind;
+export type DocumentRenderAs = 'markdown' | 'html' | DocumentRenderKind;
 
 export enum AnnotationType {
   DELETION = 'DELETION',
@@ -102,6 +105,7 @@ export interface Annotation {
   elementContext?: HtmlElementContext; // raw-HTML / live-app pinpoint: bounded agent-facing description of the primary element (never used by restore)
   htmlAdditionalTargets?: HtmlAnnotationTarget[]; // raw-HTML shift-click multi-select: extra elements this one comment covers (primary stays htmlAnchor/originalText)
   diagramAnchor?: DiagramAnchor; // a comment on a rendered diagram part (Mermaid / Graphviz fence): the part's own id, label and document source line; the highlighter skips it and the diagram overlay restores it (see @plannotator/core/diagram-anchor)
+  imageRegion?: ImageRegion; // a comment on part of an image in a markdown document (#2100): the image's src as written, its document line, and the box in the image's own pixels; drawn by the image viewer, skipped by the highlighter, exported as `Image:` / `Region:` lines (see @plannotator/core/image-region)
   questionAnswer?: QuestionAnswer; // the reviewer's answer to a `:::question` block (id `ann-question-<key>`): the Viewer draws the answer from it, the highlighter skips it, and the export prints it in the "Answers to your questions" section instead of as a numbered comment (see @plannotator/core/question-block)
   // web-highlighter metadata for cross-element selections
   startMeta?: AnnotationTextMeta;
@@ -355,8 +359,10 @@ export interface CodeAnnotation {
   gitButlerBase?: string;
   /** Exact server snapshot that supplied the GitButler line coordinates. */
   gitButlerSnapshotId?: string;
+  /** Local Git worktree + branch + comparison identity supplied by the server. */
+  localReviewTarget?: string;
   /**
-   * PR reviews only (#1590): the text of the diff lines this line comment
+   * PR and local Git reviews (#1590): the text of the diff lines this line comment
    * was anchored to at creation (lineStart..lineEnd on `side`, joined with
    * "\n"). When a saved draft is restored against a different patch, the
    * comment keeps its position only if these lines still read the same;
@@ -365,7 +371,7 @@ export interface CodeAnnotation {
    */
   anchorText?: string;
   /**
-   * PR reviews only (#1590): the lines around the anchor on the same side
+   * PR and local Git reviews (#1590): the lines around the anchor on the same side
    * (up to two before and two after; `null` where a line is outside the patch
    * hunks) and the hunk header's function context (`hunk`, when git printed
    * one), so a comment on a common line (`}`, `return null;`) only keeps its
@@ -373,19 +379,30 @@ export interface CodeAnnotation {
    */
   anchorContext?: { before: (string | null)[]; after: (string | null)[]; hunk?: string };
   /**
-   * PR reviews only (#1590): the review snapshot id of the diff whose line
+   * PR and local Git reviews (#1590): the review snapshot id of the diff whose line
    * coordinates this comment uses. Re-stamped when a later diff passes the
    * anchor check; a line comment is only posted inline when this matches the
    * diff currently known for its PR.
    */
   anchorSnapshot?: string;
   /**
-   * Set when a restored PR draft's comment no longer matches the code it was
-   * written on (the PR changed between sessions). Its line numbers refer to
+   * Set when a comment no longer matches the code it was written on.
+   * Its line numbers refer to
    * the earlier version: it is listed and exported (labelled) but never drawn
    * inline on the current diff and never posted as an inline PR comment.
    */
   outdated?: boolean;
+  /**
+   * Code review only: a comment on lines outside the diff — a file the review
+   * does not change (opened from All files), or lines of a changed file
+   * outside its hunks (its Whole file view). Line-scoped on the new side,
+   * with the commented code in `anchorText`. The agent gets it with the file,
+   * lines and code; a PR review posts it in the review body with the quoted
+   * code and a permalink, never inline (no platform accepts an inline comment
+   * outside the PR's diff). Never marked outdated by a diff re-check.
+   * Additive: annotations without it behave exactly as before.
+   */
+  outsideDiff?: boolean;
   /**
    * Code review only: a comment made by selecting text in a Markdown file's
    * rendered preview. Always file-scoped (`scope: 'file'`); `lineStart` /

package/utils/agentSwitch.ts

@@ -9,14 +9,19 @@
  * stored is surface-specific: plan approval keeps its historical hand-off to the
  * build agent, while review feedback stays on the current agent.
  *
- * Uses cookies (not localStorage) because each hook invocation runs on a
- * random port, and localStorage is scoped by origin including port.
+ * Stored through the settings registry (`agentSwitch` in config/settings.ts):
+ * cookies (not localStorage, because each hook invocation runs on a random
+ * port) plus `agentSwitch` in ~/.plannotator/config.json, which wins over the
+ * cookie (#1390: the Glimpse webview keeps no cookies between runs).
  */
 
-import { storage } from './storage';
+import { configStore } from '../config/configStore';
 
-const STORAGE_KEY = 'plannotator-agent-switch';
-const CUSTOM_NAME_KEY = 'plannotator-agent-custom';
+/** The two configStore calls this module makes; tests pass a fresh store. */
+interface AgentSwitchStore {
+  get(key: 'agentSwitch'): { switchTo: string; customName?: string } | null;
+  set(key: 'agentSwitch', value: { switchTo: string; customName?: string } | null): void;
+}
 
 // AgentSwitchOption is now a string to support dynamic agent names from OpenCode
 export type AgentSwitchOption = string;
@@ -58,25 +63,26 @@ export function getAgentSwitchDefaults(surface: AgentSwitchSurface = 'plan'): Ag
  * An explicit user choice applies to every surface; only the unset default
  * varies by surface.
  */
-export function getAgentSwitchSettings(surface: AgentSwitchSurface = 'plan'): AgentSwitchSettings {
-  const stored = storage.getItem(STORAGE_KEY);
-  const customName = storage.getItem(CUSTOM_NAME_KEY) || undefined;
-
-  // Accept any non-empty string (supports dynamic agent names from OpenCode)
-  if (stored) {
-    return { switchTo: stored, customName };
-  }
-  return getAgentSwitchDefaults(surface);
+export function getAgentSwitchSettings(
+  surface: AgentSwitchSurface = 'plan',
+  store: AgentSwitchStore = configStore,
+): AgentSwitchSettings {
+  const stored = store.get('agentSwitch');
+  return stored ? { ...stored } : getAgentSwitchDefaults(surface);
 }
 
 /**
- * Save agent switch settings to storage
+ * Save agent switch settings: cookie at once, config.json through the
+ * registry's debounced POST /api/config.
  */
-export function saveAgentSwitchSettings(settings: AgentSwitchSettings): void {
-  storage.setItem(STORAGE_KEY, settings.switchTo);
-  if (settings.customName) {
-    storage.setItem(CUSTOM_NAME_KEY, settings.customName);
-  }
+export function saveAgentSwitchSettings(
+  settings: AgentSwitchSettings,
+  store: AgentSwitchStore = configStore,
+): void {
+  store.set('agentSwitch', {
+    switchTo: settings.switchTo,
+    ...(settings.customName && { customName: settings.customName }),
+  });
 }
 
 /**
@@ -95,3 +101,18 @@ export function getEffectiveAgentName(settings: AgentSwitchSettings): string | u
   }
   return settings.switchTo;
 }
+
+/**
+ * The agent name an approval hands off to, for display ("Approve → build"):
+ * a discovered agent's display name, the custom name, or the stored id when
+ * it matches nothing discovered. Null when switching is off.
+ */
+export function agentSwitchTargetLabel(
+  setting: AgentSwitchSettings,
+  agents: ReadonlyArray<{ id: string; name: string }>,
+): string | null {
+  if (setting.switchTo === 'disabled') return null;
+  if (setting.switchTo === 'custom') return setting.customName || null;
+  const match = agents.find((a) => a.id.toLowerCase() === setting.switchTo.toLowerCase());
+  return match?.name ?? setting.switchTo;
+}

package/utils/agentToolSetting.ts

@@ -111,5 +111,5 @@ export function agentToolAppliesWhen(host: AgentToolHost): string {
 export function agentToolCostNote(host: AgentToolHost): string {
   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.';
+  return 'Adds about 800 tokens to every request.';
 }

package/utils/aiChatFormat.ts

@@ -2,14 +2,30 @@ import { createElement, type ReactNode } from 'react';
 import { marked } from 'marked';
 import DOMPurify from 'dompurify';
 
+/**
+ * What DOMPurify keeps of an Ask AI answer. Every tag and attribute marked
+ * writes for the markdown an answer uses must be listed here, or DOMPurify
+ * drops the element and keeps only its text (#2069: tables ran together).
+ */
+export const CHAT_SANITIZE_CONFIG = {
+  ALLOWED_TAGS: [
+    'p', 'br', 'strong', 'em', 'code', 'pre', 'ul', 'ol', 'li',
+    'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'hr', 'a', 'blockquote',
+    'table', 'thead', 'tbody', 'tr', 'th', 'td',
+  ],
+  // `align` is what marked writes on th/td for aligned GFM columns.
+  ALLOWED_ATTR: ['href', 'rel', 'class', 'align'],
+};
+
+/** The markdown step of {@link renderChatMarkdown}, before sanitizing. */
+export function chatMarkdownToHtml(text: string): string {
+  return marked.parse(text, { async: false, breaks: true }) as string;
+}
+
 export function renderChatMarkdown(text: string): ReactNode {
-  const html = marked.parse(text, { async: false, breaks: true }) as string;
-  const clean = DOMPurify.sanitize(html, {
-    ALLOWED_TAGS: [
-      'p', 'br', 'strong', 'em', 'code', 'pre', 'ul', 'ol', 'li',
-      'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'hr', 'a', 'blockquote',
-    ],
-    ALLOWED_ATTR: ['href', 'rel', 'class'],
+  const clean = DOMPurify.sanitize(chatMarkdownToHtml(text), {
+    ALLOWED_TAGS: [...CHAT_SANITIZE_CONFIG.ALLOWED_TAGS],
+    ALLOWED_ATTR: [...CHAT_SANITIZE_CONFIG.ALLOWED_ATTR],
   });
 
   return createElement('div', {

package/utils/annotationHelpers.ts

@@ -60,13 +60,41 @@ export interface TocItem {
   annotationCount: number;
 }
 
+/**
+ * The headings a Contents list shows, in document order: levels 1 to
+ * `maxLevel` (3 by default, plan review's list). The one place that picks
+ * them: `TableOfContents`, plan review's "has entries" check and the contents
+ * rail (`MarkdownContentsRail`, levels 1 to 4) all read it.
+ */
+export function tocHeadings(blocks: readonly Block[], maxLevel = 3): Block[] {
+  return blocks
+    .filter(b => b.type === 'heading' && (b.level ?? 0) <= maxLevel)
+    .sort((a, b) => a.order - b.order);
+}
+
+/** The contents rail lists headings of levels 1 to this (`MarkdownContentsRail`). */
+export const CONTENTS_RAIL_MAX_LEVEL = 4;
+/** The contents rail shows for a document with at least this many of them. */
+export const CONTENTS_RAIL_MIN_HEADINGS = 4;
+/** The contents rail shows in a scroll element at least this wide (and with a 68 px gutter). */
+export const CONTENTS_RAIL_MIN_PANE_WIDTH = 480;
+
+/**
+ * Whether a document gets the contents rail: at least
+ * `CONTENTS_RAIL_MIN_HEADINGS` headings of levels 1 to
+ * `CONTENTS_RAIL_MAX_LEVEL`. Kept out of the rail's own module, so a host can
+ * decide without loading the (lazy) rail.
+ */
+export function hasContentsRailHeadings(blocks: readonly Block[]): boolean {
+  return tocHeadings(blocks, CONTENTS_RAIL_MAX_LEVEL).length >= CONTENTS_RAIL_MIN_HEADINGS;
+}
+
 export function buildTocHierarchy(
   blocks: Block[],
-  annotationCounts: Map<string, number>
+  annotationCounts: Map<string, number>,
+  maxLevel = 3
 ): TocItem[] {
-  const headings = blocks
-    .filter(b => b.type === 'heading' && (b.level ?? 0) <= 3)
-    .sort((a, b) => a.order - b.order);
+  const headings = tocHeadings(blocks, maxLevel);
   
   const root: TocItem[] = [];
   const stack: TocItem[] = [];

package/utils/annotationOwnsHighlight.ts

@@ -10,18 +10,20 @@ export const CHECKBOX_ANNOTATION_PREFIX = 'ann-checkbox-';
  *
  * Not: comments made in the plan diff view (`diffContext`, `blockId`
  * `diff-block-N`, drawn by the diff view), general comments, checkbox
- * toggles, and answers to `:::question` blocks (drawn by the question card).
+ * toggles, answers to `:::question` blocks (drawn by the question card), and
+ * comments on part of an image (`imageRegion`, drawn by the image viewer).
  * Restoring any of those through the highlighter finds no text, so it would
  * be reported unanchored and its `blockId` rewritten. Every caller that
  * re-applies a stored list filters with this, and the highlighter skips the
  * same rows itself.
  */
 export function annotationOwnsHighlight(
-  annotation: Pick<Annotation, 'id' | 'type' | 'diffContext' | 'questionAnswer'>,
+  annotation: Pick<Annotation, 'id' | 'type' | 'diffContext' | 'questionAnswer'> & Partial<Pick<Annotation, 'imageRegion'>>,
 ): boolean {
   return !annotation.diffContext
     && annotation.type !== AnnotationType.GLOBAL_COMMENT
     && !annotation.id.startsWith(CHECKBOX_ANNOTATION_PREFIX)
     && annotation.questionAnswer == null
+    && annotation.imageRegion == null
     && !annotation.id.startsWith(QUESTION_ANSWER_ANNOTATION_PREFIX);
 }