@semiont/react-ui 0.5.22 → 0.5.24

package/src/components/resource/ResourceViewer.tsx

@@ -3,7 +3,9 @@
 import React, { useState, useCallback, useRef, useMemo } from 'react';
 import { useTranslations } from '../../contexts/TranslationContext';
 import { AnnotateView, type SelectionMotivation, type ClickAction, type ShapeType } from './AnnotateView';
+import type { AnnotateMediaRenderers } from './annotate-renderers';
 import { BrowseView, type ReferenceHover } from './BrowseView';
+import type { BrowseMediaRenderers } from './browse-renderers';
 import { PopupContainer } from '../annotation-popups/SharedPopupElements';
 import { JsonLdView } from '../annotation-popups/JsonLdView';
 import type { Annotation, AnnotationId, ResourceDescriptor as SemiontResource, components, EventMap, AnchorRect } from '@semiont/core';
@@ -16,19 +18,21 @@ import type { AnnotationsCollection } from '../../types/annotation-props';
 /**
  * ResourceViewer - Display and interact with resource content and annotations
  *
- * This component uses event-driven architecture for real-time updates:
- * - Subscribes to make-meaning events (mark:added, mark:removed, mark:body-updated)
- * - Automatically invalidates cache when annotations change
- * - No manual refetch needed - events handle cache invalidation
+ * Real-time updates arrive through the sdk, not through this component:
+ * the client's BrowseNamespace invalidates the right resource's annotation
+ * list on mark:added/mark:removed (payload-keyed) and patches
+ * mark:body-updated in place, so the live queries feeding `annotations`
+ * refresh on their own. The viewer subscribes only to `browse:click`
+ * (annotation-click routing).
  *
  * 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.*`.
+ * Every event it subscribes to is session-scoped 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
+ *   make-meaning → EventLog → SSE → EventBus → sdk cache invalidation → live queries
  */
 interface Props {
   resource: SemiontResource & { content: string };
@@ -75,6 +79,22 @@ interface Props {
    * this makes that opt-out a contract instead of a CSS override.
    */
   showToolbar?: boolean;
+  /**
+   * Override the read-only / annotating media renderers respectively; each is
+   * merged over its defaults by the view below.
+   *
+   * Two flat props rather than one nested object: the registries are
+   * separately typed (`MediaRendererProps` vs `AnnotateMediaRendererProps`)
+   * and nesting them would imply an interchangeability that does not exist.
+   *
+   * Forwarding them is what makes the registries reachable at all for a host
+   * that imports `ResourceViewer` — the documented entry point. Before this,
+   * reaching `BrowseView`'s `renderers` meant dropping to `BrowseView`
+   * directly and reimplementing the browse/annotate switching this component
+   * exists to provide. See .plans/ANNOTATE-RENDERER-REGISTRY.md (D5)
+   */
+  browseRenderers?: BrowseMediaRenderers;
+  annotateRenderers?: AnnotateMediaRenderers;
 }
 
 /**
@@ -82,9 +102,6 @@ interface Props {
  * panel opening invokes the host's `onOpenPanel` callback — the host owns
  * the panel and any `panel:open` emission.
  *
- * @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 browse:click - User clicked on annotation. Payload: { annotationId: string, motivation, anchorRect? }
  */
 export function ResourceViewer({
@@ -110,6 +127,8 @@ export function ResourceViewer({
   shape: shapeProp,
   onShapeChange,
   showToolbar = true,
+  browseRenderers,
+  annotateRenderers,
 }: Props) {
   const t = useTranslations('ResourceViewer');
   const documentViewerRef = useRef<HTMLDivElement>(null);
@@ -140,12 +159,13 @@ export function ResourceViewer({
   // Determine active view based on annotate mode
   const activeView = annotateMode ? 'annotate' : 'browse';
 
-  const semiont = session?.client;
-
-  // One invalidation for every annotation mutation event (added/removed/body-updated).
-  const handleAnnotationsChanged = useCallback(() => {
-    semiont?.browse.invalidateAnnotationList(rUri);
-  }, [semiont, rUri]);
+  // NOTE deliberately NO mark:* invalidation here (MULTI-RESOURCE-SCOPE
+  // Step 5). The sdk's BrowseNamespace already invalidates the RIGHT
+  // resource's annotation list on mark:added/mark:removed (payload-keyed,
+  // once per event) and patches mark:body-updated in place. A viewer-side
+  // handler on these session-wide channels was pure duplication — and with
+  // N viewers on one session (the embeddable resource-per-chat-message
+  // pattern), an O(N) refetch amplification on every mark event.
 
   // Remaining toolbar preferences — same controlled/uncontrolled split as mode.
   const [internalSelectionMotivation, setInternalSelectionMotivation] = useState<SelectionMotivation | null>('linking');
@@ -286,11 +306,6 @@ export function ResourceViewer({
 
   // Single subscription call per file (see scripts/compliance/audit-hooks-ordering.ts).
   useSessionEventSubscriptions(session, {
-    // Annotation cache invalidation
-    'mark:added': handleAnnotationsChanged,
-    'mark:removed': handleAnnotationsChanged,
-    'mark:body-updated': handleAnnotationsChanged,
-
     // Annotation clicks
     'browse:click': handleAnnotationClickEvent,
   });
@@ -343,6 +358,7 @@ export function ResourceViewer({
           showToolbar={showToolbar}
           session={session}
           newAnnotationIds={newAnnotationIds}
+          {...(annotateRenderers && { renderers: annotateRenderers })}
         />
       ) : (
         <BrowseView
@@ -361,6 +377,7 @@ export function ResourceViewer({
           onLinkClick={onLinkClick}
           onReferenceHover={onReferenceHover}
           inline={inline}
+          {...(browseRenderers && { renderers: browseRenderers })}
         />
       )}
 

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

@@ -0,0 +1,114 @@
+/**
+ * ANNOTATE-RENDERER-REGISTRY — the annotate path's overridable media registry,
+ * symmetric to EMBEDDABLE-RESOURCE-VIEWER step 3's browse registry.
+ *
+ * A host that brings its own PDF stack can already replace the read-only
+ * renderer via `BrowseView`'s `renderers` prop; without the same seam here it
+ * ends up running two PDF engines depending on which mode the user is in.
+ *
+ * Started RED (tsc: no `renderers` prop on AnnotateView).
+ * See .plans/ANNOTATE-RENDERER-REGISTRY.md
+ */
+import React from 'react';
+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';
+import type { AnnotateMediaRendererProps } from '../annotate-renderers';
+
+vi.mock('../../annotation/AnnotateToolbar', () => ({ AnnotateToolbar: () => null }));
+vi.mock('../../CodeMirrorRenderer', () => ({
+  CodeMirrorRenderer: () => <div data-testid="default-text">default-cm</div>,
+}));
+vi.mock('../../image-annotation/SvgDrawingCanvas', () => ({
+  SvgDrawingCanvas: () => <div data-testid="default-image">default-svg</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;
+}
+
+type ViewProps = React.ComponentProps<typeof AnnotateView>;
+
+const base = (mimeType: string): ViewProps => ({
+  resourceUri: 'res-1',
+  content: 'the-body',
+  mimeType,
+  annotations: emptyAnnotations,
+  uiState,
+  annotateMode: true,
+  session: fakeSession(),
+});
+
+describe('AnnotateView — media-renderer registry', () => {
+  it('uses a custom text renderer from the `renderers` override', () => {
+    const CustomText = ({ content }: AnnotateMediaRendererProps) => (
+      <div data-testid="custom-text">custom: {content}</div>
+    );
+
+    render(<AnnotateView {...base('text/plain')} renderers={{ text: CustomText }} />);
+
+    expect(screen.getByTestId('custom-text')).toHaveTextContent('custom: the-body');
+    expect(screen.queryByTestId('default-text')).not.toBeInTheDocument();
+  });
+
+  it('uses a custom pdf renderer — the realistic override, a host bringing its own viewer', () => {
+    const CustomPdf = ({ content }: AnnotateMediaRendererProps) => (
+      <div data-testid="custom-pdf">{content}</div>
+    );
+
+    render(<AnnotateView {...base('application/pdf')} renderers={{ pdf: CustomPdf }} />);
+
+    expect(screen.getByTestId('custom-pdf')).toBeInTheDocument();
+  });
+
+  it('merges over the defaults rather than replacing them: overriding text leaves image alone', () => {
+    const CustomText = () => <div data-testid="custom-text" />;
+
+    render(<AnnotateView {...base('image/png')} renderers={{ text: CustomText }} />);
+
+    expect(screen.getByTestId('default-image')).toBeInTheDocument();
+    expect(screen.queryByTestId('custom-text')).not.toBeInTheDocument();
+  });
+
+  it('a mode in neither the defaults nor the override falls back to unsupported, download intact', () => {
+    // Deliberately unlike the browse side, where a registry miss falls through
+    // to the text renderer harmlessly. Annotating an unknown type is not
+    // harmless, so the miss must stay explicit.
+    const { container } = render(<AnnotateView {...base('application/octet-stream')} />);
+
+    expect(container.querySelector('[data-mime-type="unsupported"]')).toBeInTheDocument();
+    expect(screen.getByText(/Annotation not supported/)).toBeInTheDocument();
+    expect(screen.getByText('Download File')).toBeInTheDocument();
+  });
+
+  it('renders one toolbar and one content shell, whatever the render mode', () => {
+    // The collapse this plan is really about: three branches used to repeat
+    // the wrapper, the toolbar block and the content div verbatim.
+    for (const mimeType of ['text/plain', 'application/pdf', 'image/png']) {
+      const { container, unmount } = render(<AnnotateView {...base(mimeType)} />);
+      expect(container.querySelectorAll('.semiont-annotate-view')).toHaveLength(1);
+      expect(container.querySelectorAll('.semiont-annotate-view__content')).toHaveLength(1);
+      unmount();
+    }
+  });
+});

package/src/components/resource/__tests__/AnnotationHistory.test.tsx

@@ -4,8 +4,6 @@ import { screen } from '@testing-library/react';
 import '@testing-library/jest-dom';
 import { AnnotationHistory } from '../AnnotationHistory';
 import { renderWithProviders } from '../../../test-utils';
-import type { ResourceId } from '@semiont/core';
-import { BehaviorSubject } from 'rxjs';
 
 // Mock @semiont/core - must use importOriginal to preserve EventBus etc.
 vi.mock('@semiont/core', async (importOriginal) => {
@@ -22,33 +20,14 @@ vi.mock('../../../contexts/TranslationContext', () => ({
     const translations: Record<string, string> = {
       history: 'History',
       loading: 'Loading...',
+      failed: 'Could not load history.',
+      retry: 'Try again',
     };
     return translations[key] || key;
   }),
   TranslationProvider: ({ children }: { children: React.ReactNode }) => children,
 }));
 
-const eventsSubject = new BehaviorSubject<any[] | undefined>(undefined);
-const annotationsSubject = new BehaviorSubject<any[] | undefined>(undefined);
-
-const stableMockClient = {
-  browse: {
-    events: () => eventsSubject.asObservable(),
-    annotations: () => annotationsSubject.asObservable(),
-  },
-};
-const stableMockSession = { client: stableMockClient };
-const stableActiveSession$ = new BehaviorSubject<any>(stableMockSession);
-const stableMockBrowser = { activeSession$: stableActiveSession$ };
-
-vi.mock('../../../session/SemiontProvider', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('../../../session/SemiontProvider')>();
-  return {
-    ...actual,
-    useSemiont: () => stableMockBrowser,
-  };
-});
-
 // Mock HistoryEvent to avoid deep rendering and mocking all its dependencies
 const MockHistoryEvent = vi.fn(({ event }: any) => (
   <div data-testid={`history-event-${event.id}`}>
@@ -63,8 +42,6 @@ vi.mock('../HistoryEvent', () => ({
 import { getAnnotationUriFromEvent } from '@semiont/core';
 const mockGetAnnotationUri = getAnnotationUriFromEvent as ReturnType<typeof vi.fn>;
 
-const testRId = 'res-1' as ResourceId;
-
 /** Returns flat StoredEventResponse shape (matches API response) */
 function makeStoredEvent(id: string, type: string, seq: number, overrides: Record<string, any> = {}): any {
   return {
@@ -91,16 +68,13 @@ describe('AnnotationHistory', () => {
   beforeEach(() => {
     vi.clearAllMocks();
     mockGetAnnotationUri.mockReturnValue(null);
-    eventsSubject.next(undefined);
-    annotationsSubject.next([]);
   });
 
   it('renders loading state', () => {
-    eventsSubject.next(undefined);
-
     renderWithProviders(
       <AnnotationHistory
-        rUri={testRId}
+        events={[]}
+        eventsLoading
         Link={MockLink}
         routes={mockRoutes}
       />
@@ -110,12 +84,64 @@ describe('AnnotationHistory', () => {
     expect(screen.getByText('Loading...')).toBeInTheDocument();
   });
 
-  it('renders null when no events', () => {
-    eventsSubject.next([]);
+  describe('terminal load failure', () => {
+    // The panel used to derive `loading` from `eventsData === undefined` and
+    // hard-code `const error = false`, so a failed load sat on "Loading..."
+    // for ever and the error branch below it was unreachable.
+    // See .plans/PANEL-FAILURE-STATES.md
+
+    it('reports the failure instead of staying on the loading text', () => {
+      renderWithProviders(
+        <AnnotationHistory
+          events={[]}
+          eventsLoading={false}
+          eventsError={new Error('Resource not found')}
+          Link={MockLink}
+          routes={mockRoutes}
+        />
+      );
+
+      expect(screen.queryByText('Loading...')).not.toBeInTheDocument();
+      expect(screen.getByText('Could not load history.')).toBeInTheDocument();
+    });
+
+    it('offers a retry that calls back', async () => {
+      const onRetryEvents = vi.fn();
+      const { default: userEvent } = await import('@testing-library/user-event');
+
+      renderWithProviders(
+        <AnnotationHistory
+          events={[]}
+          eventsError={new Error('boom')}
+          onRetryEvents={onRetryEvents}
+          Link={MockLink}
+          routes={mockRoutes}
+        />
+      );
+
+      await userEvent.click(screen.getByRole('button', { name: 'Try again' }));
+      expect(onRetryEvents).toHaveBeenCalledTimes(1);
+    });
+
+    it('the failure beats the loading state — a dead request is not still loading', () => {
+      renderWithProviders(
+        <AnnotationHistory
+          events={[]}
+          eventsLoading
+          eventsError={new Error('boom')}
+          Link={MockLink}
+          routes={mockRoutes}
+        />
+      );
+
+      expect(screen.getByText('Could not load history.')).toBeInTheDocument();
+    });
+  });
 
+  it('renders null when no events', () => {
     const { container } = renderWithProviders(
       <AnnotationHistory
-        rUri={testRId}
+        events={[]}
         Link={MockLink}
         routes={mockRoutes}
       />
@@ -130,11 +156,10 @@ describe('AnnotationHistory', () => {
       makeStoredEvent('e1', 'mark:added', 1),
       makeStoredEvent('e2', 'mark:added', 2),
     ];
-    eventsSubject.next(events);
 
     renderWithProviders(
       <AnnotationHistory
-        rUri={testRId}
+        events={events}
         Link={MockLink}
         routes={mockRoutes}
       />
@@ -155,11 +180,10 @@ describe('AnnotationHistory', () => {
       makeStoredEvent('e4', 'job:completed', 4),
       makeStoredEvent('e5', 'mark:body-updated', 5),
     ];
-    eventsSubject.next(events);
 
     renderWithProviders(
       <AnnotationHistory
-        rUri={testRId}
+        events={events}
         Link={MockLink}
         routes={mockRoutes}
       />
@@ -173,12 +197,11 @@ describe('AnnotationHistory', () => {
 
   it('passes isRelated when hovered annotation matches event', () => {
     const events = [makeStoredEvent('e1', 'mark:added', 1)];
-    eventsSubject.next(events);
     mockGetAnnotationUri.mockReturnValue('ann-1');
 
     renderWithProviders(
       <AnnotationHistory
-        rUri={testRId}
+        events={events}
         hoveredAnnotationId="ann-1"
         Link={MockLink}
         routes={mockRoutes}
@@ -192,11 +215,10 @@ describe('AnnotationHistory', () => {
 
   it('renders history panel structure with title and list', () => {
     const events = [makeStoredEvent('e1', 'mark:added', 1)];
-    eventsSubject.next(events);
 
     const { container } = renderWithProviders(
       <AnnotationHistory
-        rUri={testRId}
+        events={events}
         Link={MockLink}
         routes={mockRoutes}
       />

package/src/components/resource/__tests__/BrowseView.reference-hover.test.tsx

@@ -13,6 +13,7 @@
  * `browse.resource` observable so the test controls resolve timing.
  */
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { asStates } from '../../../__tests__/test-client';
 import { render, fireEvent } from '@testing-library/react';
 import '@testing-library/jest-dom';
 import { BehaviorSubject } from 'rxjs';
@@ -53,7 +54,7 @@ const stubRef = makeAnnotation('ref-stub', []);
 function setup(onReferenceHover?: (h: unknown) => void) {
   const referent$ = new BehaviorSubject<ResourceDescriptor | undefined>(undefined);
   const beckonHover = vi.fn();
-  const browseResource = vi.fn(() => referent$);
+  const browseResource = vi.fn(() => asStates(referent$));
   const session = {
     client: {
       browse: { click: vi.fn(), resource: browseResource },

package/src/components/resource/__tests__/ResourceViewer.multi-mount-invalidation.test.tsx

@@ -0,0 +1,140 @@
+/**
+ * MULTI-RESOURCE-SCOPE Step 5 — the multi-mount invalidation contract.
+ *
+ * With N viewers mounted on one session (the embeddable "resource per chat
+ * message" pattern — 40–60 concurrent in the surveyed consumer), a mark
+ * event must cost ONE invalidation, of the right resource's list — not N.
+ *
+ * The invalidation belongs to the sdk: `BrowseNamespace.subscribeToEvents`
+ * already invalidates payload-keyed on mark:added/mark:removed and patches
+ * mark:body-updated in place. `ResourceViewer` therefore subscribes to NO
+ * mark:* channels at all — a viewer-side handler was pure duplication, and
+ * unfiltered it was an O(N) refetch amplification. This suite pins the
+ * system behavior over the real client with two mounted viewers:
+ * exactly one list invalidation per mark event, zero for body updates.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { render, act, waitFor } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import type { ResourceDescriptor as SemiontResource, ResourceId, StoredEvent, EventOfType, UserId, EventMetadata, Annotation } from '@semiont/core';
+import { annotationId, resourceId as makeResourceId } from '@semiont/core';
+import { createTestSemiontWrapper } from '../../../test-utils';
+import { ResourceViewer } from '../ResourceViewer';
+
+const TEST_USER = 'did:web:test:users:test' as UserId;
+
+function makeResource(id: string): SemiontResource & { content: string } {
+  return {
+    '@context': 'https://www.w3.org/ns/activitystreams',
+    '@id': id as ResourceId,
+    name: `Doc ${id}`,
+    created: '2024-01-01T00:00:00Z',
+    entityTypes: [],
+    archived: false,
+    representations: [{ mediaType: 'text/plain', byteSize: 10 }],
+    content: `Content of ${id}.`,
+  };
+}
+
+function mockAnnotation(rIdStr: string): Annotation {
+  return {
+    '@context': 'http://www.w3.org/ns/anno.jsonld',
+    type: 'Annotation',
+    id: annotationId('ann-1'),
+    motivation: 'commenting',
+    created: '2026-01-01T00:00:00Z',
+    target: { source: rIdStr },
+    body: [{ type: 'TextualBody', value: 'c', purpose: 'commenting' }],
+  };
+}
+
+function fakeMarkAdded(rIdStr: string): StoredEvent<EventOfType<'mark:added'>> {
+  return {
+    id: 'evt-1',
+    type: 'mark:added',
+    resourceId: makeResourceId(rIdStr),
+    userId: TEST_USER,
+    version: 1,
+    timestamp: '2026-01-01T00:00:00Z',
+    payload: { annotation: mockAnnotation(rIdStr) },
+    metadata: { sequenceNumber: 1 } as EventMetadata,
+  };
+}
+
+const annotations = { highlights: [], references: [], assessments: [], comments: [], tags: [] };
+
+function mountTwoViewers() {
+  const wrapper = createTestSemiontWrapper();
+  const spy = vi.spyOn(wrapper.client.browse, 'invalidateAnnotationList');
+  render(
+    <>
+      <ResourceViewer
+        session={wrapper.session}
+        resource={makeResource('res-A')}
+        annotations={annotations}
+        onOpenResource={vi.fn()}
+        onOpenPanel={vi.fn()}
+      />
+      <ResourceViewer
+        session={wrapper.session}
+        resource={makeResource('res-B')}
+        annotations={annotations}
+        onOpenResource={vi.fn()}
+        onOpenPanel={vi.fn()}
+      />
+    </>,
+  );
+  spy.mockClear(); // only the event-driven invalidations count
+  return { ...wrapper, spy };
+}
+
+const flush = () => act(() => new Promise<void>((r) => setTimeout(r, 0)));
+
+describe('ResourceViewer — multi-mount invalidation is per-resource and O(1), not O(N)', () => {
+  it("a mark:added for res-A costs exactly ONE invalidation — res-A's, from the sdk", async () => {
+    const { eventBus, spy } = mountTwoViewers();
+
+    act(() => {
+      eventBus.get('mark:added').next(fakeMarkAdded('res-A'));
+    });
+
+    await waitFor(() => expect(spy).toHaveBeenCalledWith('res-A'));
+    expect(spy).not.toHaveBeenCalledWith('res-B');
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  it("a mark:removed for res-B costs exactly ONE invalidation — res-B's", async () => {
+    const { eventBus, spy } = mountTwoViewers();
+
+    act(() => {
+      eventBus.get('mark:removed').next({
+        id: 'evt-2',
+        type: 'mark:removed',
+        resourceId: makeResourceId('res-B'),
+        userId: TEST_USER,
+        version: 1,
+        timestamp: '2026-01-01T00:00:00Z',
+        payload: { annotationId: annotationId('ann-1') },
+        metadata: { sequenceNumber: 2 } as EventMetadata,
+      });
+    });
+
+    await waitFor(() => expect(spy).toHaveBeenCalledWith('res-B'));
+    expect(spy).not.toHaveBeenCalledWith('res-A');
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  it('a mark:body-updated costs ZERO list invalidations — the sdk patches in place', async () => {
+    const { eventBus, spy } = mountTwoViewers();
+
+    act(() => {
+      eventBus.get('mark:body-updated').next({
+        resourceId: makeResourceId('res-A'),
+        annotation: mockAnnotation('res-A'),
+      } as never);
+    });
+    await flush();
+
+    expect(spy).not.toHaveBeenCalled();
+  });
+});

package/src/components/resource/__tests__/ResourceViewer.registry.test.tsx

@@ -0,0 +1,89 @@
+/**
+ * The media-renderer registries must be reachable through `ResourceViewer` —
+ * the documented consumer entry point.
+ *
+ * `BrowseView` has taken a `renderers` override since EMBEDDABLE-RESOURCE-VIEWER
+ * step 3, and `AnnotateView` since 3b, but `ResourceViewer` forwarded neither.
+ * A host importing it (what docs/ANNOTATIONS.md tells consumers to do, and what
+ * the embeddable-surface packaging gate checks) therefore had no way to reach
+ * the extension point: it would have to drop to `BrowseView` directly and
+ * reimplement the browse/annotate switching `ResourceViewer` exists to provide.
+ *
+ * Started RED (tsc: no `browseRenderers` / `annotateRenderers` props).
+ * See .plans/ANNOTATE-RENDERER-REGISTRY.md (D5)
+ */
+import React from 'react';
+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 { ResourceViewer } from '../ResourceViewer';
+import type { MediaRendererProps } from '../browse-renderers';
+import type { AnnotateMediaRendererProps } from '../annotate-renderers';
+
+vi.mock('../../annotation/AnnotateToolbar', () => ({ AnnotateToolbar: () => null }));
+vi.mock('../../Toolbar', () => ({ Toolbar: () => null }));
+vi.mock('../../CodeMirrorRenderer', () => ({
+  CodeMirrorRenderer: () => <div data-testid="default-text">default-cm</div>,
+}));
+
+function fakeSession(): SemiontSession {
+  return {
+    client: {
+      browse: { click: vi.fn() },
+      beckon: { hover: vi.fn() },
+      mark: {
+        changeSelection: vi.fn(), changeClick: vi.fn(), changeShape: vi.fn(),
+        toggleMode: vi.fn(), request: vi.fn(),
+      },
+    },
+    subscribe: () => () => {},
+  } as unknown as SemiontSession;
+}
+
+type ViewerProps = React.ComponentProps<typeof ResourceViewer>;
+
+const emptyAnnotations = { highlights: [], references: [], assessments: [], comments: [], tags: [] };
+
+const base = (): ViewerProps => ({
+  resource: {
+    '@id': 'res-1',
+    name: 'Doc',
+    content: 'the-body',
+    representations: [{ mediaType: 'text/plain' }],
+  },
+  annotations: emptyAnnotations,
+  session: fakeSession(),
+} as unknown as ViewerProps);
+
+describe('ResourceViewer — media-renderer registries are reachable', () => {
+  it('forwards browseRenderers to the read-only path', () => {
+    const CustomText = ({ content }: MediaRendererProps) => (
+      <div data-testid="custom-browse">{content}</div>
+    );
+
+    render(<ResourceViewer {...base()} annotateMode={false} browseRenderers={{ text: CustomText }} />);
+
+    expect(screen.getByTestId('custom-browse')).toHaveTextContent('the-body');
+  });
+
+  it('forwards annotateRenderers to the annotating path', () => {
+    const CustomText = ({ content }: AnnotateMediaRendererProps) => (
+      <div data-testid="custom-annotate">{content}</div>
+    );
+
+    render(<ResourceViewer {...base()} annotateMode annotateRenderers={{ text: CustomText }} />);
+
+    expect(screen.getByTestId('custom-annotate')).toHaveTextContent('the-body');
+    expect(screen.queryByTestId('default-text')).not.toBeInTheDocument();
+  });
+
+  it('without overrides the defaults still render, in both modes', () => {
+    const { unmount } = render(<ResourceViewer {...base()} annotateMode />);
+    expect(screen.getByTestId('default-text')).toBeInTheDocument();
+    unmount();
+
+    render(<ResourceViewer {...base()} annotateMode={false} />);
+    expect(screen.getByText(/the-body/)).toBeInTheDocument();
+  });
+});