@plannotator/ui 0.47.0 → 0.50.0

package/components/html-viewer/bridge-script.asset.js

@@ -96,17 +96,89 @@
   });
 
   // --- Resize ---
-  var lastHeight = 0;
+  // The last child of el whose bottom margin could collapse through el's
+  // bottom edge: out-of-flow children (display:none, absolute/fixed, floats)
+  // never do, which also skips the bridge's own fixed overlay elements and a
+  // trailing script element.
+  function lastInFlowChild(el) {
+    for (var child = el.lastElementChild; child; child = child.previousElementSibling) {
+      var cs = window.getComputedStyle(child);
+      if (cs.display === 'none' || cs.display === 'contents') continue;
+      if (cs.position === 'absolute' || cs.position === 'fixed') continue;
+      if (cs.float && cs.float !== 'none') continue;
+      return child;
+    }
+    return null;
+  }
+
+  // Height the auto-sized frame needs to show the whole document.
+  // Not body.scrollHeight alone: when body has no top padding or border, a
+  // first child's top margin collapses THROUGH body and moves body's box down
+  // without making it taller (the same holds at the bottom), so the page was
+  // cut short by those margins. Not documentElement.scrollHeight either: it
+  // never reports less than the frame's own viewport, so the frame could grow
+  // but never shrink back, and an html{height:100%} page would pin it at
+  // whatever height it had. Instead body's box is placed in document
+  // coordinates (its top already includes a collapsed top margin), and the
+  // bottom margins that can collapse through body's bottom edge are added by
+  // walking the last in-flow child chain. Nothing here reads the frame's own
+  // height, so the measure cannot feed back on itself.
+  function measureContentHeight() {
+    var body = document.body;
+    var scrollY = window.pageYOffset || 0;
+    var bodyRect = body.getBoundingClientRect();
+    var bottom = Math.max(bodyRect.bottom, bodyRect.top + (body.clientTop || 0) + body.scrollHeight) + scrollY;
+    var el = body;
+    for (var depth = 0; el && depth < 64; depth++) {
+      var cs = window.getComputedStyle(el);
+      var marginBottom = parseFloat(cs.marginBottom) || 0;
+      if (marginBottom > 0) bottom = Math.max(bottom, el.getBoundingClientRect().bottom + scrollY + marginBottom);
+      // A child's bottom margin only collapses through a plain block parent
+      // with no bottom padding or border that does not clip (flex/grid
+      // containers, flow-root and scroll containers keep it inside).
+      if (cs.display !== 'block' && cs.display !== 'list-item') break;
+      if (cs.overflowY && cs.overflowY !== 'visible') break;
+      if ((parseFloat(cs.paddingBottom) || 0) > 0 || (parseFloat(cs.borderBottomWidth) || 0) > 0) break;
+      el = lastInFlowChild(el);
+    }
+    var rootStyle = window.getComputedStyle(document.documentElement);
+    bottom += (parseFloat(rootStyle.paddingBottom) || 0) + (parseFloat(rootStyle.borderBottomWidth) || 0);
+    return Math.max(0, Math.ceil(bottom));
+  }
+
+  // Feedback guard. Content sized by the frame itself (html,body{height:100%},
+  // min-height:100vh, a 100vh section) plus anything around it (a collapsed
+  // margin, body's own margin) always measures taller than the frame, so every
+  // grow would ask for another: the frame would grow forever. The first
+  // measure after the parent applied a GROW we asked for decides: if the page
+  // still overflows by at least as much as it did before the grow, it grew
+  // with the frame, and the frame stays where it is. Later content changes
+  // post as usual (and re-run the check on their own grow). Pure, so the
+  // test can drive it: returns the height to post, or null for none.
+  function nextResizeHeight(state, h, viewport) {
+    var applied = state.awaiting && Math.abs(viewport - state.last) <= 1;
+    if (applied) state.awaiting = false;
+    if (h === state.last) return null;
+    if (applied && state.excess > 0 && h > viewport && h - viewport >= state.excess - 1) {
+      state.last = h; // held: report nothing until the content measures differently
+      return null;
+    }
+    state.excess = h - viewport;
+    state.awaiting = true;
+    state.last = h;
+    return h;
+  }
+
+  var resizeState = { last: 0, excess: 0, awaiting: false };
   function postResize() {
     if (LIVE) return; // live surfaces render full-viewport; the parent ignores height
     if (!document.body) return;
-    var h = document.body.scrollHeight;
-    if (h !== lastHeight) {
-      lastHeight = h;
-      postToParent({ type: PREFIX + 'resize', height: h });
-    }
+    var h = nextResizeHeight(resizeState, measureContentHeight(), window.innerHeight);
+    if (h !== null) postToParent({ type: PREFIX + 'resize', height: h });
   }
   window.addEventListener('load', postResize);
