@semiont/react-ui 0.5.10 → 0.5.12

package/src/components/resource/ResourceViewer.tsx

@@ -1,20 +1,17 @@
 'use client';
 
-import React, { useState, useEffect, useCallback, useRef, useMemo } from 'react';
+import React, { useState, useCallback, useRef, useMemo } from 'react';
 import { useTranslations } from '../../contexts/TranslationContext';
 import { AnnotateView, type SelectionMotivation, type ClickAction, type ShapeType } from './AnnotateView';
-import { BrowseView } from './BrowseView';
+import { BrowseView, type ReferenceHover } from './BrowseView';
 import { PopupContainer } from '../annotation-popups/SharedPopupElements';
 import { JsonLdView } from '../annotation-popups/JsonLdView';
-import type { Annotation, AnnotationId, ResourceDescriptor as SemiontResource, components } from '@semiont/core';
+import type { Annotation, AnnotationId, ResourceDescriptor as SemiontResource, components, EventMap, AnchorRect } from '@semiont/core';
 import { getExactText, getTargetSelector, isHighlight, isAssessment, isReference, isComment, isTag, getBodySource } from '@semiont/core';
-import { useEventSubscriptions } from '../../contexts/useEventSubscription';
-import { useSemiont } from '../../session/SemiontProvider';
-import { useObservable } from '../../hooks/useObservable';
-import { useObservableExternalNavigation } from '../../hooks/useObservableBrowse';
+import type { SemiontSession } from '@semiont/sdk';
+import { useSessionEventSubscriptions } from '../../hooks/useSessionEventSubscriptions';
 import { ANNOTATORS } from '../../lib/annotation-registry';
 import type { AnnotationsCollection } from '../../types/annotation-props';
-import { getSelectorType, getSelectedShapeForSelectorType, saveSelectedShapeForSelectorType } from '../../lib/media-shapes';
 
 /**
  * ResourceViewer - Display and interact with resource content and annotations
@@ -24,9 +21,11 @@ import { getSelectorType, getSelectedShapeForSelectorType, saveSelectedShapeForS
  * - Automatically invalidates cache when annotations change
  * - No manual refetch needed - events handle cache invalidation
  *
- * Requirements:
- * - Must be wrapped in SemiontProvider (which owns the session's event bus)
- * - Must be wrapped in CacheContext (provides cache manager)
+ * Bring-your-own-session: the `session` (SemiontSession) and the host's
+ * navigation / panel callbacks come in as props — no SemiontProvider required.
+ * Every event it subscribes to is session-scoped (mark:*, browse:click) and
+ * reaches it via `session.subscribe`. Translations fall back to built-in English
+ * when no TranslationProvider is mounted; caching flows through `session.client.browse.*`.
  *
  * Event flow:
  *   make-meaning → EventLog → SSE → EventBus → ResourceViewer → Cache invalidation
@@ -37,42 +36,86 @@ import { getSelectorType, getSelectedShapeForSelectorType, saveSelectedShapeForS
 interface Props {
   resource: SemiontResource & { content: string };
   annotations: AnnotationsCollection;
+  /** Session for the shown resource — its client mutates/invalidates, its bus feeds annotation events. */
+  session: SemiontSession | null;
+  /** Host-owned navigation: a resolved reference was followed. Omit for a view with no follow behavior. */
+  onOpenResource?: (resourceId: string) => void;
+  /** Host-owned panel control (annotation clicks open a panel). Omit for hosts without side panels. */
+  onOpenPanel?: (event: EventMap['panel:open']) => void;
+  /** A content link in the rendered content was clicked — the viewer preventDefaults and delegates; it never navigates on its own. */
+  onLinkClick?: (link: { href: string; event: React.MouseEvent }) => void;
+  /** A resolved reference span is hovered (after dwell + referent descriptor resolve); `null` on leave. Host renders its own preview. */
+  onReferenceHover?: (hover: ReferenceHover | null) => void;
+  /** Inline display variant: auto-height, no inner scroll, no pane chrome (browse path). Default: fill-the-pane. */
+  inline?: boolean;
+  /** Recently-created annotation ids to sparkle (threaded to the browse/annotate subtree). */
+  newAnnotationIds?: Set<string>;
   generatingReferenceId?: string | null;
   showLineNumbers?: boolean;
   hoverDelayMs?: number;
   hoveredAnnotationId?: string | null;
