@plannotator/ui 0.30.0 → 0.32.0

package/configure.ts

@@ -8,6 +8,9 @@ import { setDraftTransport, type DraftTransport } from './hooks/useAnnotationDra
 import { setExternalAnnotationTransport, type ExternalAnnotationTransport } from './hooks/useExternalAnnotations';
 import { setAITransport, type AITransport } from './hooks/useAIChat';
 import { setSkillCatalogTransport, setSkillContentTransport, type SkillCatalogTransport, type SkillContentTransport } from './utils/skillCatalog';
+import { setWebMcpPolicy, type WebMcpPolicy } from './webmcp/policy';
+import { setMathRendererLoader, type MathRenderer, type MathRendererLoader } from './utils/math';
+import { setIdentityGenerator, type IdentityGenerator } from './utils/generateIdentity';
 import { configStore } from './config';
 import type { ServerSyncFn } from './config/configStore';
 import type { ExternalAnnotationEvent, VaultNode } from './types';
@@ -31,6 +34,10 @@ export type {
   SkillCatalogTransport,
   SkillContentTransport,
   ServerSyncFn,
+  WebMcpPolicy,
+  MathRenderer,
+  MathRendererLoader,
+  IdentityGenerator,
 };
 
 type ExternalAnnotationBase = { id: string; source?: string };
@@ -56,6 +63,28 @@ export interface PlannotatorUIConfig {
   /** Human-only skill contents request for feedback injection. Default: `GET /api/skills/content?name=` on the page origin. */
   skillContentTransport?: SkillContentTransport;
   serverSync?: ServerSyncFn;
+  /**
+   * WebMCP provider policy: `{ enabled, namePrefix }`. Default: enabled
+   * whenever the browser exposes `document.modelContext`, with the
+   * `plannotator.` prefix. There is no confirmation seam because the catalog
+   * exposes nothing consequential: no tool decides, submits or closes.
+   */
+  webmcp?: WebMcpPolicy;
+  /**
+   * How the math renderer is loaded when no renderer is registered before the
+   * first math node renders. Default: `import('katex')` (JS only; the
+   * stylesheet stays the host's job). A host that wants KaTeX and its CSS on
+   * one lazy chunk passes a loader that imports both. Hosts that want math
+   * typeset on the first commit instead import `@plannotator/ui/utils/math-eager`.
+   */
+  mathRendererLoader?: MathRendererLoader;
+  /**
+   * Synchronous generator for the default "tater" display name, used only when
+   * no `identityProvider` is installed. Default: a small built-in pool of the
+   * same `adjective-noun-tater` shape. Plannotator registers the full
+   * dictionary by importing `@plannotator/ui/utils/identity-tater`.
+   */
+  identityGenerator?: IdentityGenerator;
   /** Re-hydrate settings from the installed (SYNCHRONOUS) storageBackend after install. */
   loadSettingsFromBackend?: boolean;
 }
@@ -73,6 +102,9 @@ export function configurePlannotatorUI(config: PlannotatorUIConfig): void {
   if (config.skillCatalogTransport) setSkillCatalogTransport(config.skillCatalogTransport);
   if (config.skillContentTransport) setSkillContentTransport(config.skillContentTransport);
   if (config.serverSync) configStore.setServerSync(config.serverSync);
+  if (config.webmcp) setWebMcpPolicy(config.webmcp);
+  if (config.mathRendererLoader) setMathRendererLoader(config.mathRendererLoader);
+  if (config.identityGenerator) setIdentityGenerator(config.identityGenerator);
   // Re-hydrate AFTER storageBackend is installed (load-bearing order — gated last).
   if (config.loadSettingsFromBackend) configStore.loadFromBackend();
 }

package/hooks/useAIProviderConfig.ts

