@plannotator/ui 0.50.0 → 0.51.0

package/hooks/useAIChat.ts

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import type { AIContext } from '@plannotator/core';
 import type { AIQuestion, AIResponse } from '../types';
 import { generateId } from '../utils/generateId';
+import { SESSION_ASK_ERROR_CODES } from '../utils/aiProvider';
 
 export interface AIChatEntry {
   question: AIQuestion;
@@ -91,7 +92,8 @@ export function buildDefaultPrompt(params: AskAIParams): string {
       const label = params.scope.label ? `Re: ${params.scope.label}` : 'Re: selected text';
       const source = params.scope.sourcePath ? `\nSource: ${params.scope.sourcePath}` : '';
       const selection = params.scope.text ? `\n\nSelected text:\n\`\`\`\n${params.scope.text}\n\`\`\`` : '';
-      return `${label}${source}${selection}\n\n${params.prompt}`;
+      const detail = params.scope.detail?.trim() ? `\n\nSelected element:\n${params.scope.detail.trim()}` : '';
+      return `${label}${source}${selection}${detail}\n\n${params.prompt}`;
     }
 
     // General question (no explicit file/line/selection): tell the agent what the
@@ -289,8 +291,8 @@ export function useAIChat({
     return safeAbort(sessionId);
   }, []);
 
-  // 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").
+  // The params each question was asked with, so a busy answer can be
+  // re-asked ("Ask when it finishes", "Interrupt and ask now").
   const paramsByQuestionRef = useRef(new Map<string, AskAIParams>());
 
   const ask = useCallback(async (params: AskAIParams, askOptions?: { providerId?: string }) => {
@@ -420,6 +422,25 @@ export function useAIChat({
                 description: msg.description,
                 toolUseId: msg.toolUseId,
               }]);
+            } else if (msg.type === 'error' && msg.code === SESSION_ASK_ERROR_CODES.takenOver) {
+              // "Ask this session": the person typed into the session while it
+              // answered. The answer so far stands; the reason is a note under
+              // it, not an error that would replace it.
+              updateMessages(prev =>
+                prev.map(m =>
+                  m.question.id === questionId
+                    ? {
+                        ...m,
+                        response: {
+                          ...m.response,
+                          notice: typeof msg.error === 'string' ? msg.error : undefined,
+                          ...(m.response.status && { status: undefined }),
+                          isStreaming: false,
+                        },
+                      }
+                    : m
+                )
+              );
             } else if (msg.type === 'error') {
               updateMessages(prev =>
                 prev.map(m =>
@@ -498,8 +519,8 @@ export function useAIChat({
 
   /**
    * 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.
+   * ("Ask when it finishes" / "Interrupt and ask now"). `providerId` re-asks
+   * on another provider for hosts that offer one.
    */
   const retry = useCallback((questionId: string, options: AIRetryOptions = {}) => {
     const original = paramsByQuestionRef.current.get(questionId);

package/hooks/useAIProviderActivation.ts

@@ -23,13 +23,26 @@ export interface ActivatedAIProvider extends AIProviderOption {
 
 export function useAIProviderActivation(options: {
   onCapabilities: (providers: ActivatedAIProvider[], defaultProvider: string | null) => void;
+  /**
+   * The Ask AI providers the server currently lists. When given, an id not in
+   * it is never activated: at page load the selection can still hold a saved
+   * provider id (e.g. `codex-sdk`) for one render before the resolver moves it
+   * to what the server offers, and activating that id would start its model
+   * discovery even though Ask AI does not offer it (a session-bridge server
+   * lists only the bridge). Omitted keeps the old behavior.
+   */
+  providers?: ReadonlyArray<Pick<AIProviderOption, 'id'>>;
 }) {
   const activatedRef = useRef<Set<string>>(new Set());
   const onCapabilitiesRef = useRef(options.onCapabilities);
   onCapabilitiesRef.current = options.onCapabilities;
+  const providersRef = useRef(options.providers);
+  providersRef.current = options.providers;
 
   return useCallback((providerId: string | null | undefined) => {
     if (!providerId || activatedRef.current.has(providerId)) return;
+    const listed = providersRef.current;
+    if (listed && !listed.some(provider => provider.id === providerId)) return;
     activatedRef.current.add(providerId);
     fetch(`/api/ai/capabilities?activate=${encodeURIComponent(providerId)}`)
       .then(res => (res.ok ? res.json() : null))

package/hooks/useAIProviderConfig.ts

@@ -56,9 +56,9 @@ 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.
+  // A provider picked for this page only (`applyConfigChange(..., { persist:
+  // false })`): 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.

package/hooks/useActiveSection.ts

@@ -21,8 +21,9 @@ export function useActiveSection(
     const viewport = scrollElement ?? contentContainer;
     if (!contentContainer || !viewport) return;
     
-    // Find all heading elements with data-block-id
-    const headings = contentContainer.querySelectorAll('[data-block-type="heading"]');
+    // Only document headings: a heading inside a question card's context has
+    // no block id and is not a TOC section.
+    const headings = contentContainer.querySelectorAll('[data-block-type="heading"][data-block-id]');
     if (headings.length === 0) return;
     
     // Track which headings are currently intersecting

package/hooks/useAgentToolSetting.ts

@@ -0,0 +1,33 @@
+import { useCallback, useState } from 'react';
+import {
+  parseAgentToolSetting,
+  saveAgentToolSetting,
+  withSavedAgentTool,
+  type AgentToolSetting,
+} from '../utils/agentToolSetting';
+
+export interface AgentToolSettingState {
+  /** Undefined until a serverConfig reporting a tool host is adopted. */
+  readonly setting: AgentToolSetting | undefined;
+  /** Takes the agent tool fields from a `/api/plan` or `/api/diff` serverConfig. */
+  readonly adopt: (serverConfig: unknown) => void;
+  /** Writes the switch; resolves once config.json holds it, rejects with a readable Error. */
+  readonly save: (enabled: boolean) => Promise<void>;
+}
+
+/**
+ * The agent tool switch for an App: the Settings row and the one-time offer
+ * read the same state, so turning the tool on from the offer shows in
+ * Settings at once, and vice versa.
+ */
+export function useAgentToolSetting(): AgentToolSettingState {
+  const [setting, setSetting] = useState<AgentToolSetting | undefined>(undefined);
+  const adopt = useCallback((serverConfig: unknown) => {
+    setSetting(parseAgentToolSetting(serverConfig));
+  }, []);
+  const save = useCallback(async (enabled: boolean) => {
+    await saveAgentToolSetting(enabled);
+    setSetting((current) => (current ? withSavedAgentTool(current, enabled) : current));
+  }, []);
+  return { setting, adopt, save };
+}

package/hooks/useAnnotationDraft.ts

@@ -41,17 +41,30 @@ const DEBOUNCE_MS = 500;
  *  - `load` returns the raw stored body (or null) plus the generation the
  *    store reports when there is NO draft (the default reads `draftGeneration`
  *    from the 404 body) so the client can resume past a tombstone.
+ *  - `save` MAY resolve `{ staleGeneration }` when the store refused the body
+ *    as stale (the default reads it from a `409 { draftGeneration }` that is
+ *    not marked `decided: true`, which
+ *    annotate servers answer when the file's path copy was deleted or moved
+ *    ahead by another session). The hook then raises its counter above that
+ *    generation and saves again, once. Resolving nothing keeps the old
+ *    behavior, so a host transport that never refuses needs no change.
  */
 export interface DraftTransport {
   /** GET the draft. `data` is the raw stored body (null if none). `generation`
       is the store's reported generation when there is no draft (null otherwise). */
   load(): Promise<{ data: unknown | null; generation: number | null }>;
-  /** Persist the draft body. `keepalive` requests best-effort delivery on close. */
-  save(body: object, opts: { keepalive: boolean }): Promise<void>;
+  /** Persist the draft body. `keepalive` requests best-effort delivery on close.
+      Resolves `{ staleGeneration }` when the store refused the body as stale. */
+  save(body: object, opts: { keepalive: boolean }): Promise<void | DraftSaveRefused>;
   /** Generation-gated tombstone delete. */
   remove(generation: number, opts: { keepalive: boolean }): Promise<void>;
 }
 
+/** A save the store refused as stale: the highest generation it knows. */
+export interface DraftSaveRefused {
+  staleGeneration: number;
+}
+
 /**
  * Default transport — Plannotator's `/api/draft` fetches, moved verbatim.
  * `save` rejects on failure (the keepalive retry stays in the hook so its
@@ -73,7 +86,15 @@ const defaultDraftTransport: DraftTransport = {
     const payload = JSON.stringify(body);
     const headers = { 'Content-Type': 'application/json' };
     return fetch('/api/draft', { method: 'POST', headers, body: payload, keepalive }).then(
-      () => {},
+      async (res): Promise<void | DraftSaveRefused> => {
+        if (res.status !== 409) return;
+        const data = (await res.json().catch(() => null)) as (MissingDraftData & { decided?: boolean }) | null;
+        // The review was decided: saving again would put back comments that
+        // were just sent, so a decided refusal is never retried.
+        if (data?.decided === true) return;
+        const staleGeneration = readDraftGeneration(data?.draftGeneration);
+        return staleGeneration !== null ? { staleGeneration } : undefined;
+      },
     );
   },
   remove(generation, { keepalive }) {
@@ -281,6 +302,10 @@ interface UseAnnotationDraftResult {
   scheduleDraftSaveAfterSubmitFailure: () => void;
   getDraftGeneration: () => number;
   dismissDraft: () => void;
+  /** Send a pending (debounced) save now, if there is one. For a session
+      that ends WITHOUT a decision body (the agent closed it): the comment
+      typed just before must still reach the kept draft. */
+  flushPendingSave: () => void;
 }
 
 export function useAnnotationDraft({
@@ -393,7 +418,7 @@ export function useAnnotationDraft({
       });
   }, [isApiMode, isSharedSession]);
 
-  const persistNow = useCallback((keepalive: boolean) => {
+  const persistNow = useCallback((keepalive: boolean, retried = false) => {
     // Re-check: the session may have been submitted while the debounce was
     // pending — a save landing after submit would resurrect a draft the
     // server just deleted, ghosting it into the next session for this plan.
@@ -429,15 +454,29 @@ export function useAnnotationDraft({
     // The transport moves the POST behind the seam; the keepalive retry-on-failure
     // gate stays in the hook verbatim so a host transport that resolves/rejects on
     // failure still won't resurrect a superseded save.
-    getDraftTransport().save(payload, { keepalive }).catch(() => {
+    // A refused (stale) save means the store moved past this tab's counter:
+    // another session on the same file decided or saved ahead of it. Adopt
+    // the store's generation and save again, so the reviewer's comments are
+    // not silently left unsaved. Only while this is still the latest save,
+    // and only once per save.
+    const retryIfRefused = (result: void | DraftSaveRefused) => {
+      if (!result || retried) return;
+      if (!canPersistRef.current || draftGenerationRef.current !== draftGeneration) return;
+      draftGenerationRef.current = Math.max(draftGenerationRef.current, result.staleGeneration);
+      persistNowRef.current(false, true);
+    };
+
+    getDraftTransport().save(payload, { keepalive }).then(retryIfRefused, () => {
       // Chromium caps keepalive bodies (~64KB); retry without it. Completes
       // fine when the page was only backgrounded, best-effort on close.
       if (keepalive && canPersistRef.current && draftGenerationRef.current === draftGeneration) {
-        getDraftTransport().save(payload, { keepalive: false }).catch(() => {});
+        getDraftTransport().save(payload, { keepalive: false }).then(retryIfRefused, () => {});
       }
       // Otherwise silent failure — draft is best-effort.
     });
   }, []);
+  const persistNowRef = useRef(persistNow);
+  persistNowRef.current = persistNow;
 
   const scheduleDraftSave = useCallback(() => {
     if (!canPersistRef.current || !hasMountedRef.current) return;
@@ -457,6 +496,13 @@ export function useAnnotationDraft({
 
   const getDraftGeneration = useCallback(() => draftGenerationRef.current + 1, []);
 
+  const flushPendingSave = useCallback(() => {
+    if (timerRef.current === null) return;
+    clearTimeout(timerRef.current);
+    timerRef.current = null;
+    persistNow(false);
+  }, [persistNow]);
+
   // Flush a pending save when the page is backgrounded or closed — otherwise
   // the last debounce window of typing is lost on tab close, and reopening
   // the (still-running) session would restore a draft missing those
@@ -519,5 +565,5 @@ export function useAnnotationDraft({
     getDraftTransport().remove(deletedGeneration, { keepalive: false }).catch(() => {});
   }, []);
 
-  return { draftBanner, restoreDraft, scheduleDraftSave, scheduleDraftSaveAfterSubmitFailure, getDraftGeneration, dismissDraft };
+  return { draftBanner, restoreDraft, scheduleDraftSave, scheduleDraftSaveAfterSubmitFailure, getDraftGeneration, dismissDraft, flushPendingSave };
 }

package/hooks/useAnnotationHighlighter.ts

@@ -11,6 +11,7 @@ import type { Annotation, EditorMode, ImageAttachment } from '../types';
 import { AnnotationType } from '../types';
 import type { QuickLabel } from '../utils/quickLabels';
 import { getIdentity } from '../utils/identity';
+import { annotationOwnsHighlight } from '../utils/annotationOwnsHighlight';
 import { transformPlainText } from '../utils/inlineTransforms';
 
 // --- Exported state types ---
@@ -283,6 +284,37 @@ const paintedTextOf = (doms: readonly HTMLElement[]): string => {
   return painted;
 };
 
+/** The block element a painted highlight sits in, found the way an
+ *  annotation's `blockId` is found when it is created (walk up from the
+ *  parent of the first highlighted node to the nearest `data-block-id`), so an
+ *  unchanged document resolves every restore to the block it was made in. */
+const blockElementOf = (dom: Node | null | undefined): HTMLElement | null => {
+  let parent = dom?.parentElement ?? null;
+  while (parent && !parent.dataset.blockId) parent = parent.parentElement;
+  return parent;
+};
+
+/** Where `quote` starts in `text`, matching whitespace-insensitively (the
+ *  same comparison the restore verification uses: a quote that crossed a
+ *  block boundary or a soft wrap carries different whitespace than the
+ *  block's text). 0 when it is not there, as at creation. */
+const quoteOffsetIn = (text: string, quote: string): number => {
+  const exact = text.indexOf(quote);
+  if (exact !== -1) return exact;
+  const needle = compactText(quote);
+  if (!needle) return 0;
+  // Compact the text while remembering each kept character's original index.
+  const positions: number[] = [];
+  let compact = '';
+  for (let i = 0; i < text.length; i++) {
+    if (/\s/.test(text[i])) continue;
+    compact += text[i];
+    positions.push(i);
+  }
+  const at = compact.indexOf(needle);
+  return at === -1 ? 0 : positions[at];
+};
+
 /**
  * Tags whose boxes a browser separates with a line break in a selection string.
  *
@@ -661,9 +693,34 @@ export interface AnnotationRestoreReport {
   /** Ids the pass considered — including ones already painted, which are
    *  anchored by definition. A host clears their unanchored marks. */
   attempted: string[];
-  /** Of those, the ones left with no highlight because the stored positions
-   *  resolved onto the wrong text AND the quote was nowhere in the document. */
+  /** Of those, the ones left with no highlight: neither the stored positions
+   *  (absent, unresolvable, or resolved onto the wrong text) nor a search for
+   *  the quote found it in the document. */
   unanchored: string[];
+  /** Annotations whose stored `blockId` no longer names where their text is,
+   *  because the document changed since they were made (a draft restored
+   *  after an edit, a plan revision). Each entry says where the text is NOW:
+   *  `blockId` is the block the highlight landed in, or `''` when the text is
+   *  gone (every unanchored id is listed here too). Annotations whose stored
+   *  block still holds their text are never listed, so an unchanged document
+   *  reports nothing here. A host that exports line numbers from `blockId`
+   *  should write these back. Optional so older reporters (the diagram
+   *  overlay) need not produce it. */
+  moved?: RestoredAnchor[];
+}
+
+/** Where a restored annotation's text sits now (see `moved`). */
+export interface RestoredAnchor {
+  id: string;
+  /** The block the highlight landed in; `''` when the text is gone. */
+  blockId: string;
+  /** Offset of the quote in that block's text (same rule as creation);
+   *  absent when the text is gone. */
+  startOffset?: number;
+  /** The stored `startMeta`/`endMeta` did not lead to the text (unresolvable,
+   *  or onto other text) and should be dropped so later restores search by
+   *  text instead. False when the stored positions themselves were verified. */
+  positionsStale: boolean;
 }
 
 /** Annotation UI state and mutation commands owned by one rendered document. */
@@ -1097,9 +1154,36 @@ export function useAnnotationHighlighter({
 
     const attempted: string[] = [];
     const unanchored: string[] = [];
+    const moved: RestoredAnchor[] = [];
+
+    // Record where a restored annotation's text sits when its stored blockId
+    // no longer names that place. Block ids are positional (`block-N`), so
+    // after the document changed the stored id can name a different block,
+    // and a line label read from it would point at the wrong line. Nothing is
+    // recorded while the stored block still holds the quote — an unchanged
+    // document, or a quote that also appears in the stored block — so the
+    // stored id (and the export built from it) stays exactly as it was.
+    const noteAnchor = (ann: Annotation, firstDom: Node | null | undefined, positionsStale: boolean) => {
+      if (!ann.blockId) return;
+      const blockEl = blockElementOf(firstDom);
+      const blockId = blockEl?.dataset.blockId;
+      if (!blockEl || !blockId || blockId === ann.blockId) return;
+      const stored = containerRef.current?.querySelector(
+        `[data-block-id="${escapeAttrValue(ann.blockId)}"]`,
+      );
+      const quote = compactText(ann.originalText);
+      if (stored && quote && compactText(stored.textContent ?? '').includes(quote)) return;
+      moved.push({ id: ann.id, blockId, startOffset: quoteOffsetIn(blockEl.textContent ?? '', ann.originalText), positionsStale });
+    };
 
     anns.forEach(ann => {
       if (ann.type === AnnotationType.GLOBAL_COMMENT) return;
+      // Diff-view comments (`diff-block-N`, drawn by the diff view) and
+      // checkbox toggles (raw-markdown quotes keyed by their block) are never
+      // text highlights. Callers filter them out; skipping them here as well
+      // keeps a stray one from being reported unanchored or moved, which would
+      // rewrite its blockId.
+      if (!annotationOwnsHighlight(ann)) return;
       // A comment on a rendered diagram part has no text anchor: the
       // diagram overlay restores it against its render and reports its own
       // verdict, so it is neither attempted nor unanchored here (the same
@@ -1128,7 +1212,8 @@ export function useAnnotationHighlighter({
       if (existingManual) return;
 
       const mathTargets = findMathElementsForAnnotation(ann);
-      if (mathTargets.length > 0) {
+      const paintedMath = mathTargets.length > 0;
+      if (paintedMath) {
         applyMathTargets(mathTargets, ann.id, ann.type);
         if (!ann.startMeta && !ann.endMeta && !ann.mathTargets?.length) {
           return;
@@ -1160,6 +1245,7 @@ export function useAnnotationHighlighter({
               } else if (ann.type === AnnotationType.COMMENT) {
                 highlighter.addClass('comment', ann.id);
               }
+              if (!paintedMath) noteAnchor(ann, restoredDoms[0] as Node, false);
               return;
             }
           }
@@ -1169,9 +1255,15 @@ export function useAnnotationHighlighter({
       const range = findTextInDOM(ann.originalText);
       if (!range) {
         if (rejectedRestoreText !== null) {
-          unanchored.push(ann.id);
           onRestoreMismatchRef.current?.(ann, rejectedRestoreText);
         }
+        // Nothing painted it: not the stored positions (absent, unresolvable,
+        // or onto other text) and not the search. A formula the math path
+        // painted above is anchored, whatever its quote search says.
+        if (!paintedMath) {
+          unanchored.push(ann.id);
+          moved.push({ id: ann.id, blockId: '', positionsStale: true });
+        }
         console.warn(`Could not find text for annotation ${ann.id}: "${ann.originalText.slice(0, 50)}..."`);
         return;
       }
@@ -1229,6 +1321,8 @@ export function useAnnotationHighlighter({
           return;
         }
 
+        if (!paintedMath) noteAnchor(ann, textNodes[0].node, true);
+
         textNodes.reverse().forEach(({ node, start, end }) => {
           try {
             const nodeRange = document.createRange();
@@ -1259,7 +1353,9 @@ export function useAnnotationHighlighter({
       }
     });
 
-    if (attempted.length > 0) onRestoreReportRef.current?.({ attempted, unanchored });
+    if (attempted.length > 0) {
+      onRestoreReportRef.current?.({ attempted, unanchored, ...(moved.length > 0 ? { moved } : {}) });
+    }
   }, [findMathElementsForAnnotation, findTextInDOM, verifyRestoredContent]);
 
   const removeHighlight = useCallback((id: string) => {

package/hooks/useExternalAnnotations.ts

@@ -120,10 +120,25 @@ interface UseExternalAnnotationsReturn<T> {
   clearExternalAnnotations: (source?: string) => void;
 }
 
+/** The agent session that opened this review closed it (`session-closed` on the stream). */
+export interface ExternalSessionClosed {
+  unsentAnnotations: number;
+}
+
 export function useExternalAnnotations<T extends { id: string; source?: string }>(
-  options?: { enabled?: boolean },
+  options?: {
+    enabled?: boolean;
+    /**
+     * The stream reported that the agent closed this review
+     * (`POST /api/host/close`). Only the SSE stream carries it; the polling
+     * fallback does not.
+     */
+    onSessionClosed?: (event: ExternalSessionClosed) => void;
+  },
 ): UseExternalAnnotationsReturn<T> {
   const enabled = options?.enabled ?? true;
+  const onSessionClosedRef = useRef(options?.onSessionClosed);
+  onSessionClosedRef.current = options?.onSessionClosed;
   const [annotations, setAnnotations] = useState<T[]>([]);
   const versionRef = useRef(0);
   const fallbackRef = useRef(false);
@@ -175,6 +190,11 @@ export function useExternalAnnotations<T extends { id: string; source?: string }
             prev.map((a) => a.id === parsed.id ? (parsed.annotation as T) : a),
           );
           break;
+        case 'session-closed':
+          onSessionClosedRef.current?.({
+            unsentAnnotations: typeof parsed.unsentAnnotations === 'number' ? parsed.unsentAnnotations : 0,
+          });
+          break;
       }
     }
 

package/hooks/useFirstRunAnnouncementWindow.ts

@@ -0,0 +1,114 @@
+import { useEffect, useState } from 'react';
+
+/** How long after the initial load an announcement may still open. */
+export const FIRST_RUN_ANNOUNCEMENT_WINDOW_MS = 4000;
+
+/**
+ * How long after the initial load a window blur is still taken for the app's
+ * own startup (a viewer focusing its iframe) rather than the reader.
+ */
+export const FIRST_RUN_ANNOUNCEMENT_BLUR_GRACE_MS = 1000;
+
+type Phase = 'waiting' | 'shown' | 'missed';
+
+function isEditable(element: Element | null): boolean {
+  if (!(element instanceof HTMLElement)) return false;
+  if (element.isContentEditable) return true;
+  const tag = element.tagName;
+  if (tag === 'TEXTAREA' || tag === 'SELECT') return true;
+  if (tag !== 'INPUT') return false;
+  const type = (element as HTMLInputElement).type;
+  return !['button', 'checkbox', 'radio', 'submit', 'reset', 'range', 'color', 'file', 'image'].includes(type);
+}
+
+/**
+ * The reader is in something the parent cannot see into: a text field, or an
+ * iframe (the raw-HTML and live-app annotate surfaces), where their typing
+ * never reaches this document's listeners.
+ */
+function isWorkingIn(element: Element | null): boolean {
+  return isEditable(element) || element instanceof HTMLIFrameElement;
+}
+
+interface Options {
+  /** The announcement has not been seen (latched at mount). */
+  readonly pending: boolean;
+  /** Every other condition for opening holds right now. */
+  readonly eligible: boolean;
+  /** The initial payload has loaded; the window's clock starts here. */
+  readonly armed: boolean;
+  readonly windowMs?: number;
+  readonly blurGraceMs?: number;
+}
+
+/**
+ * Lets a non-blocking announcement open only before the reader has started
+ * working: before their first pointer press, key press or focus into an
+ * editable field, and within `windowMs` of the initial load. An announcement
+ * whose conditions arrive later (a slow capabilities answer, say) would take
+ * focus mid-sentence, and the Space or Enter that follows would dismiss it
+ * unread and spend its cookie. Instead it misses this load and waits for the
+ * next one; nothing is written. Once open, it stays until dismissed.
+ */
+export function useFirstRunAnnouncementWindow({
+  pending,
+  eligible,
+  armed,
+  windowMs = FIRST_RUN_ANNOUNCEMENT_WINDOW_MS,
+  blurGraceMs = FIRST_RUN_ANNOUNCEMENT_BLUR_GRACE_MS,
+}: Options): boolean {
+  const [phase, setPhase] = useState<Phase>('waiting');
+
+  // The reader's first move closes the window.
+  useEffect(() => {
+    if (phase !== 'waiting' || !pending) return;
+    const miss = () => setPhase((current) => (current === 'waiting' ? 'missed' : current));
+    const onFocusIn = (event: FocusEvent) => {
+      if (isEditable(event.target as Element | null)) miss();
+    };
+    document.addEventListener('pointerdown', miss, true);
+    document.addEventListener('keydown', miss, true);
+    document.addEventListener('focusin', onFocusIn, true);
+    return () => {
+      document.removeEventListener('pointerdown', miss, true);
+      document.removeEventListener('keydown', miss, true);
+      document.removeEventListener('focusin', onFocusIn, true);
+    };
+  }, [phase, pending]);
+
+  // Work inside an iframe (raw-HTML or live-app annotate) never reaches the
+  // listeners above, but moving into it blurs this window. Counted only after
+  // the app's own startup, which may focus a viewer iframe by itself.
+  useEffect(() => {
+    if (phase !== 'waiting' || !pending || !armed) return;
+    const miss = () => setPhase((current) => (current === 'waiting' ? 'missed' : current));
+    let listening = false;
+    const grace = setTimeout(() => {
+      listening = true;
+      window.addEventListener('blur', miss);
+    }, blurGraceMs);
+    return () => {
+      clearTimeout(grace);
+      if (listening) window.removeEventListener('blur', miss);
+    };
+  }, [phase, pending, armed, blurGraceMs]);
+
+  // So does time, counted from the end of the initial load.
+  useEffect(() => {
+    if (phase !== 'waiting' || !pending || !armed) return;
+    const timer = setTimeout(() => {
+      setPhase((current) => (current === 'waiting' ? 'missed' : current));
+    }, windowMs);
+    return () => clearTimeout(timer);
+  }, [phase, pending, armed, windowMs]);
+
+  // Open while the window is still open. Never over a field or a framed page
+  // the reader is in (a comment composer, a search box, a raw-HTML page), even
+  // an autofocused one.
+  useEffect(() => {
+    if (phase !== 'waiting' || !pending || !eligible) return;
+    setPhase(isWorkingIn(document.activeElement) ? 'missed' : 'shown');
+  }, [phase, pending, eligible]);
+
+  return pending && phase === 'shown';
+}

package/hooks/useLatchedTrue.ts

@@ -0,0 +1,15 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * True from the first render where `value` is true, for the life of the
+ * component. The Apps use it to remember that an announcement was shown on
+ * this load, so the next one in the chain waits for a later load even after
+ * the first is dismissed.
+ */
+export function useLatchedTrue(value: boolean): boolean {
+  const [latched, setLatched] = useState(value);
+  useEffect(() => {
+    if (value) setLatched(true);
+  }, [value]);
+  return latched || value;
+}