@plannotator/ui 0.45.1 → 0.46.1

package/config/settings.ts

@@ -236,15 +236,21 @@ export const SETTINGS = {
 
   // Which left-panel view a code review OPENS in. 'sections' = the git-status
   // view (Committed/Changes/Untracked); 'tree' = the classic file tree.
-  // Cookie-only. Written ONLY by Settings and the first-run setup dialog —
-  // the in-review header toggle is session-scoped and never writes this
-  // (looking at another view mid-review must not silently change the default).
+  // Cookie-only. Written ONLY by Settings — the in-review header toggle is
+  // session-scoped and never writes this (looking at another view mid-review
+  // must not silently change the default).
+  //
+  // The default is 'tree': the classic file tree renders every diff type, so
+  // the (reviewPanelView, defaultDiffType) pair is trivially consistent for a
+  // reviewer who has chosen neither. 'sections' is reachable from the panel's
+  // Tree | Git status | Commits toggle and settable as the default here in
+  // Settings. Anyone with a persisted cookie keeps whatever they chose.
   //
   // Deliberately NOT a value here: 'commits'. The Commits view is session-only
   // and never the opening view — a review always opens on files. A
   // previously-persisted 'commits' cookie is treated as unset.
   reviewPanelView: {
-    defaultValue: 'sections' as 'sections' | 'tree',
+    defaultValue: 'tree' as 'sections' | 'tree',
     fromCookie: () => {
       const v = storage.getItem('plannotator-review-panel-view');
       return v === 'tree' || v === 'sections' ? v : undefined;

package/hooks/useAgentSettings.ts

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
+import { resolveEffortChoice, resolveModelChoice } from '@plannotator/core/model-catalog';
 import { getItem, setItem } from '../utils/storage';
-import { clampCodexReasoning } from '../utils/codexModels';
+import type { ModelCatalog, ModelCatalogs } from './useModelCatalogs';
 
 const COOKIE_KEY = 'plannotator.agents';
 
@@ -16,16 +17,17 @@ const COOKIE_KEY = 'plannotator.agents';
 // would clobber writes exactly like before.
 const settingsListeners = new Set<(s: AgentSettingsState) => void>();
 
-export const DEFAULT_CLAUDE_MODEL = 'claude-opus-5';
+// Claude defaults are the CLI's latest-resolving aliases, so they never go
+// stale. Codex defaults are '' — "the model Codex's own list marks default",
+// resolved against the discovered catalog (see useModelCatalogs).
+export const DEFAULT_CLAUDE_MODEL = 'opus';
 export const DEFAULT_CLAUDE_EFFORT = 'high';
-// gpt-5.3-codex is deprecated (ChatGPT-account Codex rejects it outright) —
-// default to the current flagship everywhere.
-export const DEFAULT_CODEX_MODEL = 'gpt-5.5';
+export const DEFAULT_CODEX_MODEL = '';
 export const DEFAULT_CODEX_REASONING = 'high';
 export const DEFAULT_CODEX_FAST = false;
 export const DEFAULT_TOUR_CLAUDE_MODEL = 'sonnet';
 export const DEFAULT_TOUR_CLAUDE_EFFORT = 'medium';
-export const DEFAULT_TOUR_CODEX_MODEL = 'gpt-5.5';
+export const DEFAULT_TOUR_CODEX_MODEL = '';
 export const DEFAULT_TOUR_CODEX_REASONING = 'medium';
 export const DEFAULT_TOUR_CODEX_FAST = false;
 export const DEFAULT_GUIDE_CLAUDE_MODEL = 'sonnet';
@@ -33,7 +35,7 @@ export const DEFAULT_GUIDE_CLAUDE_MODEL = 'sonnet';
 // orientation doc the reviewer is actively waiting on, and newer models at
 // low effort chapter a diff well. Guide-scoped only — tour/review keep medium.
 export const DEFAULT_GUIDE_CLAUDE_EFFORT = 'low';
-export const DEFAULT_GUIDE_CODEX_MODEL = 'gpt-5.5';
+export const DEFAULT_GUIDE_CODEX_MODEL = '';
 export const DEFAULT_GUIDE_CODEX_REASONING = 'low';
 // No DEFAULT_GUIDE_CODEX_FAST: fast mode is deliberately not offered for
 // guide (product decision — see AgentsTab's guide codex config block), so
@@ -175,66 +177,16 @@ const initialState: AgentSettingsState = {
   guideCopilot: { model: DEFAULT_GUIDE_COPILOT_MODEL },
 };
 
-// One-shot migration: drop any cached "none" codex reasoning entries. The
-// dropdown no longer offers "None" (codex-rs rejects it as a config value);
-// fall back to the default instead of shipping an invalid flag. Saved
-// "minimal" entries migrate to "low": no current Codex model supports
-// minimal, and low is the nearest effort that every model does.
-export function sanitizeCodexPerModel(
-  perModel: Record<string, { reasoning: string; fast: boolean }> | undefined,
-): Record<string, { reasoning: string; fast: boolean }> {
-  if (!perModel) return {};
-  const out: Record<string, { reasoning: string; fast: boolean }> = {};
-  for (const [model, entry] of Object.entries(perModel)) {
-    if (!entry || typeof entry !== 'object') continue;
-    if (entry.reasoning === 'none') {
-      if (entry.fast) out[model] = { reasoning: DEFAULT_CODEX_REASONING, fast: true };
-      continue;
-    }
-    if (entry.reasoning === 'minimal') {
-      out[model] = { ...entry, reasoning: 'low' };
-      continue;
-    }
-    out[model] = entry;
-  }
-  return out;
-}
-
-// Saved model IDs that migrate to a direct replacement: the stale gpt-5.6
-// slug (renamed to -sol when the tiered family shipped) and gpt-5.1-codex-mini
-// (API shutdown 2026-07-23; gpt-5.4-mini is OpenAI's recommended replacement).
-const RENAMED_CODEX_MODELS: Record<string, string> = {
-  'gpt-5.6': 'gpt-5.6-sol',
-  'gpt-5.1-codex-mini': 'gpt-5.4-mini',
-};
-
-// Saved model IDs with no direct replacement — migrate to the surface's
-// fallback. gpt-5.3-codex is rejected outright by ChatGPT-account Codex;
-// gpt-5.2-codex and gpt-5.1-codex-max hit the API-level shutdown on
-// 2026-07-23 (OpenAI recommends gpt-5.5, which every fallback already is).
-const RETIRED_CODEX_MODELS = new Set(['gpt-5.3-codex', 'gpt-5.2-codex', 'gpt-5.1-codex-max']);
-
-// One-shot model migrations for a saved Codex section. Keep its per-model
-// preferences aligned with the canonical model ID while sanitizing them.
-export function migrateCodexSection(
-  section: { model?: unknown; perModel?: Record<string, { reasoning: string; fast: boolean }> } | undefined,
+// A saved Claude/Codex section. Stale model ids are NOT migrated here: they
+// are resolved against the discovered catalog at read time (effectiveModel).
+function parseModelSection<P>(
+  section: { model?: unknown; perModel?: unknown } | undefined,
   fallback: string,
-): CodexSection {
-  const perModel = sanitizeCodexPerModel(section?.perModel);
-  for (const [legacy, replacement] of Object.entries(RENAMED_CODEX_MODELS)) {
-    const legacyPreference = perModel[legacy];
-    if (legacyPreference) {
-      perModel[replacement] ??= legacyPreference;
-      delete perModel[legacy];
-    }
-  }
-
-  const savedModel = section?.model;
-  const model =
-    typeof savedModel !== 'string' || RETIRED_CODEX_MODELS.has(savedModel)
-      ? fallback
-      : (RENAMED_CODEX_MODELS[savedModel] ?? savedModel);
-  return { model, perModel };
+): { model: string; perModel: Record<string, P> } {
+  return {
+    model: typeof section?.model === 'string' ? section.model : fallback,
+    perModel: (section?.perModel as Record<string, P> | undefined) ?? {},
+  };
 }
 
 function parseEngine(value: unknown): AgentEngine {
@@ -280,11 +232,8 @@ function readCookie(): AgentSettingsState {
       reviewProfileByEngine: parseReviewProfileByEngine(parsed),
       tourEngine: parseEngine(parsed.tourEngine),
       guideEngine: parseReviewEngine(parsed.guideEngine),
-      claude: {
-        model: typeof parsed.claude?.model === 'string' ? parsed.claude.model : DEFAULT_CLAUDE_MODEL,
-        perModel: parsed.claude?.perModel ?? {},
-      },
-      codex: migrateCodexSection(parsed.codex, DEFAULT_CODEX_MODEL),
+      claude: parseModelSection(parsed.claude, DEFAULT_CLAUDE_MODEL),
+      codex: parseModelSection(parsed.codex, DEFAULT_CODEX_MODEL),
       cursor: {
         model: typeof parsed.cursor?.model === 'string' ? parsed.cursor.model : DEFAULT_CURSOR_MODEL,
       },
@@ -298,16 +247,10 @@ function readCookie(): AgentSettingsState {
       copilot: {
         model: typeof parsed.copilot?.model === 'string' ? parsed.copilot.model : DEFAULT_COPILOT_MODEL,
       },
-      tourClaude: {
-        model: typeof parsed.tourClaude?.model === 'string' ? parsed.tourClaude.model : DEFAULT_TOUR_CLAUDE_MODEL,
-        perModel: parsed.tourClaude?.perModel ?? {},
-      },
-      tourCodex: migrateCodexSection(parsed.tourCodex, DEFAULT_TOUR_CODEX_MODEL),
-      guideClaude: {
-        model: typeof parsed.guideClaude?.model === 'string' ? parsed.guideClaude.model : DEFAULT_GUIDE_CLAUDE_MODEL,
-        perModel: parsed.guideClaude?.perModel ?? {},
-      },
-      guideCodex: migrateCodexSection(parsed.guideCodex, DEFAULT_GUIDE_CODEX_MODEL),
+      tourClaude: parseModelSection(parsed.tourClaude, DEFAULT_TOUR_CLAUDE_MODEL),
+      tourCodex: parseModelSection(parsed.tourCodex, DEFAULT_TOUR_CODEX_MODEL),
+      guideClaude: parseModelSection(parsed.guideClaude, DEFAULT_GUIDE_CLAUDE_MODEL),
+      guideCodex: parseModelSection(parsed.guideCodex, DEFAULT_GUIDE_CODEX_MODEL),
       guideCursor: {
         model: typeof parsed.guideCursor?.model === 'string' ? parsed.guideCursor.model : DEFAULT_GUIDE_CURSOR_MODEL,
       },
@@ -327,7 +270,34 @@ function readCookie(): AgentSettingsState {
   }
 }
 
-export function useAgentSettings() {
+/**
+ * The model a launch actually uses: the saved pick when the catalog offers it,
+ * else the surface default, else the catalog's own default. Resolved at read
+ * time (the saved cookie is never rewritten), and only once the catalog has
+ * settled — before that the saved pick is used as-is.
+ */
+export function effectiveModel(catalog: ModelCatalog | undefined, saved: string, surfaceDefault: string): string {
+  return catalog?.settled ? resolveModelChoice(saved, catalog.models, surfaceDefault) : saved;
+}
+
+/** The effort a launch uses: clamped to what the effective model accepts ('' = none). */
+export function effectiveEffort(catalog: ModelCatalog | undefined, model: string, effort: string): string {
+  return catalog?.settled ? resolveEffortChoice(effort, catalog.models, model) : effort;
+}
+
+/**
+ * Fast mode only for a model that offers it, and never carried over to a
+ * DIFFERENT model that replaced a stale saved pick (the fast choice was made
+ * for the old model). A saved '' is "the tool's default", not a replacement.
+ */
+export function effectiveFast(catalog: ModelCatalog | undefined, savedModel: string, model: string, fast: boolean): boolean {
+  if (!fast || !catalog?.settled) return fast;
+  if (savedModel && savedModel !== model) return false;
+  const entry = catalog.models.find((m) => m.id === model);
+  return entry ? entry.fastMode === true : fast;
+}
+
+export function useAgentSettings(catalogs?: ModelCatalogs) {
   const [state, setState] = useState<AgentSettingsState>(readCookie);
   // Serialized form of the state this instance knows is already persisted
   // and broadcast. The persist effect compares VALUES against this instead
@@ -444,20 +414,32 @@ export function useAgentSettings() {
     setState((s) => ({ ...s, copilot: { ...s.copilot, model } }));
   }, []);
 
+  /**
+   * Write a Codex setting for the model the picker SHOWS. When resolution
+   * replaced a stale saved model with a different one, the section is re-keyed
+   * to the shown model (seeded with the values shown for it), since a setting
+   * stored under the stale id would never apply (effectiveFast drops fast
+   * across a replacement). A saved '' ("the tool's default") is kept.
+   */
   const patchCodex = useCallback(
     (
       section: 'codex' | 'tourCodex' | 'guideCodex',
       patch: Partial<{ reasoning: string; fast: boolean }>,
       defaults: { reasoning: string; fast: boolean },
+      shown: { model: string; reasoning: string; fast: boolean },
     ) => {
       setState((s) => {
         const cur = s[section];
-        const prev = cur.perModel[cur.model] ?? defaults;
+        const replaced = !!cur.model && !!shown.model && shown.model !== cur.model;
+        const model = replaced ? shown.model : cur.model;
+        const prev =
+          cur.perModel[model] ?? (replaced ? { reasoning: shown.reasoning, fast: shown.fast } : defaults);
         return {
           ...s,
           [section]: {
             ...cur,
-            perModel: { ...cur.perModel, [cur.model]: { ...prev, ...patch } },
+            model,
+            perModel: { ...cur.perModel, [model]: { ...prev, ...patch } },
           },
         };
       });
@@ -465,13 +447,36 @@ export function useAgentSettings() {
     [],
   );
 
+  // Effective (launchable) values, resolved against the discovered catalogs.
+  // Pickers and launch payloads both read these, so what is shown is what runs.
+  const claudeCatalog = catalogs?.claude;
+  const codexCatalog = catalogs?.codex;
+  const claudeModel = effectiveModel(claudeCatalog, state.claude.model, DEFAULT_CLAUDE_MODEL);
+  const claudeEffort = effectiveEffort(claudeCatalog, claudeModel, state.claude.perModel[state.claude.model]?.effort ?? DEFAULT_CLAUDE_EFFORT);
+  const codexModel = effectiveModel(codexCatalog, state.codex.model, DEFAULT_CODEX_MODEL);
+  const codexReasoning = effectiveEffort(codexCatalog, codexModel, state.codex.perModel[state.codex.model]?.reasoning ?? DEFAULT_CODEX_REASONING);
+  const codexFast = effectiveFast(codexCatalog, state.codex.model, codexModel, state.codex.perModel[state.codex.model]?.fast ?? DEFAULT_CODEX_FAST);
+  const tourClaudeModel = effectiveModel(claudeCatalog, state.tourClaude.model, DEFAULT_TOUR_CLAUDE_MODEL);
+  const tourClaudeEffort = effectiveEffort(claudeCatalog, tourClaudeModel, state.tourClaude.perModel[state.tourClaude.model]?.effort ?? DEFAULT_TOUR_CLAUDE_EFFORT);
+  const tourCodexModel = effectiveModel(codexCatalog, state.tourCodex.model, DEFAULT_TOUR_CODEX_MODEL);
+  const tourCodexReasoning = effectiveEffort(codexCatalog, tourCodexModel, state.tourCodex.perModel[state.tourCodex.model]?.reasoning ?? DEFAULT_TOUR_CODEX_REASONING);
+  const tourCodexFast = effectiveFast(codexCatalog, state.tourCodex.model, tourCodexModel, state.tourCodex.perModel[state.tourCodex.model]?.fast ?? DEFAULT_TOUR_CODEX_FAST);
+  const guideClaudeModel = effectiveModel(claudeCatalog, state.guideClaude.model, DEFAULT_GUIDE_CLAUDE_MODEL);
+  const guideClaudeEffort = effectiveEffort(claudeCatalog, guideClaudeModel, state.guideClaude.perModel[state.guideClaude.model]?.effort ?? DEFAULT_GUIDE_CLAUDE_EFFORT);
+  const guideCodexModel = effectiveModel(codexCatalog, state.guideCodex.model, DEFAULT_GUIDE_CODEX_MODEL);
+  const guideCodexReasoning = effectiveEffort(codexCatalog, guideCodexModel, state.guideCodex.perModel[state.guideCodex.model]?.reasoning ?? DEFAULT_GUIDE_CODEX_REASONING);
+  // Guide offers no fast toggle; a re-key carries whatever is stored.
+  const guideCodexFast = state.guideCodex.perModel[state.guideCodex.model]?.fast ?? DEFAULT_CODEX_FAST;
+
   const setCodexReasoning = useCallback(
-    (reasoning: string) => patchCodex('codex', { reasoning }, { reasoning: DEFAULT_CODEX_REASONING, fast: DEFAULT_CODEX_FAST }),
-    [patchCodex],
+    (reasoning: string) =>
+      patchCodex('codex', { reasoning }, { reasoning: DEFAULT_CODEX_REASONING, fast: DEFAULT_CODEX_FAST }, { model: codexModel, reasoning: codexReasoning, fast: codexFast }),
+    [patchCodex, codexModel, codexReasoning, codexFast],
   );
   const setCodexFast = useCallback(
-    (fast: boolean) => patchCodex('codex', { fast }, { reasoning: DEFAULT_CODEX_REASONING, fast: DEFAULT_CODEX_FAST }),
-    [patchCodex],
+    (fast: boolean) =>
+      patchCodex('codex', { fast }, { reasoning: DEFAULT_CODEX_REASONING, fast: DEFAULT_CODEX_FAST }, { model: codexModel, reasoning: codexReasoning, fast: codexFast }),
+    [patchCodex, codexModel, codexReasoning, codexFast],
   );
 
   const setTourClaudeModel = useCallback((model: string) => {
@@ -488,12 +493,14 @@ export function useAgentSettings() {
   }, []);
 
   const setTourCodexReasoning = useCallback(
-    (reasoning: string) => patchCodex('tourCodex', { reasoning }, { reasoning: DEFAULT_TOUR_CODEX_REASONING, fast: DEFAULT_TOUR_CODEX_FAST }),
-    [patchCodex],
+    (reasoning: string) =>
+      patchCodex('tourCodex', { reasoning }, { reasoning: DEFAULT_TOUR_CODEX_REASONING, fast: DEFAULT_TOUR_CODEX_FAST }, { model: tourCodexModel, reasoning: tourCodexReasoning, fast: tourCodexFast }),
+    [patchCodex, tourCodexModel, tourCodexReasoning, tourCodexFast],
   );
   const setTourCodexFast = useCallback(
-    (fast: boolean) => patchCodex('tourCodex', { fast }, { reasoning: DEFAULT_TOUR_CODEX_REASONING, fast: DEFAULT_TOUR_CODEX_FAST }),
-    [patchCodex],
+    (fast: boolean) =>
+      patchCodex('tourCodex', { fast }, { reasoning: DEFAULT_TOUR_CODEX_REASONING, fast: DEFAULT_TOUR_CODEX_FAST }, { model: tourCodexModel, reasoning: tourCodexReasoning, fast: tourCodexFast }),
+    [patchCodex, tourCodexModel, tourCodexReasoning, tourCodexFast],
   );
 
   const setGuideClaudeModel = useCallback((model: string) => {
@@ -510,8 +517,9 @@ export function useAgentSettings() {
   }, []);
 
   const setGuideCodexReasoning = useCallback(
-    (reasoning: string) => patchCodex('guideCodex', { reasoning }, { reasoning: DEFAULT_GUIDE_CODEX_REASONING, fast: DEFAULT_CODEX_FAST }),
-    [patchCodex],
+    (reasoning: string) =>
+      patchCodex('guideCodex', { reasoning }, { reasoning: DEFAULT_GUIDE_CODEX_REASONING, fast: DEFAULT_CODEX_FAST }, { model: guideCodexModel, reasoning: guideCodexReasoning, fast: guideCodexFast }),
+    [patchCodex, guideCodexModel, guideCodexReasoning, guideCodexFast],
   );
 
   const setGuideCursorModel = useCallback((model: string) => {
@@ -534,38 +542,15 @@ export function useAgentSettings() {
     setState((s) => ({ ...s, guideCopilot: { ...s.guideCopilot, model } }));
   }, []);
 
-  const claudeEffort = state.claude.perModel[state.claude.model]?.effort ?? DEFAULT_CLAUDE_EFFORT;
-  // Codex reasoning is clamped through the model's supported-effort set: a
-  // saved (or surface-default) effort the selected model doesn't support
-  // snaps to that model's catalog default. Every consumer — the pickers AND
-  // the launch payloads — reads these derived values, so an unsupported
-  // effort can never reach `-c model_reasoning_effort=`.
-  const codexReasoning = clampCodexReasoning(
-    state.codex.model,
-    state.codex.perModel[state.codex.model]?.reasoning ?? DEFAULT_CODEX_REASONING,
-  );
-  const codexFast = state.codex.perModel[state.codex.model]?.fast ?? DEFAULT_CODEX_FAST;
-  const tourClaudeEffort = state.tourClaude.perModel[state.tourClaude.model]?.effort ?? DEFAULT_TOUR_CLAUDE_EFFORT;
-  const tourCodexReasoning = clampCodexReasoning(
-    state.tourCodex.model,
-    state.tourCodex.perModel[state.tourCodex.model]?.reasoning ?? DEFAULT_TOUR_CODEX_REASONING,
-  );
-  const tourCodexFast = state.tourCodex.perModel[state.tourCodex.model]?.fast ?? DEFAULT_TOUR_CODEX_FAST;
-  const guideClaudeEffort = state.guideClaude.perModel[state.guideClaude.model]?.effort ?? DEFAULT_GUIDE_CLAUDE_EFFORT;
-  const guideCodexReasoning = clampCodexReasoning(
-    state.guideCodex.model,
-    state.guideCodex.perModel[state.guideCodex.model]?.reasoning ?? DEFAULT_GUIDE_CODEX_REASONING,
-  );
-
   return {
     selectedMode: state.selectedMode,
     reviewEngine: state.reviewEngine,
     reviewProfileId: state.reviewProfileByEngine[state.reviewEngine] ?? BUILTIN_DEFAULT_PROFILE,
     tourEngine: state.tourEngine,
     guideEngine: state.guideEngine,
-    claudeModel: state.claude.model,
+    claudeModel,
     claudeEffort,
-    codexModel: state.codex.model,
+    codexModel,
     codexReasoning,
     codexFast,
     cursorModel: state.cursor.model,
@@ -573,14 +558,14 @@ export function useAgentSettings() {
     piModel: state.pi.model,
     piThinking: state.pi.thinking,
     copilotModel: state.copilot.model,
-    tourClaudeModel: state.tourClaude.model,
+    tourClaudeModel,
     tourClaudeEffort,
-    tourCodexModel: state.tourCodex.model,
+    tourCodexModel,
     tourCodexReasoning,
     tourCodexFast,
-    guideClaudeModel: state.guideClaude.model,
+    guideClaudeModel,
     guideClaudeEffort,
-    guideCodexModel: state.guideCodex.model,
+    guideCodexModel,
     guideCodexReasoning,
     guideCursorModel: state.guideCursor.model,
     guideOpencodeModel: state.guideOpencode.model,

package/hooks/useAnnotationHighlighter.ts

@@ -212,6 +212,53 @@ const isAnnotationExcludedTextNode = (node: Node): boolean =>
  */
 const compactText = (value: string): string => value.replace(/\s+/g, '');
 
+/**
+ * A quote with nothing but whitespace in it is not an annotation (#881).
+ *
+ * A double-click at a block boundary — just past the end of a heading, a
+ * paragraph, a list item, a fence — leaves a non-collapsed selection whose
+ * whole string is the break BETWEEN two blocks ("\n"). Acting on it produces
+ * an invisible highlight and an `originalText: "\n"` annotation that no
+ * reload can re-anchor, and which is still counted and exported.
+ *
+ * `compactText` rather than `trim`: it also removes the non-breaking spaces
+ * and other Unicode whitespace a rendered document is full of.
+ */
+const isBlankQuote = (value: string | null | undefined): boolean =>
+  compactText(value ?? '') === '';
+
+/**
+ * Whether web-highlighter can serialize a range boundary (#881).
+ *
+ * A non-text boundary is resolved by the library as `childNodes[offset]` and
+ * that node is then serialized. The DOM lets `offset` equal `childNodes.length`
+ * (one past the last child) and browsers really do report that for a
+ * double-click at the end of the last block, which leaves the library holding
+ * `undefined` and throwing `Cannot read properties of undefined (reading
+ * 'parentNode')` out of its own pointer-end listener — an uncaught error, with
+ * no annotation created either way.
+ */
+const boundaryResolves = (node: Node, offset: number): boolean => {
+  // Text, CDATASection and Comment boundaries are offsets INTO the node.
+  if (node.nodeType === 3 || node.nodeType === 4 || node.nodeType === 8) return true;
+  return offset >= 0 && offset < node.childNodes.length && node.childNodes[offset] != null;
+};
+
+const isSerializableRange = (range: Range): boolean =>
+  boundaryResolves(range.startContainer, range.startOffset)
+  && boundaryResolves(range.endContainer, range.endOffset);
+
+/**
+ * One line per page load: a highlighter failure is degraded UX (the selection
+ * is ignored), not something to flood the console — or the user — over.
+ */
+let warnedHighlighterFailure = false;
+const warnHighlighterFailure = (context: string, error: unknown): void => {
+  if (warnedHighlighterFailure) return;
+  warnedHighlighterFailure = true;
+  console.warn(`[plannotator] highlighter ${context} failed; the selection was ignored`, error);
+};
+
 /**
  * The text a set of painted highlight wrappers shows the reader.
  *
@@ -878,6 +925,11 @@ export function useAnnotationHighlighter({
     quickLabelTip?: string,
     mentions?: readonly string[],
   ) => {
+    // #881: the last line before an annotation exists. A quote of pure
+    // whitespace cannot be re-anchored on the next load, so it would come back
+    // as an invisible row that is still counted and still exported.
+    if (isBlankQuote(source?.text)) return;
+
     const doms = highlighter.getDoms(source.id);
     let blockId = '';
     let startOffset = 0;
@@ -1053,6 +1105,14 @@ export function useAnnotationHighlighter({
       // verdict, so it is neither attempted nor unanchored here (the same
       // rule the raw-HTML pinpoints follow on their surface).
       if (ann.diagramAnchor) return;
+      // #881: a row whose quote is only whitespace has nothing to anchor to.
+      // Older drafts carry such rows (a double-click at a block boundary used
+      // to create one), and the stored positions still resolve, so restoring
+      // it paints an invisible mark on a spot the reviewer never chose. Skip
+      // it outright — neither attempted nor unanchored, the same treatment a
+      // diagram row gets, so a legacy draft does not raise an "Unanchored"
+      // chip and a toast on every load.
+      if (isBlankQuote(ann.originalText)) return;
       attempted.push(ann.id);
 
       // Skip if already highlighted
@@ -1292,6 +1352,21 @@ export function useAnnotationHighlighter({
             source.text,
             doms.map((dom: HTMLElement) => dom.textContent ?? '').join(''),
           );
+          // #881, belt to the capture-phase guard's braces: every producer of
+          // a selection highlight lands here (the library's own pointer-end
+          // listener, the touch selectionchange bridge, vim and pinpoint
+          // ranges), and the quote repair above can itself leave nothing but
+          // whitespace. A blank quote opens no toolbar, no composer and
+          // creates no annotation; the painted-but-invisible highlight goes
+          // with it, and the pending selection already on screen is untouched.
+          if (isBlankQuote(source.text)) {
+            try { highlighter.remove(source.id); } catch (error) {
+              warnHighlighterFailure('cleanup of a blank selection', error);
+            }
+            pendingRangeRunsRef.current = null;
+            window.getSelection()?.removeAllRanges();
+            return;
+          }
           // Clean up previous pending
           if (pendingSourceRef.current) {
             highlighter.remove(pendingSourceRef.current.id);
@@ -1352,6 +1427,24 @@ export function useAnnotationHighlighter({
         return;
       }
       const range = selection.getRangeAt(0).cloneRange();
+      // #881: fail closed on a selection there is nothing to annotate in, and
+      // on one the library cannot serialize. Collapsing it HERE — on the
+      // capture phase, before the library's own pointer-end listener reads the
+      // live selection — is what makes its handler a no-op: it bails on a
+      // collapsed selection rather than painting an empty highlight or
+      // throwing out of an event listener we do not own.
+      //
+      // Ahead of the containment check on purpose: the library's handler does
+      // not check containment either. A double-click past the end of the LAST
+      // block leaves a selection whose common ancestor is the scroll container
+      // AROUND the document and whose end boundary is an empty <div> — the
+      // exact shape that throws — so a containment bail here would hand that
+      // selection straight to the serializer.
+      if (isBlankQuote(selection.toString()) || !isSerializableRange(range)) {
+        pendingRangeRunsRef.current = null;
+        selection.removeAllRanges();
+        return;
+      }
       if (!container.contains(range.commonAncestorContainer)) {
         pendingRangeRunsRef.current = null;
         return;
@@ -1466,9 +1559,17 @@ export function useAnnotationHighlighter({
             if (!sel || sel.isCollapsed || sel.rangeCount === 0) return;
             if (!containerRef.current?.contains(sel.anchorNode)) return;
             const range = sel.getRangeAt(0).cloneRange();
+            // Same fail-closed rule as the pointer-end guard (#881): touch
+            // selections settle on block boundaries just as often.
+            if (isBlankQuote(sel.toString()) || !isSerializableRange(range)) return;
             snapRangeStartPastExcluded(range);
             pendingRangeRunsRef.current = rangeTextPieces(range);
-            highlighter.fromRange(range);
+            try {
+              highlighter.fromRange(range);
+            } catch (error) {
+              pendingRangeRunsRef.current = null;
+              warnHighlighterFailure('painting a touch selection', error);
+            }
           }, 400);
         }
       : null;
@@ -1495,6 +1596,10 @@ export function useAnnotationHighlighter({
     const container = containerRef.current;
     if (!highlighter || !container || range.collapsed) return;
     if (!container.contains(range.commonAncestorContainer)) return;
+    // A caller-built range (vim, pinpoint) can name a boundary the library
+    // cannot serialize just as a pointer selection can (#881); refuse it
+    // rather than let the serializer throw through this call.
+    if (!isSerializableRange(range)) return;
 
     // Pinpoint clicks and vim visual selections anchor on the first
     // annotatable text node of a block, which for a titled GitHub alert is the
@@ -1511,6 +1616,9 @@ export function useAnnotationHighlighter({
 
     try {
       highlighter.fromRange(painted);
+    } catch (error) {
+      pendingRangeRunsRef.current = null;
+      warnHighlighterFailure('painting a range', error);
     } finally {
       pendingModeOverrideRef.current = null;
       selection?.removeAllRanges();