+  /**
+   * Toolbar preferences as controlled props (TOOLBAR-PREFS-AS-PROPS). Supply a value
+   * to own that pref: the instance renders it and reports intents via the callback —
+   * it never self-mutates, never persists, never listens to other instances. Omit for
+   * a plain uncontrolled default (false / 'detail' / 'linking' / 'rectangle').
+   * Hosts wanting the shared+persisted Browser UX compose `useToolbarPrefs()`.
+   */
+  annotateMode?: boolean;
+  onAnnotateModeChange?: (mode: boolean) => void;
+  clickAction?: ClickAction;
+  onClickActionChange?: (action: ClickAction) => void;
+  selectionMotivation?: SelectionMotivation | null;
+  onSelectionMotivationChange?: (motivation: SelectionMotivation | null) => void;
+  shape?: ShapeType;
+  onShapeChange?: (shape: ShapeType) => void;
+  /**
+   * Render the built-in AnnotateToolbar (default true — today's behavior,
+   * byte-identical). `false` → no bar at any internal site (browse + every
+   * annotate render mode), while every seam stays live: annotate-mode selection
+   * capture, image/pdf drawing, `mark.request` emission, and the controlled
+   * props. Tier-2 hosts compose their own controls from the controlled props;
+   * this makes that opt-out a contract instead of a CSS override.
+   */
+  showToolbar?: boolean;
 }
 
 /**
  * @emits mark:delete - User requested to delete annotation. Payload: { annotationId: string }
  * @emits panel:open - Request to open panel with annotation. Payload: { panel: string, scrollToAnnotationId?: string, motivation?: Motivation }
  *
- * @subscribes mark:mode-toggled - Toggles between browse and annotate mode. Payload: { mode: 'browse' | 'annotate' }
  * @subscribes mark:added - New annotation was added. Payload: { annotation: Annotation }
  * @subscribes mark:removed - Annotation was removed. Payload: { annotationId: string }
  * @subscribes mark:body-updated - Annotation was updated. Payload: { annotation: Annotation }
- * @subscribes mark:selection-changed - Text selection tool changed. Payload: { selection: boolean }
- * @subscribes mark:click-changed - Click annotation tool changed. Payload: { click: 'detail' | 'scroll' | null }
- * @subscribes mark:shape-changed - Drawing shape changed. Payload: { shape: string }
  * @subscribes browse:click - User clicked on annotation. Payload: { annotationId: string }
  */
 export function ResourceViewer({
   resource,
   annotations,
+  session,
+  onOpenResource,
+  onOpenPanel,
+  onLinkClick,
+  onReferenceHover,
+  inline = false,
+  newAnnotationIds,
   generatingReferenceId,
   showLineNumbers = false,
   hoverDelayMs,
-  hoveredAnnotationId: hoveredAnnotationIdProp
+  hoveredAnnotationId: hoveredAnnotationIdProp,
+  annotateMode: annotateModeProp,
+  onAnnotateModeChange,
+  clickAction: clickActionProp,
+  onClickActionChange,
+  selectionMotivation: selectionMotivationProp,
+  onSelectionMotivationChange,
+  shape: shapeProp,
+  onShapeChange,
+  showToolbar = true,
 }: Props) {
   const t = useTranslations('ResourceViewer');
   const documentViewerRef = useRef<HTMLDivElement>(null);
 
-  const browser = useSemiont();
-  const session = useObservable(browser.activeSession$);
-
-  // Get observable navigation for event-driven routing
-  const navigate = useObservableExternalNavigation();
-
   const { highlights, references, assessments, comments, tags } = annotations;
 
   // Extract resource URI once at the top - required for all annotation operations
@@ -93,25 +136,16 @@ export function ResourceViewer({
 
   const mimeType = getMimeType();
 
-  // Annotate mode state - persisted in localStorage
-  const [annotateMode, setAnnotateMode] = useState<boolean>(() => {
-    if (typeof window !== 'undefined') {
-      return localStorage.getItem('annotateMode') === 'true';
-    }
-    return false;
-  });
-
-  // Persist annotateMode to localStorage
-  useEffect(() => {
-    if (typeof window !== 'undefined') {
-      localStorage.setItem('annotateMode', annotateMode.toString());
-    }
-  }, [annotateMode]);
-
-  // Event handlers (extracted to avoid inline arrow functions)
-  const handleViewModeToggle = useCallback(() => {
-    setAnnotateMode(prev => !prev);
-  }, []);
+  // Toolbar preferences (TOOLBAR-PREFS-AS-PROPS): controlled (prop supplied) or a
+  // plain uncontrolled default. Preferences are state, not events — no localStorage
+  // and no preference bus channels here; hosts wanting the shared+persisted Browser
+  // UX compose useToolbarPrefs() (the policy layer) and pass the values down.
+  const [internalAnnotateMode, setInternalAnnotateMode] = useState(false);
+  const annotateMode = annotateModeProp ?? internalAnnotateMode;
+  const changeAnnotateMode = useCallback((mode: boolean) => {
+    if (annotateModeProp === undefined) setInternalAnnotateMode(mode);
+    onAnnotateModeChange?.(mode);
+  }, [annotateModeProp, onAnnotateModeChange]);
 
   // Determine active view based on annotate mode
   const activeView = annotateMode ? 'annotate' : 'browse';
@@ -130,74 +164,27 @@ export function ResourceViewer({
     semiont?.browse.invalidateAnnotationList(rUri);
   }, [semiont, rUri]);
 
-  // Annotation toolbar state - persisted in localStorage
-  const [selectedMotivation, setSelectedMotivation] = useState<SelectionMotivation | null>(() => {
-    if (typeof window !== 'undefined') {
-      const stored = localStorage.getItem('semiont-toolbar-selection');
-      if (stored === 'null') return null;
-      if (stored && ['linking', 'highlighting', 'assessing', 'commenting', 'tagging'].includes(stored)) {
-        return stored as SelectionMotivation;
-      }
-    }
-    return 'linking';
-  });
-
-  const [selectedClick, setSelectedClick] = useState<ClickAction>(() => {
-    if (typeof window !== 'undefined') {
-      const stored = localStorage.getItem('semiont-toolbar-click');
-      if (stored && ['detail', 'follow', 'jsonld', 'deleting'].includes(stored)) {
-        return stored as ClickAction;
-      }
-    }
-    return 'detail';
-  });
-
-  // Get selector type for current media type
-  const selectorType = getSelectorType(mimeType);
-
-  // Get selected shape for this selector type
-  const [selectedShape, setSelectedShape] = useState<ShapeType>(() => {
-    return getSelectedShapeForSelectorType(selectorType);
-  });
-
-  // Toolbar event handlers (extracted to avoid inline arrow functions)
-  const handleToolbarSelectionChanged = useCallback(({ motivation }: { motivation: string | null }) => {
-    setSelectedMotivation(motivation as SelectionMotivation | null);
-  }, []);
-
-  const handleToolbarClickChanged = useCallback(({ action }: { action: string }) => {
-    setSelectedClick(action as ClickAction);
-  }, []);
-
-  const handleToolbarShapeChanged = useCallback(({ shape }: { shape: string }) => {
-    setSelectedShape(shape as ShapeType);
-  }, []);
-
-  // Persist toolbar state to localStorage
-  useEffect(() => {
-    if (selectedMotivation === null) {
-      localStorage.setItem('semiont-toolbar-selection', 'null');
-    } else {
-      localStorage.setItem('semiont-toolbar-selection', selectedMotivation);
-    }
-  }, [selectedMotivation]);
-
-  useEffect(() => {
-    localStorage.setItem('semiont-toolbar-click', selectedClick);
-  }, [selectedClick]);
-
-  // Persist shape selection per selector type
-  useEffect(() => {
-    saveSelectedShapeForSelectorType(selectorType, selectedShape);
-  }, [selectorType, selectedShape]);
-
-  // Update selected shape when selector type changes (e.g., switching between PDF and image)
-  useEffect(() => {
-    const shapeForType = getSelectedShapeForSelectorType(selectorType);
-    if (shapeForType !== selectedShape) {
-      setSelectedShape(shapeForType);
-    }
-  }, [selectorType]);
+  // Remaining toolbar preferences — same controlled/uncontrolled split as mode.
+  const [internalSelectionMotivation, setInternalSelectionMotivation] = useState<SelectionMotivation | null>('linking');
+  const selectedMotivation = selectionMotivationProp !== undefined ? selectionMotivationProp : internalSelectionMotivation;
+  const changeSelectionMotivation = useCallback((motivation: SelectionMotivation | null) => {
+    if (selectionMotivationProp === undefined) setInternalSelectionMotivation(motivation);
+    onSelectionMotivationChange?.(motivation);
+  }, [selectionMotivationProp, onSelectionMotivationChange]);
+
+  const [internalClickAction, setInternalClickAction] = useState<ClickAction>('detail');
+  const selectedClick = clickActionProp ?? internalClickAction;
+  const changeClickAction = useCallback((action: ClickAction) => {
+    if (clickActionProp === undefined) setInternalClickAction(action);
+    onClickActionChange?.(action);
+  }, [clickActionProp, onClickActionChange]);
+
+  const [internalShape, setInternalShape] = useState<ShapeType>('rectangle');
+  const selectedShape = shapeProp ?? internalShape;
+  const changeShape = useCallback((shape: ShapeType) => {
+    if (shapeProp === undefined) setInternalShape(shape);
+    onShapeChange?.(shape);
+  }, [shapeProp, onShapeChange]);
 
   // JSON-LD view state
   const [showJsonLdView, setShowJsonLdView] = useState(false);
@@ -267,8 +254,8 @@ export function ResourceViewer({
     if (selectedClick === 'follow' && isReference(annotation)) {
       const bodySource = getBodySource(annotation.body);
       if (bodySource) {
-        // bodySource is already a bare resource ID
-        navigate(`/know/resource/${bodySource}`, { resourceId: bodySource });
+        // bodySource is already a bare resource ID — the host owns navigation
+        onOpenResource?.(bodySource);
       }
       return;
     }
@@ -293,12 +280,13 @@ export function ResourceViewer({
       setDeleteConfirmation({ annotation, position });
       return;
     }
-  }, [annotateMode, selectedClick, focusAnnotation]);
+  }, [annotateMode, selectedClick, focusAnnotation, onOpenResource]);
 
   // Annotation click coordinator - handles panel opening and scrolling
-  const handleAnnotationClickEvent = useCallback(({ annotationId, motivation }: {
+  const handleAnnotationClickEvent = useCallback(({ annotationId, motivation, anchorRect }: {
     annotationId: string;
     motivation: components['schemas']['Motivation'];
+    anchorRect?: AnchorRect;
   }) => {
     // Find the annotation metadata
     const metadata = Object.values(ANNOTATORS).find(a => a.matchesAnnotation({ motivation } as Annotation));
@@ -323,27 +311,20 @@ export function ResourceViewer({
       return;
     }
 
-    // All annotations open the unified annotations panel
-    // The panel internally switches tabs based on the motivation → tab mapping in UnifiedAnnotationsPanel
-    browser.emit('panel:open', { panel: 'annotations', scrollToAnnotationId: annotationId, motivation });
-  }, [highlights, references, assessments, comments, tags, handleAnnotationClick, selectedClick, session]);
+    // All annotations open the unified annotations panel — the host owns the panel.
+    // The panel internally switches tabs based on the motivation → tab mapping in UnifiedAnnotationsPanel.
+    // View geometry passes through untouched: the emitter owned it, the host anchors with it.
+    onOpenPanel?.({ panel: 'annotations', scrollToAnnotationId: annotationId, motivation, ...(anchorRect ? { anchorRect } : {}) });
+  }, [highlights, references, assessments, comments, tags, handleAnnotationClick, selectedClick, onOpenPanel]);
 
   // Event subscriptions - Combined into single useEventSubscriptions call to prevent hook ordering issues
   // IMPORTANT: All event subscriptions MUST be in a single call to maintain consistent hook order between renders
-  useEventSubscriptions({
-    // View mode
-    'mark:mode-toggled': handleViewModeToggle,
-
+  useSessionEventSubscriptions(session, {
     // Annotation cache invalidation
     'mark:added': handleAnnotateAdded,
     'mark:removed': handleAnnotateRemoved,
     'mark:body-updated': handleAnnotateBodyUpdated,
 
-    // Toolbar state
-    'mark:selection-changed': handleToolbarSelectionChanged,
-    'mark:click-changed': handleToolbarClickChanged,
-    'mark:shape-changed': handleToolbarShapeChanged,
-
     // Annotation clicks
     'browse:click': handleAnnotationClickEvent,
   });
@@ -370,7 +351,7 @@ export function ResourceViewer({
   }, [references]);
 
   return (
-    <div ref={documentViewerRef} className="semiont-resource-viewer">
+    <div ref={documentViewerRef} className={`semiont-resource-viewer${inline ? ' semiont-resource-viewer--inline' : ''}`}>
       {/* Content */}
       {activeView === 'annotate' ? (
         <AnnotateView
@@ -380,9 +361,9 @@ export function ResourceViewer({
           annotations={annotationsCollection}
           uiState={uiState}
           onUIStateChange={(updates) => {
-            if ('selectedMotivation' in updates) setSelectedMotivation(updates.selectedMotivation!);
-            if ('selectedClick' in updates) setSelectedClick(updates.selectedClick!);
-            if ('selectedShape' in updates) setSelectedShape(updates.selectedShape!);
+            if ('selectedMotivation' in updates) changeSelectionMotivation(updates.selectedMotivation ?? null);
+            if ('selectedClick' in updates) changeClickAction(updates.selectedClick!);
+            if ('selectedShape' in updates) changeShape(updates.selectedShape!);
           }}
           enableWidgets={true}
           getTargetResourceName={getTargetResourceName}
@@ -390,6 +371,10 @@ export function ResourceViewer({
           showLineNumbers={showLineNumbers}
           hoverDelayMs={hoverDelayMs}
           annotateMode={annotateMode}
+          onModeChange={changeAnnotateMode}
+          showToolbar={showToolbar}
+          session={session}
+          newAnnotationIds={newAnnotationIds}
         />
       ) : (
         <BrowseView
@@ -400,6 +385,14 @@ export function ResourceViewer({
           selectedClick={selectedClick}
           hoverDelayMs={hoverDelayMs}
           annotateMode={annotateMode}
+          onModeChange={changeAnnotateMode}
+          onClickActionChange={changeClickAction}
+          showToolbar={showToolbar}
+          session={session}
+          newAnnotationIds={newAnnotationIds}
+          onLinkClick={onLinkClick}
+          onReferenceHover={onReferenceHover}
+          inline={inline}
         />
       )}
 

package/src/components/resource/__tests__/AnnotateView.embeddable.test.tsx

@@ -0,0 +1,55 @@
+/**
+ * EMBEDDABLE-RESOURCE-VIEWER step 1b — AnnotateView + AnnotateToolbar provider-free.
+ *
+ * AnnotateView takes `session` + `newAnnotationIds` as props; the REAL
+ * AnnotateToolbar (not mocked — its decoupling is the crux of 1b) takes `session`
+ * as a prop. CodeMirrorRenderer is mocked (heavy; already prop-based).
+ *
+ * Started RED (tsc: no `session` prop) and GREEN once step 1b lands.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import type { SemiontSession } from '@semiont/sdk';
+import type { AnnotationUIState } from '../../../types/annotation-props';
+import { AnnotateView } from '../AnnotateView';
+
+vi.mock('../../CodeMirrorRenderer', () => ({ CodeMirrorRenderer: () => <div>cm-mock</div> }));
+
+const emptyAnnotations = { highlights: [], references: [], assessments: [], comments: [], tags: [] };
+const uiState: AnnotationUIState = {
+  selectedMotivation: 'linking',
+  selectedClick: 'detail',
+  selectedShape: 'rectangle',
+  hoveredAnnotationId: null,
+  scrollToAnnotationId: null,
+};
+
+function fakeSession(): SemiontSession {
+  return {
+    client: {
+      mark: {
+        changeSelection: vi.fn(), changeClick: vi.fn(), changeShape: vi.fn(),
+        toggleMode: vi.fn(), request: vi.fn(),
+      },
+    },
+    subscribe: () => () => {},
+  } as unknown as SemiontSession;
+}
+
+describe('AnnotateView — embeddable (session prop, no providers)', () => {
+  it('renders (incl. the real AnnotateToolbar) fed only a session, no providers', () => {
+    render(
+      <AnnotateView resourceUri="res-1"
+        content="hello"
+        mimeType="text/plain"
+        annotations={emptyAnnotations}
+        uiState={uiState}
+        annotateMode={true}
+        session={fakeSession()}
+      />,
+    );
+    // The tree (real AnnotateToolbar + mocked CodeMirror) rendered without a provider.
+    expect(screen.getByText('cm-mock')).toBeInTheDocument();
+  });
+});

package/src/components/resource/__tests__/BrowseView.embeddable.test.tsx

@@ -0,0 +1,49 @@
+/**
+ * EMBEDDABLE-RESOURCE-VIEWER step 1a — BrowseView renders provider-free.
+ *
+ * BrowseView takes its `session` + `newAnnotationIds` as props (not
+ * `useSemiont()` / `useResourceAnnotations()`), and subscribes to session-scoped
+ * beckon events via `session.subscribe`. `AnnotateToolbar` is mocked here — its
+ * own provider decoupling is step 1b — so this spec isolates BrowseView's body.
+ *
+ * Started RED (tsc: no `session` prop) and GREEN once step 1a lands.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import type { SemiontSession } from '@semiont/sdk';
+import { BrowseView } from '../BrowseView';
+
+// AnnotateToolbar still calls useSemiont() (step 1b) — stub it out so this spec
+// exercises only BrowseView's own provider-freedom.
+vi.mock('../../annotation/AnnotateToolbar', () => ({ AnnotateToolbar: () => null }));
+vi.mock('react-markdown', () => ({ default: ({ children }: { children: string }) => <div>{children}</div> }));
+vi.mock('remark-gfm', () => ({ default: () => ({}) }));
+
+const emptyAnnotations = { highlights: [], references: [], assessments: [], comments: [], tags: [] };
+
+function fakeSession(): SemiontSession {
+  return {
+    client: {
+      browse: { click: vi.fn() },
+      beckon: { hover: vi.fn() },
+    },
+    subscribe: () => () => {},
+  } as unknown as SemiontSession;
+}
+
+describe('BrowseView — embeddable (session prop, no providers)', () => {
+  it('renders content fed only a session, with NO providers mounted', () => {
+    render(
+      <BrowseView
+        content="Embeddable browse content."
+        mimeType="text/plain"
+        resourceUri="res-1"
+        annotations={emptyAnnotations}
+        annotateMode={false}
+        session={fakeSession()}
+      />,
+    );
+    expect(screen.getByText('Embeddable browse content.')).toBeInTheDocument();
+  });
+});

package/src/components/resource/__tests__/BrowseView.links.test.tsx

@@ -0,0 +1,60 @@
+/**
+ * EMBEDDABLE-VIEWER-COMPLETION Phase 2 — content-link delegation.
+ *
+ * A content link (`<a href>` rendered inside the resource content) must be
+ * intercepted: the viewer `preventDefault`s (never navigates on its own — an
+ * embedded/Electron security requirement) and delegates to `onLinkClick({href,
+ * event})`. With no handler, the click is still cancelled (nothing happens).
+ *
+ * Started RED (no `onLinkClick` prop) and GREEN once Phase 2 lands. Real
+ * react-markdown (not the mock) so the `<a>` is a genuine rendered content link.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import type { SemiontSession } from '@semiont/sdk';
+import { BrowseView } from '../BrowseView';
+
+vi.mock('../../annotation/AnnotateToolbar', () => ({ AnnotateToolbar: () => null }));
+
+const emptyAnnotations = { highlights: [], references: [], assessments: [], comments: [], tags: [] };
+
+function fakeSession(): SemiontSession {
+  return {
+    client: { browse: { click: vi.fn() }, beckon: { hover: vi.fn() } },
+    subscribe: () => () => {},
+  } as unknown as SemiontSession;
+}
+
+const MD = 'see [the link](https://example.test/x) here';
+
+describe('BrowseView — content link delegation (Phase 2)', () => {
+  it('intercepts a content <a> click: preventDefault + onLinkClick(href)', () => {
+    const onLinkClick = vi.fn();
+    render(
+      <BrowseView
+        content={MD} mimeType="text/markdown" resourceUri="res-1"
+        annotations={emptyAnnotations} annotateMode={false}
+        session={fakeSession()} onLinkClick={onLinkClick}
+      />,
+    );
+    const anchor = screen.getByText('the link').closest('a')!;
+    // fireEvent.click returns false when the event was cancelled (preventDefault).
+    const notCancelled = fireEvent.click(anchor);
+    expect(notCancelled).toBe(false); // navigation blocked
+    expect(onLinkClick).toHaveBeenCalledTimes(1);
+    expect(onLinkClick.mock.calls[0]![0]).toMatchObject({ href: 'https://example.test/x' });
+  });
+
+  it('blocks navigation even with no handler (never navigates on its own)', () => {
+    render(
+      <BrowseView
+        content={MD} mimeType="text/markdown" resourceUri="res-1"
+        annotations={emptyAnnotations} annotateMode={false}
+        session={fakeSession()}
+      />,
+    );
+    const anchor = screen.getByText('the link').closest('a')!;
+    expect(fireEvent.click(anchor)).toBe(false); // still cancelled — nothing happens, but no navigation
+  });
+});

package/src/components/resource/__tests__/BrowseView.overlay-async.test.tsx

@@ -0,0 +1,113 @@
+/**
+ * BUG: browse-view-overlay-misses-async-content — the overlay effect must be
+ * keyed on everything it reads: the rendered content DOM AND the annotations.
+ *
+ * When annotations arrive BEFORE content (any host loading content async —
+ * useResourceContent), the overlay resolved ranges against the empty document
+ * and never re-ran when content landed: rendered text, ZERO spans, healed only
+ * by a remount. When content arrives first (sync-content hosts), it worked by
+ * accident of ordering. Both orders are pinned here, plus shrink-to-zero.
+ *
+ * REAL overlay pipeline (no annotation-overlay mocks) — react-markdown is
+ * mocked to identity, so the source→rendered offset map is 1:1 and spans
+ * paint in jsdom via the actual Range/surroundContents path.
+ *
+ * Started RED (async order → 0 spans) → GREEN with the single keyed effect.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import type { SemiontSession } from '@semiont/sdk';
+import type { Annotation, AnnotationId } from '@semiont/core';
+import { BrowseView } from '../BrowseView';
+
+vi.mock('../../annotation/AnnotateToolbar', () => ({ AnnotateToolbar: () => null }));
+vi.mock('react-markdown', () => ({ default: ({ children }: { children: string }) => <div>{children}</div> }));
+vi.mock('remark-gfm', () => ({ default: () => ({}) }));
+
+const CONTENT = 'hello world selectme end';
+
+function fakeSession(): SemiontSession {
+  return {
+    client: { browse: { click: vi.fn() }, beckon: { hover: vi.fn() } },
+    subscribe: () => () => {},
+  } as unknown as SemiontSession;
+}
+
+/** A resolved reference over "world" (offsets 6..11) — real W3C shape. */
+function referenceOnWorld(): Annotation {
+  return {
+    '@context': 'http://www.w3.org/ns/anno.jsonld',
+    id: 'ref-world' as AnnotationId,
+    type: 'Annotation',
+    motivation: 'linking',
+    creator: { '@type': 'Person', name: 'user@example.com' },
+    created: '2026-07-10T00:00:00Z',
+    target: {
+      source: 'res-1',
+      selector: { type: 'TextPositionSelector', start: 6, end: 11 },
+    },
+  } as unknown as Annotation;
+}
+
+const emptyAnnotations = { highlights: [], references: [], assessments: [], comments: [], tags: [] };
+const withReference = { ...emptyAnnotations, references: [referenceOnWorld()] };
+
+const baseProps = {
+  mimeType: 'text/plain',
+  resourceUri: 'res-1',
+  annotateMode: false,
+};
+
+const spans = (c: HTMLElement) => c.querySelectorAll('[data-annotation-id]');
+
+describe('BrowseView — overlay vs async content arrival', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('paints spans when content arrives AFTER annotations (the async-content bug)', () => {
+    const session = fakeSession();
+    const { container, rerender } = render(
+      <BrowseView {...baseProps} content="" annotations={withReference} session={session} />,
+    );
+    expect(spans(container)).toHaveLength(0); // nothing to anchor on yet
+
+    // Content lands (useResourceContent resolved) — annotations unchanged.
+    rerender(
+      <BrowseView {...baseProps} content={CONTENT} annotations={withReference} session={session} />,
+    );
+
+    expect(spans(container)).toHaveLength(1);
+    expect(spans(container)[0]!.textContent).toBe('world');
+    expect(spans(container)[0]!.getAttribute('data-annotation-type')).toBe('reference');
+  });
+
+  it('paints spans when annotations arrive AFTER content (the always-working order — pinned)', () => {
+    const session = fakeSession();
+    const { container, rerender } = render(
+      <BrowseView {...baseProps} content={CONTENT} annotations={emptyAnnotations} session={session} />,
+    );
+    expect(spans(container)).toHaveLength(0);
+
+    rerender(
+      <BrowseView {...baseProps} content={CONTENT} annotations={withReference} session={session} />,
+    );
+
+    expect(spans(container)).toHaveLength(1);
+    expect(spans(container)[0]!.textContent).toBe('world');
+  });
+
+  it('clears spans when annotations shrink to zero', () => {
+    const session = fakeSession();
+    const { container, rerender } = render(
+      <BrowseView {...baseProps} content={CONTENT} annotations={withReference} session={session} />,
+    );
+    expect(spans(container)).toHaveLength(1);
+
+    rerender(
+      <BrowseView {...baseProps} content={CONTENT} annotations={emptyAnnotations} session={session} />,
+    );
+
+    expect(spans(container)).toHaveLength(0);
+    expect(container.textContent).toContain(CONTENT); // text restored intact
+  });
+});