@semiont/react-ui 0.5.10 → 0.5.12

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

@@ -0,0 +1,161 @@
+/**
+ * EMBEDDABLE-VIEWER-COMPLETION Phase 2b — `onReferenceHover`.
+ *
+ * Hovering a RESOLVED reference span fires `onReferenceHover({annotation,
+ * referent, anchorRect})` once — after the viewer's dwell AND the referent's
+ * cached descriptor resolves. A stub fires nothing (not even null); leaving
+ * before the descriptor resolves cancels (no fire, and no stray null); leaving
+ * after a fire sends `null`; the beckon:hover panel-highlight emit is untouched.
+ *
+ * Started RED (no `onReferenceHover` prop) and GREEN once Phase 2b lands.
+ * Test mechanics mirror BrowseView.test.tsx: mock target with `closest()`,
+ * fake timers for the dwell, a BehaviorSubject standing in for the cached
+ * `browse.resource` observable so the test controls resolve timing.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render, fireEvent } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { BehaviorSubject } from 'rxjs';
+import type { Annotation, AnnotationId, ResourceDescriptor } from '@semiont/core';
+import type { SemiontSession } from '@semiont/sdk';
+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: () => ({}) }));
+// jsdom has no Range API — the overlay is not under test here.
+vi.mock('../../../lib/annotation-overlay', () => ({
+  buildSourceToRenderedMap: vi.fn(() => new Map()),
+  buildTextNodeIndex: vi.fn(() => []),
+  resolveAnnotationRanges: vi.fn(() => new Map()),
+  applyHighlights: vi.fn(),
+  clearHighlights: vi.fn(),
+  toOverlayAnnotations: vi.fn(() => []),
+}));
+
+const REFERENT = { '@id': 'res-target', name: 'Target Doc' } as unknown as ResourceDescriptor;
+const DWELL = 100;
+
+const makeAnnotation = (id: string, body: Annotation['body']): Annotation => ({
+  '@context': 'http://www.w3.org/ns/anno.jsonld',
+  id: id as AnnotationId,
+  type: 'Annotation',
+  motivation: 'linking',
+  creator: { '@type': 'Person', name: 'u' },
+  created: '2024-01-01T00:00:00Z',
+  target: { source: 'res-1', selector: { type: 'TextPositionSelector', start: 0, end: 4 } },
+  body,
+});
+
+const resolvedRef = makeAnnotation('ref-resolved', [{ type: 'SpecificResource', source: 'res-target', purpose: 'linking' }]);
+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 session = {
+    client: {
+      browse: { click: vi.fn(), resource: browseResource },
+      beckon: { hover: beckonHover },
+    },
+    subscribe: () => () => {},
+  } as unknown as SemiontSession;
+
+  const { container } = render(
+    <BrowseView
+      content="some text"
+      mimeType="text/plain"
+      resourceUri="res-1"
+      annotations={{ highlights: [], references: [resolvedRef, stubRef], assessments: [], comments: [], tags: [] }}
+      annotateMode={false}
+      hoverDelayMs={DWELL}
+      session={session}
+      {...(onReferenceHover ? { onReferenceHover } : {})}
+    />,
+  );
+  const content = container.querySelector('.semiont-browse-view__content')!;
+
+  const hoverTarget = (id: string) => {
+    const el = document.createElement('span');
+    el.setAttribute('data-annotation-id', id);
+    return { el, target: { closest: vi.fn(() => el) } as unknown as Element };
+  };
+
+  return { content, referent$, beckonHover, browseResource, hoverTarget };
+}
+
+describe('BrowseView — onReferenceHover (Phase 2b)', () => {
+  beforeEach(() => { vi.useFakeTimers(); });
+  afterEach(() => { vi.useRealTimers(); });
+
+  it('fires once after dwell + descriptor resolve, with {annotation, referent, anchorRect}', () => {
+    const onReferenceHover = vi.fn();
+    const { content, referent$, hoverTarget } = setup(onReferenceHover);
+
+    fireEvent.mouseOver(content, { target: hoverTarget('ref-resolved').target });
+    vi.advanceTimersByTime(DWELL + 10);        // dwell fires → subscribe starts
+    expect(onReferenceHover).not.toHaveBeenCalled(); // descriptor not resolved yet
+
+    referent$.next(REFERENT);                  // descriptor lands
+    expect(onReferenceHover).toHaveBeenCalledTimes(1);
+    const hover = onReferenceHover.mock.calls[0]![0];
+    expect(hover.annotation.id).toBe('ref-resolved');
+    expect(hover.referent).toBe(REFERENT);
+    expect(typeof hover.anchorRect.top).toBe('number'); // DOMRect from the hovered span
+
+    referent$.next({ ...REFERENT });           // later cache emissions must NOT re-fire
+    expect(onReferenceHover).toHaveBeenCalledTimes(1);
+  });
+
+  it('a stub reference fires nothing — not even null on leave', () => {
+    const onReferenceHover = vi.fn();
+    const { content, beckonHover, hoverTarget } = setup(onReferenceHover);
+
+    const { target } = hoverTarget('ref-stub');
+    fireEvent.mouseOver(content, { target });
+    vi.advanceTimersByTime(DWELL + 10);
+    fireEvent.mouseOut(content, { target });
+
+    expect(onReferenceHover).not.toHaveBeenCalled();
+    expect(beckonHover).toHaveBeenCalledWith('ref-stub'); // panel-highlight path unaffected
+  });
+
+  it('leaving before the descriptor resolves cancels: no fire, and a late resolve stays silent', () => {
+    const onReferenceHover = vi.fn();
+    const { content, referent$, hoverTarget } = setup(onReferenceHover);
+
+    const { target } = hoverTarget('ref-resolved');
+    fireEvent.mouseOver(content, { target });
+    vi.advanceTimersByTime(DWELL + 10);        // dwell fired, load in flight
+    fireEvent.mouseOut(content, { target });   // leave first
+
+    referent$.next(REFERENT);                  // late resolve
+    expect(onReferenceHover).not.toHaveBeenCalled(); // cancelled — and no stray null either
+  });
+
+  it('leaving after a fire sends null', () => {
+    const onReferenceHover = vi.fn();
+    const { content, referent$, hoverTarget } = setup(onReferenceHover);
+
+    const { target } = hoverTarget('ref-resolved');
+    fireEvent.mouseOver(content, { target });
+    vi.advanceTimersByTime(DWELL + 10);
+    referent$.next(REFERENT);
+    expect(onReferenceHover).toHaveBeenCalledTimes(1);
+
+    fireEvent.mouseOut(content, { target });
+    expect(onReferenceHover).toHaveBeenCalledTimes(2);
+    expect(onReferenceHover).toHaveBeenLastCalledWith(null);
+  });
+
+  it('without onReferenceHover, hover still emits beckon:hover and loads nothing', () => {
+    const { content, beckonHover, browseResource, hoverTarget } = setup();
+
+    fireEvent.mouseOver(content, { target: hoverTarget('ref-resolved').target });
+    vi.advanceTimersByTime(DWELL + 10);
+
+    expect(beckonHover).toHaveBeenCalledWith('ref-resolved');
+    expect(browseResource).not.toHaveBeenCalled(); // no handler → no referent load
+  });
+});

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

@@ -0,0 +1,43 @@
+/**
+ * EMBEDDABLE-RESOURCE-VIEWER step 3 — overridable browse media-renderer registry.
+ *
+ * A consumer can swap a media renderer via the `renderers` prop (e.g. its own PDF
+ * viewer) without forking BrowseView. AnnotateToolbar is mocked (unrelated here).
+ *
+ * Started RED (tsc: no `renderers` prop) and GREEN once step 3 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';
+import type { MediaRendererProps } from '../browse-renderers';
+
+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;
+}
+
+describe('BrowseView — media-renderer registry', () => {
+  it('uses a custom renderer from the `renderers` override', () => {
+    const CustomText = ({ content }: MediaRendererProps) => <div>custom-render: {content}</div>;
+    render(
+      <BrowseView
+        content="the-body"
+        mimeType="text/plain"
+        resourceUri="res-1"
+        annotations={emptyAnnotations}
+        annotateMode={false}
+        session={fakeSession()}
+        renderers={{ text: CustomText }}
+      />,
+    );
+    expect(screen.getByText(/custom-render: the-body/)).toBeInTheDocument();
+  });
+});

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

@@ -3,17 +3,15 @@ import React from 'react';
 import { render, screen, fireEvent, waitFor } from '@testing-library/react';
 import { BrowseView } from '../BrowseView';
 import type { EventBus } from '@semiont/core';
+import type { SemiontClient, SemiontSession } from '@semiont/sdk';
 import { createTestSemiontWrapper } from '../../../test-utils';
 
 import type { Annotation, AnnotationId } from '@semiont/core';
 
-// Mock ResourceAnnotationsContext - keep this simple
-let mockNewAnnotationIds = new Set<string>();
-vi.mock('../../../contexts/ResourceAnnotationsContext', () => ({
-  useResourceAnnotations: vi.fn(() => ({
-    newAnnotationIds: mockNewAnnotationIds,
-  })),
-}));
+// BrowseView takes its `session` + `newAnnotationIds` as props now (step 1a) — no
+// ResourceAnnotationsContext / SemiontProvider reach-in. `makeSession` (below)
+// wraps the fake client so browse:click / beckon:hover land on the bus the
+// trackers listen on, and session.subscribe registers beckon:* on that bus.
 
 // Mock @semiont/core utilities. The media-type registry (`capabilitiesOf`)
 // is NOT mocked — BrowseView dispatches on the real registry's render mode,
@@ -72,12 +70,8 @@ vi.mock('../../../lib/annotation-registry', () => ({
   },
 }));
 
-// Mock ImageViewer
-vi.mock('../../viewers', () => ({
-  ImageViewer: ({ resourceUri }: { resourceUri: string }) => (
-    <img data-testid="image-viewer" src={resourceUri} alt="Resource content" />
-  ),
-}));
+// Image browse renders the read-only SvgDrawingCanvas (real component — jsdom
+// renders its container fine; shape painting is covered by the dispatch spec).
 
 // Mock AnnotateToolbar
 vi.mock('../../annotation/AnnotateToolbar', () => ({
@@ -116,34 +110,47 @@ function createEventTracker() {
   };
 }
 
+// BrowseView now takes its session as a prop. Wrap the fake client so
+// browse:click / beckon:hover emit on the SAME bus the trackers listen on, and
+// session.subscribe registers beckon:* there (mirrors test-utils' fake session).
+function makeSession(client: SemiontClient): SemiontSession {
+  return {
+    client,
+    subscribe: (channel: string, handler: (p: never) => void) => {
+      const sub = (client.bus.get(channel as never) as { subscribe(fn: (p: never) => void): { unsubscribe(): void } }).subscribe(handler);
+      return () => sub.unsubscribe();
+    },
+  } as unknown as SemiontSession;
+}
+
 const renderWithProviders = (
-  component: React.ReactElement,
+  component: React.ReactElement<React.ComponentProps<typeof BrowseView>>,
   options: { newAnnotationIds?: Set<string> } = {}
 ) => {
-  if (options.newAnnotationIds) {
-    mockNewAnnotationIds = options.newAnnotationIds;
-  }
-  const { SemiontWrapper } = createTestSemiontWrapper();
+  const { SemiontWrapper, client } = createTestSemiontWrapper();
   const Wrapper = ({ children }: { children: React.ReactNode }) => (
     <SemiontWrapper>{children}</SemiontWrapper>
   );
-  return render(component, { wrapper: Wrapper });
+  return render(
+    React.cloneElement(component, { session: makeSession(client), newAnnotationIds: options.newAnnotationIds }),
+    { wrapper: Wrapper },
+  );
 };
 
 const renderWithEventTracking = (
-  component: React.ReactElement,
+  component: React.ReactElement<React.ComponentProps<typeof BrowseView>>,
   tracker: ReturnType<typeof createEventTracker>,
   options: { newAnnotationIds?: Set<string> } = {}
 ) => {
-  if (options.newAnnotationIds) {
-    mockNewAnnotationIds = options.newAnnotationIds;
-  }
-  const { SemiontWrapper, eventBus } = createTestSemiontWrapper();
+  const { SemiontWrapper, eventBus, client } = createTestSemiontWrapper();
   tracker._attach(eventBus);
   const Wrapper = ({ children }: { children: React.ReactNode }) => (
     <SemiontWrapper>{children}</SemiontWrapper>
   );
-  return render(component, { wrapper: Wrapper });
+  return render(
+    React.cloneElement(component, { session: makeSession(client), newAnnotationIds: options.newAnnotationIds }),
+    { wrapper: Wrapper },
+  );
 };
 
 // Test data fixtures
@@ -179,11 +186,13 @@ describe('BrowseView Component', () => {
     hoveredAnnotationId: null,
     selectedClick: 'detail' as const,
     annotateMode: false,
+    // Placeholder — the render helpers override this with a session bound to the
+    // fake client's bus (so emits/subscriptions land where the trackers listen).
+    session: null as SemiontSession | null,
   };
 
   beforeEach(() => {
     vi.clearAllMocks();
-    mockNewAnnotationIds = new Set();
 
     // Mock scrollIntoView for jsdom
     if (typeof Element !== 'undefined') {
@@ -211,10 +220,12 @@ describe('BrowseView Component', () => {
       expect(screen.getByTestId('annotate-toolbar')).toBeInTheDocument();
     });
 
-    it('should render image viewer for image mime types', () => {
-      renderWithProviders(<BrowseView {...defaultProps} mimeType="image/png" />);
+    it('should render the read-only annotation canvas for image mime types', () => {
+      // Was a bare ImageViewer, which silently dropped the annotations prop
+      // (bugs/image-browse-renderer-drops-annotations.md).
+      const { container } = renderWithProviders(<BrowseView {...defaultProps} mimeType="image/png" />);
 
-      expect(screen.getByTestId('image-viewer')).toBeInTheDocument();
+      expect(container.querySelector('.semiont-svg-drawing-canvas')).toBeInTheDocument();
     });
 
     it('should render unsupported message for unsupported mime types', () => {
@@ -391,12 +402,16 @@ describe('BrowseView Component', () => {
       });
     });
 
-    it('should emit browse:click only for reference annotations', async () => {
+    it('should emit browse:click for every motivation', async () => {
+      // browse:click is the platform's one "user clicked an annotation" signal;
+      // text browse mode must emit it for whatever the click resolves, matching
+      // the image/PDF/annotate emitters (BROWSE-CLICK-ALL-MOTIVATIONS.md).
       const tracker = createEventTracker();
       const annotations = {
         ...defaultProps.annotations,
         references: [createMockAnnotation('linking', 'ref-1')],
         highlights: [createMockAnnotation('highlighting', 'highlight-1')],
+        comments: [createMockAnnotation('commenting', 'comment-1')],
       };
 
       const { container } = renderWithEventTracking(
@@ -404,36 +419,101 @@ describe('BrowseView Component', () => {
         tracker
       );
 
-      const mockReferenceElement = document.createElement('span');
-      mockReferenceElement.setAttribute('data-annotation-id', 'ref-1');
-      mockReferenceElement.setAttribute('data-annotation-type', 'reference');
+      const browseContainer = container.querySelector('.semiont-browse-view__content');
 
-      const mockHighlightElement = document.createElement('span');
-      mockHighlightElement.setAttribute('data-annotation-id', 'highlight-1');
-      mockHighlightElement.setAttribute('data-annotation-type', 'highlight');
+      const clickCases = [
+        { id: 'ref-1', type: 'reference', motivation: 'linking' },
+        { id: 'highlight-1', type: 'highlight', motivation: 'highlighting' },
+        { id: 'comment-1', type: 'comment', motivation: 'commenting' },
+      ] as const;
 
-      const mockRefTarget = { closest: vi.fn(() => mockReferenceElement) } as any;
-      const mockHighlightTarget = { closest: vi.fn(() => mockHighlightElement) } as any;
+      for (const { id, type, motivation } of clickCases) {
+        const el = document.createElement('span');
+        el.setAttribute('data-annotation-id', id);
+        el.setAttribute('data-annotation-type', type);
+        const mockTarget = { closest: vi.fn(() => el) } as unknown as EventTarget;
+
+        tracker.clear();
+        fireEvent.click(browseContainer!, { target: mockTarget });
+
+        await waitFor(() => {
+          expect(tracker.events.some(e =>
+            e.event === 'browse:click' &&
+            e.payload?.annotationId === id &&
+            e.payload?.motivation === motivation
+          )).toBe(true);
+        });
+      }
+    });
 
-      const browseContainer = container.querySelector('.semiont-browse-view__content');
+    it('should include the clicked span rect as anchorRect', async () => {
+      // A1 anchor thread (HEADLESS-ANNOTATION-PANELS Phase 3): the emission
+      // site owns the geometry — the clicked span's viewport rect rides the
+      // event so hosts can anchor popovers. Runtime-only; no schema pin.
+      const tracker = createEventTracker();
+      const annotations = {
+        ...defaultProps.annotations,
+        highlights: [createMockAnnotation('highlighting', 'highlight-1')],
+      };
 
-      tracker.clear();
+      const { container } = renderWithEventTracking(
+        <BrowseView {...defaultProps} annotations={annotations} />,
+        tracker
+      );
 
-      // Click reference - should emit
-      fireEvent.click(browseContainer!, { target: mockRefTarget });
+      const el = document.createElement('span');
+      el.setAttribute('data-annotation-id', 'highlight-1');
+      el.setAttribute('data-annotation-type', 'highlight');
+      const RECT: DOMRect = {
+        x: 10, y: 20, width: 30, height: 40,
+        top: 20, right: 40, bottom: 60, left: 10,
+        toJSON: () => ({}),
+      };
+      el.getBoundingClientRect = () => RECT;
+      const mockTarget = { closest: vi.fn(() => el) } as unknown as EventTarget;
+
+      const browseContainer = container.querySelector('.semiont-browse-view__content');
+      tracker.clear();
+      fireEvent.click(browseContainer!, { target: mockTarget });
 
       await waitFor(() => {
         expect(tracker.events.some(e =>
           e.event === 'browse:click' &&
-          e.payload?.annotationId === 'ref-1' &&
-          e.payload?.motivation === 'linking'
+          e.payload?.annotationId === 'highlight-1' &&
+          e.payload?.anchorRect?.left === 10 &&
+          e.payload?.anchorRect?.width === 30
         )).toBe(true);
       });
+    });
 
-      tracker.clear();
+    it('should not emit browse:click when the click completes a text selection', async () => {
+      // Browse mode is the reading surface: a drag-select that starts and ends
+      // inside one annotated span fires click on it. The guard applies to
+      // references too — a copy-drag inside a reference span must not emit
+      // (deliberate behavior change; previously it navigated under `follow`).
+      const tracker = createEventTracker();
+      const annotations = {
+        ...defaultProps.annotations,
+        references: [createMockAnnotation('linking', 'ref-1')],
+      };
 
-      // Click highlight - should not emit
-      fireEvent.click(browseContainer!, { target: mockHighlightTarget });
+      const { container } = renderWithEventTracking(
+        <BrowseView {...defaultProps} annotations={annotations} />,
+        tracker
+      );
+
+      const el = document.createElement('span');
+      el.setAttribute('data-annotation-id', 'ref-1');
+      el.setAttribute('data-annotation-type', 'reference');
+      const mockTarget = { closest: vi.fn(() => el) } as unknown as EventTarget;
+
+      vi.spyOn(window, 'getSelection').mockReturnValue({
+        isCollapsed: false,
+      } as Selection);
+
+      const browseContainer = container.querySelector('.semiont-browse-view__content');
+      tracker.clear();
+      fireEvent.click(browseContainer!, { target: mockTarget });
 
       await new Promise(resolve => setTimeout(resolve, 50));
       expect(tracker.events.filter(e => e.event === 'browse:click').length).toBe(0);
@@ -499,7 +579,7 @@ describe('BrowseView Component', () => {
         tags: [],
       };
 
-      const { SemiontWrapper, eventBus } = createTestSemiontWrapper();
+      const { SemiontWrapper, eventBus, client } = createTestSemiontWrapper();
       eventBus.get('beckon:hover').subscribe((payload: any) => {
         eventTracker.push({ event: 'beckon:hover', annotationId: payload?.annotationId ?? null });
       });
@@ -509,7 +589,7 @@ describe('BrowseView Component', () => {
 
       const { container } = render(
         <SemiontWrapper>
-          <BrowseView {...defaultProps} annotations={manyAnnotations} />
+          <BrowseView {...defaultProps} annotations={manyAnnotations} session={makeSession(client)} />
         </SemiontWrapper>
       );
 
@@ -539,13 +619,13 @@ describe('BrowseView Component', () => {
         expect(eventTracker.some(e => e.event === 'browse:click' && e.annotationId === 'ref-1')).toBe(true);
       });
 
-      // Verify highlight doesn't trigger click events
+      // Highlights emit through the same delegated handler (all motivations)
       eventTracker.length = 0; // Clear tracker
       fireEvent.click(browseContainer!, { target: mockHighlightTarget });
 
-      // Should not have any click events for highlights
-      await new Promise(resolve => setTimeout(resolve, 50));
-      expect(eventTracker.some(e => e.event === 'browse:click')).toBe(false);
+      await waitFor(() => {
+        expect(eventTracker.some(e => e.event === 'browse:click' && e.annotationId === 'highlight-1')).toBe(true);
+      });
 
       // The key insight: With event delegation, we can handle 100 annotations
       // with only container-level listeners, not 100+ individual listeners

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

@@ -0,0 +1,102 @@
+/**
+ * EMBEDDABLE-RESOURCE-VIEWER — keystone acceptance spec.
+ *
+ * The consumer's (my-chat) actual requirement: render + interact with a resource
+ * fed ONLY a `SemiontSession`, with NO SemiontProvider / TranslationProvider /
+ * cache context mounted. This is the definition of done for provider-free
+ * rendering — the "an external host can import the pieces" half of the plan's
+ * dual acceptance test.
+ *
+ * GREEN as of step 1c: the browse-mode subtree (ResourceViewer → BrowseView →
+ * AnnotateToolbar) renders provider-free from a bare session. The annotate-mode
+ * subtree is covered by AnnotateView.embeddable.test.tsx.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, act, waitFor } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import type { SemiontSession } from '@semiont/sdk';
+import type { ResourceDescriptor as SemiontResource, ResourceId } from '@semiont/core';
+import { createTestSemiontWrapper } from '../../../test-utils';
+import { ResourceViewer } from '../ResourceViewer';
+
+// Minimal bring-your-own-session double: just the surface ResourceViewer + its
+// subtree touch — `client.browse` / `client.mark` and generic-channel `subscribe`.
+function fakeSession(): SemiontSession {
+  const client = {
+    baseUrl: 'http://localhost:4000',
+    browse: { invalidateAnnotationList: vi.fn(), click: vi.fn() },
+    mark: { delete: vi.fn() },
+  };
+  return {
+    client,
+    subscribe: () => () => {},
+  } as unknown as SemiontSession;
+}
+
+const resource: SemiontResource & { content: string } = {
+  '@context': 'https://www.w3.org/ns/activitystreams',
+  '@id': 'res-1' as ResourceId,
+  name: 'Doc',
+  created: '2024-01-01T00:00:00Z',
+  entityTypes: [],
+  archived: false,
+  representations: [{ mediaType: 'text/plain', byteSize: 10 }],
+  content: 'Embeddable content.',
+};
+
+const annotations = { highlights: [], references: [], assessments: [], comments: [], tags: [] };
+
+describe('ResourceViewer — embeddable (bring-your-own-session, no providers)', () => {
+  // GREEN: the whole browse-mode subtree (ResourceViewer → BrowseView →
+  // AnnotateToolbar) renders provider-free from a bare session.
+  it('renders content fed only a session, with NO providers mounted', () => {
+    render(
+      <ResourceViewer
+        session={fakeSession()}
+        resource={resource}
+        annotations={annotations}
+        onOpenResource={vi.fn()}
+        onOpenPanel={vi.fn()}
+      />,
+    );
+    expect(screen.getByText('Embeddable content.')).toBeInTheDocument();
+  });
+
+  // A1 anchor thread: the viewer is a pass-through for view geometry — an
+  // anchorRect arriving on browse:click reaches the host's onOpenPanel
+  // untouched (detail routing, the default click action).
+  it('forwards the browse:click anchorRect into onOpenPanel', async () => {
+    const { session, eventBus } = createTestSemiontWrapper();
+    const onOpenPanel = vi.fn();
+
+    render(
+      <ResourceViewer
+        session={session}
+        resource={resource}
+        annotations={annotations}
+        onOpenResource={vi.fn()}
+        onOpenPanel={onOpenPanel}
+      />,
+    );
+
+    const anchorRect = {
+      x: 5, y: 6, width: 7, height: 8,
+      top: 6, right: 12, bottom: 14, left: 5,
+    };
+    act(() => {
+      eventBus.get('browse:click').next({
+        annotationId: 'ann-1',
+        motivation: 'highlighting',
+        anchorRect,
+      });
+    });
+
+    await waitFor(() => {
+      expect(onOpenPanel).toHaveBeenCalledWith(expect.objectContaining({
+        panel: 'annotations',
+        scrollToAnnotationId: 'ann-1',
+        anchorRect: expect.objectContaining({ left: 5, width: 7 }),
+      }));
+    });
+  });
+});