+  // The frame resizing is what tells the guard its last grow was applied.
+  window.addEventListener('resize', postResize, { passive: true });
 
   // --- Selection ---
   var pendingSelection = null;
@@ -4898,11 +4970,16 @@
 
   function onReady() {
     if (typeof ResizeObserver !== 'undefined' && document.body) {
-      new ResizeObserver(function() {
+      var resizeObserver = new ResizeObserver(function() {
         postResize();
         scheduleVimUiUpdate();
         schedulePinpointReconcile();
-      }).observe(document.body);
+      });
+      resizeObserver.observe(document.body);
+      // A collapsed margin changing moves body without resizing it; the root
+      // box does resize then. (An html{height:100%} root resizes with the
+      // frame instead, which re-measures the same height and posts nothing.)
+      resizeObserver.observe(document.documentElement);
     }
     watchPageMutations();
     // Armed is the default on both surfaces, and live sessions default to

package/components/html-viewer/bridge-script.ts

@@ -332,17 +332,89 @@ export const BRIDGE_SCRIPT = `(function() {
   });
 
   // --- Resize ---
-  var lastHeight = 0;
+  // The last child of el whose bottom margin could collapse through el's
+  // bottom edge: out-of-flow children (display:none, absolute/fixed, floats)
+  // never do, which also skips the bridge's own fixed overlay elements and a
+  // trailing script element.
+  function lastInFlowChild(el) {
+    for (var child = el.lastElementChild; child; child = child.previousElementSibling) {
+      var cs = window.getComputedStyle(child);
+      if (cs.display === 'none' || cs.display === 'contents') continue;
+      if (cs.position === 'absolute' || cs.position === 'fixed') continue;
+      if (cs.float && cs.float !== 'none') continue;
+      return child;
+    }
+    return null;
+  }
+
+  // Height the auto-sized frame needs to show the whole document.
+  // Not body.scrollHeight alone: when body has no top padding or border, a
+  // first child's top margin collapses THROUGH body and moves body's box down
+  // without making it taller (the same holds at the bottom), so the page was
+  // cut short by those margins. Not documentElement.scrollHeight either: it
+  // never reports less than the frame's own viewport, so the frame could grow
+  // but never shrink back, and an html{height:100%} page would pin it at
+  // whatever height it had. Instead body's box is placed in document
+  // coordinates (its top already includes a collapsed top margin), and the
+  // bottom margins that can collapse through body's bottom edge are added by
+  // walking the last in-flow child chain. Nothing here reads the frame's own
+  // height, so the measure cannot feed back on itself.
+  function measureContentHeight() {
+    var body = document.body;
+    var scrollY = window.pageYOffset || 0;
+    var bodyRect = body.getBoundingClientRect();
+    var bottom = Math.max(bodyRect.bottom, bodyRect.top + (body.clientTop || 0) + body.scrollHeight) + scrollY;
+    var el = body;
+    for (var depth = 0; el && depth < 64; depth++) {
+      var cs = window.getComputedStyle(el);
+      var marginBottom = parseFloat(cs.marginBottom) || 0;
+      if (marginBottom > 0) bottom = Math.max(bottom, el.getBoundingClientRect().bottom + scrollY + marginBottom);
+      // A child's bottom margin only collapses through a plain block parent
+      // with no bottom padding or border that does not clip (flex/grid
+      // containers, flow-root and scroll containers keep it inside).
+      if (cs.display !== 'block' && cs.display !== 'list-item') break;
+      if (cs.overflowY && cs.overflowY !== 'visible') break;
+      if ((parseFloat(cs.paddingBottom) || 0) > 0 || (parseFloat(cs.borderBottomWidth) || 0) > 0) break;
+      el = lastInFlowChild(el);
+    }
+    var rootStyle = window.getComputedStyle(document.documentElement);
+    bottom += (parseFloat(rootStyle.paddingBottom) || 0) + (parseFloat(rootStyle.borderBottomWidth) || 0);
+    return Math.max(0, Math.ceil(bottom));
+  }
+
+  // Feedback guard. Content sized by the frame itself (html,body{height:100%},
+  // min-height:100vh, a 100vh section) plus anything around it (a collapsed
+  // margin, body's own margin) always measures taller than the frame, so every
+  // grow would ask for another: the frame would grow forever. The first
+  // measure after the parent applied a GROW we asked for decides: if the page
+  // still overflows by at least as much as it did before the grow, it grew
+  // with the frame, and the frame stays where it is. Later content changes
+  // post as usual (and re-run the check on their own grow). Pure, so the
+  // test can drive it: returns the height to post, or null for none.
+  function nextResizeHeight(state, h, viewport) {
+    var applied = state.awaiting && Math.abs(viewport - state.last) <= 1;
+    if (applied) state.awaiting = false;
+    if (h === state.last) return null;
+    if (applied && state.excess > 0 && h > viewport && h - viewport >= state.excess - 1) {
+      state.last = h; // held: report nothing until the content measures differently
+      return null;
+    }
+    state.excess = h - viewport;
+    state.awaiting = true;
+    state.last = h;
+    return h;
+  }
+
+  var resizeState = { last: 0, excess: 0, awaiting: false };
   function postResize() {
     if (LIVE) return; // live surfaces render full-viewport; the parent ignores height
     if (!document.body) return;
-    var h = document.body.scrollHeight;
-    if (h !== lastHeight) {
-      lastHeight = h;
-      postToParent({ type: PREFIX + 'resize', height: h });
-    }
+    var h = nextResizeHeight(resizeState, measureContentHeight(), window.innerHeight);
+    if (h !== null) postToParent({ type: PREFIX + 'resize', height: h });
   }
   window.addEventListener('load', postResize);
+  // The frame resizing is what tells the guard its last grow was applied.
+  window.addEventListener('resize', postResize, { passive: true });
 
   // --- Selection ---
   var pendingSelection = null;
@@ -5134,11 +5206,16 @@ export const BRIDGE_SCRIPT = `(function() {
 
   function onReady() {
     if (typeof ResizeObserver !== 'undefined' && document.body) {
-      new ResizeObserver(function() {
+      var resizeObserver = new ResizeObserver(function() {
         postResize();
         scheduleVimUiUpdate();
         schedulePinpointReconcile();
-      }).observe(document.body);
+      });
+      resizeObserver.observe(document.body);
+      // A collapsed margin changing moves body without resizing it; the root
+      // box does resize then. (An html{height:100%} root resizes with the
+      // frame instead, which re-measures the same height and posts nothing.)
+      resizeObserver.observe(document.documentElement);
     }
     watchPageMutations();
     // Armed is the default on both surfaces, and live sessions default to

package/config/settings.ts

@@ -599,6 +599,23 @@ export const SETTINGS = {
     },
     toServer: (value: boolean) => ({ reviewAnalysis: { callFlow: value } }),
   },
+  /**
+   * Opt-in background auto-update of the compiled CLI (#1634). The server
+   * always sends the config-file value (default false), so the cookie is only
+   * a mirror and can never turn this on by itself.
+   */
+  autoUpdate: {
+    defaultValue: false as boolean,
+    fromCookie: () => {
+      const v = storage.getItem('plannotator-auto-update');
+      return v === 'true' ? true : v === 'false' ? false : undefined;
+    },
+    toCookie: (v: boolean) => storage.setItem('plannotator-auto-update', String(v)),
+    serverKey: 'autoUpdate',
+    fromServer: (sc: Record<string, unknown>) =>
+      typeof sc.autoUpdate === 'boolean' ? sc.autoUpdate : undefined,
+    toServer: (v: boolean) => ({ autoUpdate: v }),
+  },
   conventionalComments: {
     defaultValue: false as boolean,
     fromCookie: () => {

package/configure.ts

@@ -12,6 +12,7 @@ import { setWebMcpPolicy, type WebMcpPolicy } from './webmcp/policy';
 import { setMathRendererLoader, type MathRenderer, type MathRendererLoader } from './utils/math';
 import { setIdentityGenerator, type IdentityGenerator } from './utils/generateIdentity';
 import { setAlertIconRenderer, type AlertIconRenderer } from './components/blocks/AlertBlock';
+import { setFenceThemeResolver, type FenceThemeResolver } from './utils/syntaxTheme';
 import { configStore } from './config';
 import type { ServerSyncFn } from './config/configStore';
 import type { ExternalAnnotationEvent, VaultNode } from './types';
@@ -40,6 +41,7 @@ export type {
   MathRendererLoader,
   IdentityGenerator,
   AlertIconRenderer,
+  FenceThemeResolver,
 };
 
 type ExternalAnnotationBase = { id: string; source?: string };
@@ -93,6 +95,15 @@ export interface PlannotatorUIConfig {
    * today; the package bundles no icon set. A host with one registers a renderer.
    */
   alertIconRenderer?: AlertIconRenderer;
+  /**
+   * Pick the Shiki theme code fences render in, per (palette id, resolved
+   * mode). Return `undefined` to keep the default resolution (the palette's
+   * `SHIKI_THEME_MAP` entry, else `pierre-dark` / `pierre-light`). Applies to
+   * every fence-style surface (Viewer fences, the code-file hover preview, the
+   * plan diff view, code review suggestion snippets); the code-review diff
+   * pane keeps its own pair. An unknown theme name renders plain text.
+   */
+  fenceTheme?: FenceThemeResolver;
   /** Re-hydrate settings from the installed (SYNCHRONOUS) storageBackend after install. */
   loadSettingsFromBackend?: boolean;
 }
@@ -114,6 +125,7 @@ export function configurePlannotatorUI(config: PlannotatorUIConfig): void {
   if (config.mathRendererLoader) setMathRendererLoader(config.mathRendererLoader);
   if (config.identityGenerator) setIdentityGenerator(config.identityGenerator);
   if (config.alertIconRenderer) setAlertIconRenderer(config.alertIconRenderer);
+  if (config.fenceTheme) setFenceThemeResolver(config.fenceTheme);
   // Re-hydrate AFTER storageBackend is installed (load-bearing order — gated last).
   if (config.loadSettingsFromBackend) configStore.loadFromBackend();
 }

package/hooks/useAIChat.ts

@@ -42,6 +42,18 @@ export interface AskAIParams {
   /** Context block prepended to the message (e.g. the "changes under review"
    *  description). Rides with each question so it reflects the live view. */
   contextPreamble?: string;
+  /** "Ask this session" only: what to do when the host session is busy
+   *  ("wait" = ask when it finishes, "interrupt" = stop its turn and ask now). */
+  busyPolicy?: 'wait' | 'interrupt';
+}
+
+/** Overrides for re-asking a question that ended in a busy/gone/blocked answer. */
+export interface AIRetryOptions {
+  busyPolicy?: 'wait' | 'interrupt';
+  /** Ask a different provider instead (a fresh session is created for it). */
+  providerId?: string;
+  /** Replace parts of the original question (e.g. a provider-specific preamble). */
+  params?: Partial<AskAIParams>;
 }
 
 interface UseAIChatOptions {
@@ -228,7 +240,7 @@ export function useAIChat({
     setThread(prev => ({ ...prev, sessionId }));
   }, []);
 
-  const createSession = useCallback(async (signal: AbortSignal, epoch: number): Promise<string> => {
+  const createSession = useCallback(async (signal: AbortSignal, epoch: number, providerOverride?: string): Promise<string> => {
     if (!context) {
       throw new Error('AI context is unavailable');
     }
@@ -236,7 +248,10 @@ export function useAIChat({
     const requestId = ++createRequestRef.current;
     setIsCreatingSession(true);
     try {
-      const res = await aiTransport.session({
+      const res = await aiTransport.session(providerOverride ? {
+        context,
+        providerId: providerOverride,
+      } : {
         context,
         ...(providerId && { providerId }),
         ...(model && { model }),
@@ -274,7 +289,11 @@ export function useAIChat({
     return safeAbort(sessionId);
   }, []);
 
-  const ask = useCallback(async (params: AskAIParams) => {
+  // The params each question was asked with, so a busy/gone answer can be
+  // re-asked ("Ask when it finishes", "Ask a separate AI instead").
+  const paramsByQuestionRef = useRef(new Map<string, AskAIParams>());
+
+  const ask = useCallback(async (params: AskAIParams, askOptions?: { providerId?: string }) => {
     if (abortRef.current) {
       abortRef.current.abort();
       // Supersede: stop the server-side turn (not just the browser fetch).
@@ -295,6 +314,7 @@ export function useAIChat({
     setError(null);
 
     const questionId = generateId('ai-question');
+    paramsByQuestionRef.current.set(questionId, params);
     const question: AIQuestion = {
       id: questionId,
       prompt: params.prompt,
@@ -319,7 +339,9 @@ export function useAIChat({
 
     try {
       let sid = sessionIdRef.current;
-      if (!sid) {
+      if (askOptions?.providerId) {
+        sid = await createSession(controller.signal, epoch, askOptions.providerId);
+      } else if (!sid) {
         sid = await createSession(controller.signal, epoch);
       }
 
@@ -332,6 +354,7 @@ export function useAIChat({
         sessionId: sid,
         prompt: fullPrompt,
         ...(params.contextUpdate && { contextUpdate: params.contextUpdate }),
+        ...(params.busyPolicy && { busyPolicy: params.busyPolicy }),
       }, controller.signal);
 
       if (!res.ok || !res.body) {
@@ -363,7 +386,19 @@ export function useAIChat({
               updateMessages(prev =>
                 prev.map(m =>
                   m.question.id === questionId
-                    ? { ...m, response: { ...m.response, text: m.response.text + msg.delta } }
+                    ? { ...m, response: m.response.status
+                        ? { ...m.response, text: m.response.text + msg.delta, status: undefined }
+                        : { ...m.response, text: m.response.text + msg.delta } }
+                    : m
+                )
+              );
+            } else if (msg.type === 'status') {
+              // "Ask this session": waiting on / interrupting a busy session.
+              const status = msg.status === 'waiting' || msg.status === 'interrupting' ? msg.status : undefined;
+              updateMessages(prev =>
+                prev.map(m =>
+                  m.question.id === questionId
+                    ? { ...m, response: { ...m.response, status } }
                     : m
                 )
               );
@@ -389,7 +424,16 @@ export function useAIChat({
               updateMessages(prev =>
                 prev.map(m =>
                   m.question.id === questionId
-                    ? { ...m, response: { ...m.response, error: msg.error, isStreaming: false } }
+                    ? {
+                        ...m,
+                        response: {
+                          ...m.response,
+                          error: msg.error,
+                          ...(typeof msg.code === 'string' && { errorCode: msg.code }),
+                          ...(m.response.status && { status: undefined }),
+                          isStreaming: false,
+                        },
+                      }
                     : m
                 )
               );
@@ -418,8 +462,8 @@ export function useAIChat({
 
       updateMessages(prev =>
         prev.map(m =>
-          m.question.id === questionId && m.response.isStreaming
-            ? { ...m, response: { ...m.response, isStreaming: false } }
+          m.question.id === questionId && (m.response.isStreaming || m.response.status)
+            ? { ...m, response: { ...m.response, isStreaming: false, ...(m.response.status && { status: undefined }) } }
             : m
         )
       );
@@ -428,7 +472,7 @@ export function useAIChat({
         updateMessages(prev =>
           prev.map(m =>
             m.question.id === questionId
-              ? { ...m, response: { ...m.response, isStreaming: false } }
+              ? { ...m, response: { ...m.response, isStreaming: false, ...(m.response.status && { status: undefined }) } }
               : m
           )
         );
@@ -452,6 +496,25 @@ export function useAIChat({
     }
   }, [buildPrompt, createSession, updateMessages, updatePermissions, postServerAbort]);
 
+  /**
+   * Re-ask an earlier question in place of its answer: the busy-session choice
+   * ("Ask when it finishes" / "Interrupt and ask now") and the fallback to a
+   * separate AI after "Ask this session" reports the session gone or blocked.
+   */
+  const retry = useCallback((questionId: string, options: AIRetryOptions = {}) => {
+    const original = paramsByQuestionRef.current.get(questionId);
+    if (!original) return;
+    paramsByQuestionRef.current.delete(questionId);
+    updateMessages(prev => prev.filter(m => m.question.id !== questionId));
+    const { busyPolicy: _previousPolicy, ...base } = original;
+    const params: AskAIParams = {
+      ...base,
+      ...options.params,
+      ...(options.busyPolicy && { busyPolicy: options.busyPolicy }),
+    };
+    return ask(params, options.providerId ? { providerId: options.providerId } : undefined);
+  }, [ask, updateMessages]);
+
   const abort = useCallback(() => {
     if (abortRef.current) {
       abortRef.current.abort();
@@ -502,6 +565,7 @@ export function useAIChat({
       abortRef.current = null;
       pendingAbortRef.current = postServerAbort();
     }
+    paramsByQuestionRef.current.clear();
     setThread(createThread(threadTitle));
     setIsCreatingSession(false);
     setIsStreaming(false);
@@ -527,6 +591,7 @@ export function useAIChat({
     permissionRequests: thread.permissionRequests,
     respondToPermission,
     ask,
+    retry,
     abort,
     resetSession,
     resetThread,

package/hooks/useAIProviderConfig.ts

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import type { Origin } from '@plannotator/core/agents';
 import {
   getAIProviderSettings,
@@ -56,16 +56,26 @@ export function useAIProviderConfig({
     };
   });
 
+  // A provider picked for this page only (the "Ask a separate AI instead"
+  // fallback from "Ask this session"): never written to the cookie, but kept
+  // across capability refreshes so the resolver does not flip back.
+  const sessionPickRef = useRef<string | null>(null);
+
   // Auto-resolve provider/model once capabilities are known.
   useEffect(() => {
     if (!available || providers.length === 0) return;
     const saved = getAIProviderSettings();
-    const selection = resolveAIProviderSelection({
-      providers,
-      origin,
-      settings: saved,
-      serverDefaultProvider: defaultProvider,
-    });
+    const sessionPick = sessionPickRef.current
+      ? providers.find(p => p.id === sessionPickRef.current) ?? null
+      : null;
+    const selection = sessionPick
+      ? { providerId: sessionPick.id, model: resolveAIModelForProvider(sessionPick, saved.preferredModels) }
+      : resolveAIProviderSelection({
+          providers,
+          origin,
+          settings: saved,
+          serverDefaultProvider: defaultProvider,
+        });
 
     setAiConfig(prev => {
       if (prev.providerId === selection.providerId && prev.model === selection.model) return prev;
@@ -81,7 +91,13 @@ export function useAIProviderConfig({
   // Update the selection (provider/model/effort). Does NOT reset the session —
   // the caller composes that (see the cycle note above).
   const applyConfigChange = useCallback(
-    (config: { providerId?: string | null; model?: string | null; reasoningEffort?: string | null }) => {
+    (
+      config: { providerId?: string | null; model?: string | null; reasoningEffort?: string | null },
+      options?: { persist?: boolean },
+    ) => {
+      const persist = options?.persist !== false;
+      if (!persist && config.providerId) sessionPickRef.current = config.providerId;
+      else if (persist && config.providerId !== undefined) sessionPickRef.current = null;
       setAiConfig(prev => {
         const saved = getAIProviderSettings();
         const providerId = config.providerId !== undefined ? config.providerId : prev.providerId;
@@ -104,12 +120,14 @@ export function useAIProviderConfig({
         // (e.g. the static fallback a lazily-discovered provider advertises
         // before activation) must never overwrite the user's saved preference
         // — the session request may fall back, the cookie may not.
-        saveAIProviderSelection({
-          providerId: next.providerId,
-          model: config.model !== undefined ? next.model : null,
-          origin,
-          settings: saved,
-        });
+        if (persist) {
+          saveAIProviderSelection({
+            providerId: next.providerId,
+            model: config.model !== undefined ? next.model : null,
+            origin,
+            settings: saved,
+          });
+        }
         return next;
       });
     },

package/hooks/useAnnotationHighlighter.ts

@@ -1105,6 +1105,10 @@ 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;
+      // An answer to a `:::question` block quotes the prompt but is not a
+      // selection: the question block draws it from the annotation, so it is
+      // never painted as a highlight (and never reported as unanchored here).
+      if (ann.questionAnswer) 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

package/hooks/useDiffFileTreeExpansion.ts

@@ -0,0 +1,92 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import {
+  getAllFolderPaths,
+  getAncestorPaths,
+  type DiffFileTreeFile,
+  type DiffFileTreeNode,
+} from '../utils/diffFileTree';
+
+/** Which folders start open: every folder (the review's behavior), none, or
+ * an explicit list of folder paths (`DiffFileTreeNode.path`). */
+export type DiffFileTreeDefaultExpanded = 'all' | 'none' | readonly string[];
+
+function initialSet(allFolderPaths: string[], defaultExpanded: DiffFileTreeDefaultExpanded): Set<string> {
+  if (defaultExpanded === 'all') return new Set(allFolderPaths);
+  if (defaultExpanded === 'none') return new Set();
+  return new Set(defaultExpanded);
+}
+
+/**
+ * Folder open/closed state for a diff file tree, shared by the review's
+ * FileTree and the embeddable DiffFileTree:
+ * - starts from `defaultExpanded` and resets to it whenever `tree` changes
+ *   identity (a new diff), so pass a memoized tree;
+ * - keeps every ancestor of `activePath` open, so moving the selection always
+ *   reveals the selected file.
+ */
+export function useDiffFileTreeExpansion<F extends DiffFileTreeFile>(
+  tree: DiffFileTreeNode<F>[],
+  activePath: string | null | undefined,
+  defaultExpanded: DiffFileTreeDefaultExpanded = 'all',
+) {
+  const allFolderPaths = useMemo(() => getAllFolderPaths(tree), [tree]);
+  const [expandedFolders, setExpandedFolders] = useState<Set<string>>(() => initialSet(allFolderPaths, defaultExpanded));
+  const [prevTree, setPrevTree] = useState(tree);
+
+  // Reset when the tree changes (initial render + diff switch).
+  if (tree !== prevTree) {
+    setPrevTree(tree);
+    setExpandedFolders(initialSet(allFolderPaths, defaultExpanded));
+  }
+
+  // Auto-expand ancestors of the active file so keyboard nav always reveals the target.
+  useEffect(() => {
+    if (activePath) {
+      const ancestors = getAncestorPaths(activePath);
+      setExpandedFolders((prev) => {
+        const missing = ancestors.filter((p) => !prev.has(p));
+        if (missing.length === 0) return prev;
+        const next = new Set(prev);
+        for (const p of missing) next.add(p);
+        return next;
+      });
+    }
+  }, [activePath, tree]);
+
+  const toggleFolder = useCallback((path: string) => {
+    setExpandedFolders((prev) => {
+      const next = new Set(prev);
+      if (next.has(path)) {
+        next.delete(path);
+      } else {
+        next.add(path);
+      }
+      return next;
+    });
+  }, []);
+
+  const setFolderExpanded = useCallback((path: string, expanded: boolean) => {
+    setExpandedFolders((prev) => {
+      if (prev.has(path) === expanded) return prev;
+      const next = new Set(prev);
+      if (expanded) next.add(path);
+      else next.delete(path);
+      return next;
+    });
+  }, []);
+
+  const areAllFoldersExpanded = allFolderPaths.length > 0 && allFolderPaths.every((path) => expandedFolders.has(path));
+
+  const toggleAllFolders = useCallback(() => {
+    setExpandedFolders(areAllFoldersExpanded ? new Set() : new Set(allFolderPaths));
+  }, [allFolderPaths, areAllFoldersExpanded]);
+
+  return {
+    expandedFolders,
+    allFolderPaths,
+    areAllFoldersExpanded,
+    toggleFolder,
+    setFolderExpanded,
+    toggleAllFolders,
+  };
+}