@@ -59,14 +59,15 @@ export function useAIProviderConfig({
   // 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,
+    });
+
     setAiConfig(prev => {
-      const saved = getAIProviderSettings();
-      const selection = resolveAIProviderSelection({
-        providers,
-        origin,
-        settings: saved,
-        serverDefaultProvider: defaultProvider,
-      });
       if (prev.providerId === selection.providerId && prev.model === selection.model) return prev;
       return {
         ...prev,

package/hooks/useActiveSection.ts

@@ -1,4 +1,5 @@
 import { useEffect, useState, useRef } from 'react';
+import { getScrollViewportIntersectionRoot } from './useScrollViewport';
 
 /**
  * Track which heading section is currently visible in the viewport
@@ -16,11 +17,12 @@ export function useActiveSection(
   const observerRef = useRef<IntersectionObserver | null>(null);
 
   useEffect(() => {
-    const container = scrollElement ?? containerRef.current;
-    if (!container) return;
+    const contentContainer = containerRef.current ?? scrollElement;
+    const viewport = scrollElement ?? contentContainer;
+    if (!contentContainer || !viewport) return;
     
     // Find all heading elements with data-block-id
-    const headings = container.querySelectorAll('[data-block-type="heading"]');
+    const headings = contentContainer.querySelectorAll('[data-block-type="heading"]');
     if (headings.length === 0) return;
     
     // Track which headings are currently intersecting
@@ -57,7 +59,7 @@ export function useActiveSection(
         }
       },
       {
-        root: container,
+        root: getScrollViewportIntersectionRoot(viewport),
         rootMargin: '-80px 0px -80% 0px', // Activate when heading is near top
         threshold: [0, 0.1, 0.5, 1.0],
       }

package/hooks/useAgentJobs.ts

@@ -37,6 +37,9 @@ export type AgentLaunchParams = {
    *  schema-capable engine and starts a new, normal guide job rather than
    *  mutating the failed one in place. */
   repairOf?: string;
+  /** Reviewer-supplied extra instructions (#1265), appended to the Guided
+   *  Review organizer prompt. Guide launches only; other providers ignore it. */
+  instructions?: string;
 };
 
 /** Does a job belong to the given review context? Jobs launched against a PR

package/hooks/useAnnotationHighlighter.ts

@@ -27,6 +27,7 @@ export interface CommentPopoverState {
   selectedText?: string;
   initialText?: string;
   source?: any;
+  draftKey: string;
 }
 
 export interface QuickLabelPickerState {
@@ -46,6 +47,21 @@ type MathAnnotationSource = {
 const isMathAnnotationSource = (source: any): source is MathAnnotationSource =>
   source?.kind === 'math';
 
+function commentDraftTargetKey(source: any, selectedText: string): string {
+  if (isMathAnnotationSource(source)) {
+    return `math:${source.blockId}:${source.text}`;
+  }
+  const start = source?.startMeta;
+  const end = source?.endMeta;
+  const startKey = start
+    ? `${start.parentTagName}:${start.parentIndex}:${start.textOffset}`
+    : 'unknown';
+  const endKey = end
+    ? `${end.parentTagName}:${end.parentIndex}:${end.textOffset}`
+    : 'unknown';
+  return `selection:${startKey}:${endKey}:${selectedText}`;
+}
+
 type MathAnnotationTarget = {
   element: HTMLElement;
   blockId: string;
@@ -859,6 +875,7 @@ export function useAnnotationHighlighter({
               contextText: source.text.slice(0, 80),
               selectedText: source.text,
               source,
+              draftKey: commentDraftTargetKey(source, source.text),
             });
           } else if (effectiveMode === 'quickLabel') {
             pendingSourceRef.current = source;
@@ -944,6 +961,7 @@ export function useAnnotationHighlighter({
           contextText: source.text.slice(0, 80),
           selectedText: source.text,
           source,
+          draftKey: commentDraftTargetKey(source, source.text),
         });
         return;
       }
@@ -1061,6 +1079,7 @@ export function useAnnotationHighlighter({
         contextText: source.text.slice(0, 80),
         selectedText: source.text,
         source,
+        draftKey: commentDraftTargetKey(source, source.text),
       });
       return;
     }
@@ -1204,6 +1223,7 @@ export function useAnnotationHighlighter({
       selectedText: toolbarState.selectionText,
       initialText: initialChar,
       source: toolbarState.source,
+      draftKey: commentDraftTargetKey(toolbarState.source, toolbarState.selectionText),
     });
     setToolbarState(null);
   };

package/hooks/useHtmlRefresh.ts

@@ -0,0 +1,149 @@
+import { useCallback, useLayoutEffect, useRef, useState } from 'react';
+
+/** What a host's `fetchSnapshot` resolves to. */
+export type HtmlRefreshSnapshot =
+  | { status: 'ok'; rawHtml: string }
+  | { status: 'missing' }
+  | { status: 'unavailable' };
+
+/** The outcome of one `refresh()` call, for host notifications (toasts). */
+export type HtmlRefreshResult = 'refreshed' | 'missing' | 'unavailable';
+
+export interface UseHtmlRefreshOptions {
+  /** Whether refresh is offered at all. Default true. */
+  enabled?: boolean;
+  /**
+   * Identity of the document under refresh (a path, an id). A change
+   * cancels any in-flight fetch and any pending restore acknowledgement, so
+   * a snapshot for the previous document can never land on the next one.
+   * `null` means no document: `canRefresh` is false. Omit it when the host
+   * has a single document.
+   */
+  documentKey?: string | null;
+  /** Fetch the current bytes of the document. Called with `documentKey`.
+   *  A rejection is treated as `{ status: 'unavailable' }`. */
+  fetchSnapshot: (documentKey: string | null) => Promise<HtmlRefreshSnapshot>;
+  /** Apply the refreshed bytes (the host owns the viewer's `rawHtml`). */
+  onSnapshot: (rawHtml: string) => void;
+  /**
+   * Once per refresh: the ids the remounted viewer could not re-anchor,
+   * possibly empty. Wire the viewer's `onUnanchoredChange` to the returned
+   * `reportAnnotationRestore`; only the first report after a refresh is
+   * forwarded, and only while the document and reload generation match.
+   */
+  onUnanchored?: (ids: string[]) => void;
+  /** The outcome of each `refresh()` call that reached a decision. */
+  onResult?: (result: HtmlRefreshResult) => void;
+}
+
+export interface UseHtmlRefreshReturn {
+  canRefresh: boolean;
+  isRefreshing: boolean;
+  /** Bumps after every applied snapshot. Key the viewer on it to remount. */
+  reloadGeneration: number;
+  refresh: () => Promise<void>;
+  /** Feed the viewer's `onUnanchoredChange` report here. */
+  reportAnnotationRestore: (missingIds: string[]) => void;
+}
+
+/**
+ * Re-fetch a rendered HTML document from the host's source and remount the
+ * viewer on it, keeping the annotations the viewer can still anchor.
+ *
+ * Backend-agnostic: the host supplies `fetchSnapshot` (Plannotator wraps its
+ * `/api/doc` read; a host with a document store passes its own read). The
+ * hook owns the guards: an in-flight fetch that is superseded by a newer
+ * refresh, or by a document change, is dropped before `onSnapshot`; the
+ * restore acknowledgement is armed per reload generation and consumed by
+ * the first viewer report for that generation.
+ */
+export function useHtmlRefresh({
+  enabled = true,
+  documentKey,
+  fetchSnapshot,
+  onSnapshot,
+  onUnanchored,
+  onResult,
+}: UseHtmlRefreshOptions): UseHtmlRefreshReturn {
+  const [isRefreshing, setIsRefreshing] = useState(false);
+  const [reloadGeneration, setReloadGeneration] = useState(0);
+  const keyed = documentKey !== undefined;
+  const activeKey = keyed ? documentKey : null;
+  const activeKeyRef = useRef(activeKey);
+  const requestRef = useRef(0);
+  const reloadGenerationRef = useRef(0);
+  const restorePendingRef = useRef<{ key: string | null; generation: number } | null>(null);
+  const onUnanchoredRef = useRef(onUnanchored);
+  onUnanchoredRef.current = onUnanchored;
+  const onResultRef = useRef(onResult);
+  onResultRef.current = onResult;
+  const canRefresh = enabled && (!keyed || !!documentKey);
+
+  useLayoutEffect(() => {
+    if (activeKeyRef.current !== activeKey) {
+      requestRef.current += 1;
+      restorePendingRef.current = null;
+      setIsRefreshing(false);
+    }
+    activeKeyRef.current = activeKey;
+  }, [activeKey]);
+
+  const refresh = useCallback(async () => {
+    if (!canRefresh) return;
+
+    const requestKey = activeKey;
+    const requestId = ++requestRef.current;
+    setIsRefreshing(true);
+    try {
+      // A rejecting fetch is an unavailable snapshot: the host hears it
+      // through onResult like any other outcome, never as an unhandled
+      // rejection out of refresh().
+      let result: HtmlRefreshSnapshot;
+      try {
+        result = await fetchSnapshot(requestKey);
+      } catch {
+        result = { status: 'unavailable' };
+      }
+      if (requestId !== requestRef.current || activeKeyRef.current !== requestKey) return;
+
+      if (result.status === 'missing' || result.status === 'unavailable') {
+        onResultRef.current?.(result.status);
+        return;
+      }
+
+      onSnapshot(result.rawHtml);
+      const nextGeneration = reloadGenerationRef.current + 1;
+      reloadGenerationRef.current = nextGeneration;
+      // Armed until the remounted viewer's bridge reports its restore. The
+      // bridge emits "unanchored" only when the set CHANGES from its initial
+      // empty state, so a pass that restores everything never posts and this
+      // stays armed; that is harmless because the next refresh replaces it
+      // and a document change clears it.
+      restorePendingRef.current = { key: requestKey, generation: nextGeneration };
+      setReloadGeneration(nextGeneration);
+      onResultRef.current?.('refreshed');
+    } finally {
+      if (requestId === requestRef.current) setIsRefreshing(false);
+    }
+  }, [activeKey, canRefresh, fetchSnapshot, onSnapshot]);
+
+  const reportAnnotationRestore = useCallback((missingIds: string[]) => {
+    const pending = restorePendingRef.current;
+    if (
+      !pending ||
+      pending.key !== activeKeyRef.current ||
+      pending.generation !== reloadGenerationRef.current
+    ) return;
+
+    restorePendingRef.current = null;
+    onUnanchoredRef.current?.(missingIds);
+  }, []);
+
+  return {
+    canRefresh,
+    isRefreshing,
+    reloadGeneration,
+    refresh,
+    reportAnnotationRestore,
+  };
+}

package/hooks/useIsMobile.ts

@@ -1,5 +1,17 @@
 import { useState, useEffect } from 'react';
 
+/** Maximum CSS viewport width that can enter Plannotator's compact touch shell. */
+export const COMPACT_TOUCH_LAYOUT_MAX_WIDTH = 1024;
+
+/**
+ * Canonical media query for the compact application shell.
+ *
+ * The primary pointer is intentional: `any-pointer: coarse` also matches
+ * touchscreen laptops whose primary mouse or trackpad needs the desktop shell.
+ */
+export const COMPACT_TOUCH_LAYOUT_MEDIA_QUERY =
+  `(max-width: ${COMPACT_TOUCH_LAYOUT_MAX_WIDTH}px) and (pointer: coarse)`;
+
 export function useIsMobile(breakpoint = 768): boolean {
   const [isMobile, setIsMobile] = useState(
     () => typeof window !== 'undefined' ? window.innerWidth < breakpoint : false
@@ -15,3 +27,28 @@ export function useIsMobile(breakpoint = 768): boolean {
 
   return isMobile;
 }
+
+/**
+ * Reports whether the current viewport needs Plannotator's compact touch shell.
+ * Plan and Code Review must share this decision so responsive chrome and scroll
+ * ownership cannot diverge on hybrid devices.
+ */
+export function useCompactTouchLayout(): boolean {
+  const [isCompactTouchLayout, setIsCompactTouchLayout] = useState(
+    () => typeof window !== 'undefined'
+      && window.matchMedia(COMPACT_TOUCH_LAYOUT_MEDIA_QUERY).matches,
+  );
+
+  useEffect(() => {
+    const mediaQuery = window.matchMedia(COMPACT_TOUCH_LAYOUT_MEDIA_QUERY);
+    const onChange = (event: MediaQueryListEvent) => {
+      setIsCompactTouchLayout(event.matches);
+    };
+
+    mediaQuery.addEventListener('change', onChange);
+    setIsCompactTouchLayout(mediaQuery.matches);
+    return () => mediaQuery.removeEventListener('change', onChange);
+  }, []);
+
+  return isCompactTouchLayout;
+}

package/hooks/useLinkedDoc.ts

@@ -90,6 +90,9 @@ export interface UseLinkedDocOptions {
   /** Let the host initialize/restore editable document state and optionally
    *  override the markdown displayed for this file. */
   onDocumentLoaded?: (doc: LinkedDocLoadData) => string | undefined;
+  /** Notify the host after any fetched or already-loaded destination has been
+   *  activated, including HTML documents and backlinks to the source. */
+  onDocumentActivated?: (doc: LinkedDocLoadData & { filepath: string }) => void;
   /** Read current host-owned text when caching a linked doc. */
   getDocumentMarkdown?: (filepath: string, fallback?: string) => string | undefined;
   /** Let the host restore any state that was suspended while a linked doc was active. */
@@ -185,6 +188,7 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
     sourceConverted,
     onBeforeNavigate,
     onDocumentLoaded,
+    onDocumentActivated,
     getDocumentMarkdown,
     onAfterBack,
   } = options;
@@ -292,6 +296,7 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
     // annotations intact.
     if (sourceFilePath && data.filepath === sourceFilePath && savedPlanState.current) {
       back();
+      onDocumentActivated?.(data);
       return;
     }
 
@@ -364,6 +369,7 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
     });
     setError(null);
     sidebar.open(targetTab ?? "toc");
+    onDocumentActivated?.(data);
 
     // Re-apply cached annotations after DOM settles
     if (cached?.annotations.length) {
@@ -393,6 +399,7 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
     sourceFilePath,
     onBeforeNavigate,
     onDocumentLoaded,
+    onDocumentActivated,
     getDocumentMarkdown,
     back,
   ]);

package/hooks/useMathRenderer.ts

@@ -0,0 +1,30 @@
+import { useEffect, useSyncExternalStore } from 'react';
+import {
+  getMathRenderer,
+  loadMathRenderer,
+  subscribeMathRenderer,
+  type MathRenderer,
+} from '../utils/math';
+
+/**
+ * The registered math renderer, read synchronously during render.
+ *
+ * With the slot filled before mount (Plannotator: `utils/math-eager`) this
+ * returns KaTeX on the first render and the effect below is a no-op, so the
+ * typeset HTML is in the first commit. With the slot empty it returns `null`,
+ * kicks off `loadMathRenderer()` from an effect, and the subscription
+ * re-renders the caller once the renderer lands. A rejected load is left to
+ * the loader's retry contract; the caller keeps showing the TeX placeholder.
+ */
+export function useMathRenderer(): MathRenderer | null {
+  const renderer = useSyncExternalStore(subscribeMathRenderer, getMathRenderer, getMathRenderer);
+
+  useEffect(() => {
+    if (renderer) return;
+    loadMathRenderer().catch(() => {
+      /* placeholder stays; the next mount retries */
+    });
+  }, [renderer]);
+
+  return renderer;
+}

package/hooks/useScrollViewport.ts

@@ -1,5 +1,79 @@
 import { createContext, useContext, createElement, type ReactNode } from 'react';
 
+/** Return whether this element is the browser's page-scrolling element. */
+export function isDocumentScrollViewport(
+  viewport: HTMLElement | null,
+): boolean {
+  return viewport !== null
+    && viewport.ownerDocument.scrollingElement === viewport;
+}
+
+/** Resolve the document scroller without assuming whether WebKit chose html or body. */
+export function getDocumentScrollViewport(
+  targetDocument: Document = document,
+): HTMLElement | null {
+  return targetDocument.scrollingElement as HTMLElement | null;
+}
+
+/**
+ * Page scrolling needs viewport geometry, not the document element's full
+ * content rect. Element-backed scroll areas retain their incumbent geometry.
+ */
+export function getScrollViewportRect(viewport: HTMLElement): DOMRect {
+  if (!isDocumentScrollViewport(viewport)) return viewport.getBoundingClientRect();
+
+  const targetWindow = viewport.ownerDocument.defaultView;
+  const visualViewport = targetWindow?.visualViewport;
+  const left = visualViewport?.offsetLeft ?? 0;
+  const top = visualViewport?.offsetTop ?? 0;
+  const width = visualViewport?.width ?? targetWindow?.innerWidth ?? viewport.clientWidth;
+  const height = visualViewport?.height ?? targetWindow?.innerHeight ?? viewport.clientHeight;
+  const DOMRectConstructor = targetWindow?.DOMRect ?? DOMRect;
+  return new DOMRectConstructor(left, top, width, height);
+}
+
+export function getScrollViewportTop(viewport: HTMLElement): number {
+  if (!isDocumentScrollViewport(viewport)) return viewport.scrollTop;
+  return viewport.ownerDocument.defaultView?.scrollY ?? viewport.scrollTop;
+}
+
+export function scrollViewportTo(
+  viewport: HTMLElement,
+  options: ScrollToOptions,
+): void {
+  if (!isDocumentScrollViewport(viewport)) {
+    viewport.scrollTo(options);
+    return;
+  }
+  viewport.ownerDocument.defaultView?.scrollTo(options);
+}
+
+export function offsetScrollViewport(viewport: HTMLElement, delta: number): void {
+  if (!isDocumentScrollViewport(viewport)) {
+    viewport.scrollTop += delta;
+    return;
+  }
+  viewport.ownerDocument.defaultView?.scrollBy({ top: delta, behavior: 'auto' });
+}
+
+export function addScrollViewportListener(
+  viewport: HTMLElement,
+  listener: EventListener,
+): () => void {
+  const target: EventTarget = isDocumentScrollViewport(viewport)
+    ? viewport.ownerDocument.defaultView ?? viewport
+    : viewport;
+  target.addEventListener('scroll', listener, { passive: true });
+  return () => target.removeEventListener('scroll', listener);
+}
+
+/** A document scroll uses the browser viewport as its IntersectionObserver root. */
+export function getScrollViewportIntersectionRoot(
+  viewport: HTMLElement,
+): Element | null {
+  return isDocumentScrollViewport(viewport) ? null : viewport;
+}
+
 /**
  * Provides the currently-active scroll viewport element to descendants.
  *

package/hooks/useSharing.ts

@@ -8,7 +8,7 @@
  * - Tracking whether current session is from a shared link
  */
 
-import React, { useState, useEffect, useCallback, useRef } from 'react';
+import React, { useState, useEffect, useCallback, useMemo, useRef } from 'react';
 import { Annotation, type ImageAttachment } from '../types';
 import {
   type SharePayload,
@@ -104,6 +104,7 @@ export function useSharing(
   setRawHtml?: (h: string) => void,
   setShareHtml?: (h: string) => void,
   setRenderAs?: (m: 'markdown' | 'html') => void,
+  contentRevision = 0,
 ): UseSharingResult {
   const [isSharedSession, setIsSharedSession] = useState(false);
   const [isLoadingShared, setIsLoadingShared] = useState(true);
@@ -115,6 +116,23 @@ export function useSharing(
   const [pendingSharedAnnotations, setPendingSharedAnnotations] = useState<Annotation[] | null>(null);
   const [sharedGlobalAttachments, setSharedGlobalAttachments] = useState<ImageAttachment[] | null>(null);
   const [shareLoadError, setShareLoadError] = useState('');
+  // Identity token for in-flight share requests: a new token invalidates any
+  // response still on the wire. Content inputs only — resolveRawHtmlForShare
+  // is deliberately NOT a dependency: its identity changes when it caches the
+  // portable HTML mid-request (App memoizes it on shareHtml), and listing it
+  // would make the first short-link generation on an HTML session discard its
+  // own result. HTML refreshes invalidate through contentRevision instead.
+  const shareRequestContext = useMemo(() => ({}), [
+    markdown,
+    annotations,
+    globalAttachments,
+    shareBaseUrl,
+    pasteApiUrl,
+    rawHtml,
+    contentRevision,
+  ]);
+  const latestShareRequestContextRef = useRef(shareRequestContext);
+  latestShareRequestContextRef.current = shareRequestContext;
 
   const clearPendingSharedAnnotations = useCallback(() => {
     setPendingSharedAnnotations(null);
@@ -257,16 +275,19 @@ export function useSharing(
 
   // Generate share URL when markdown or annotations change
   const refreshShareUrl = useCallback(async () => {
+    const requestContext = shareRequestContext;
     try {
       const url = await generateShareUrl(markdown, annotations, globalAttachments, shareBaseUrl, rawHtml);
+      if (latestShareRequestContextRef.current !== requestContext) return;
       setShareUrl(url ?? '');
       setShareUrlSize(url ? formatUrlSize(url) : '');
     } catch (e) {
+      if (latestShareRequestContextRef.current !== requestContext) return;
       console.error('Failed to generate share URL:', e);
       setShareUrl('');
       setShareUrlSize('');
     }
-  }, [markdown, annotations, globalAttachments, shareBaseUrl, rawHtml]);
+  }, [markdown, annotations, globalAttachments, shareBaseUrl, rawHtml, shareRequestContext]);
 
   // Auto-refresh share URL when dependencies change
   useEffect(() => {
@@ -280,9 +301,10 @@ export function useSharing(
   useEffect(() => {
     if (isSharedSession) { isSharedRef.current = true; return; }
     if (isSharedRef.current) { isSharedRef.current = false; return; }
+    setIsGeneratingShortUrl(false);
     setShortShareUrl('');
     setShortUrlError('');
-  }, [markdown, annotations, globalAttachments, rawHtml, isSharedSession]);
+  }, [markdown, annotations, globalAttachments, rawHtml, isSharedSession, contentRevision]);
 
   /**
    * Generate a short URL via the paste service.
@@ -295,6 +317,7 @@ export function useSharing(
 
     setIsGeneratingShortUrl(true);
     setShortUrlError('');
+    const requestContext = shareRequestContext;
 
     try {
       const htmlForShare = rawHtml
@@ -308,6 +331,8 @@ export function useSharing(
         htmlForShare,
       );
 
+      if (latestShareRequestContextRef.current !== requestContext) return null;
+
       if (result) {
         setShortShareUrl(result.shortUrl);
         return result.shortUrl;
@@ -317,13 +342,14 @@ export function useSharing(
         return null;
       }
     } catch (e) {
+      if (latestShareRequestContextRef.current !== requestContext) return null;
       setShortShareUrl('');
       setShortUrlError(e instanceof Error ? e.message : 'Failed to generate short URL');
       return null;
     } finally {
-      setIsGeneratingShortUrl(false);
+      if (latestShareRequestContextRef.current === requestContext) setIsGeneratingShortUrl(false);
     }
-  }, [markdown, annotations, globalAttachments, shareBaseUrl, pasteApiUrl, rawHtml, resolveRawHtmlForShare]);
+  }, [markdown, annotations, globalAttachments, shareBaseUrl, pasteApiUrl, rawHtml, resolveRawHtmlForShare, shareRequestContext]);
 
   // Import annotations from a teammate's share URL (supports both hash-based and short /p/<id> URLs)
   const importFromShareUrl = useCallback(async (url: string): Promise<ImportResult> => {