@semiont/react-ui 0.5.10 → 0.5.11

package/src/components/resource/__tests__/ResourceViewer.toolbar-prefs.test.tsx

@@ -0,0 +1,200 @@
+/**
+ * TOOLBAR-PREFS-AS-PROPS — keystone + per-pref specs.
+ *
+ * Preferences are state, not events: each of the four toolbar prefs (mode, click
+ * action, selection motivation, shape) is a controlled/uncontrolled prop pair.
+ * Controlled instances render the given value and report intents via the callback —
+ * never self-mutate, never touch localStorage, never hear other instances.
+ * Uncontrolled instances hold a plain internal default (false / 'detail' /
+ * 'linking' / 'rectangle') — NOT the legacy localStorage+bus behavior (that lives
+ * in the useToolbarPrefs() policy layer).
+ *
+ * RED ledger: authored `it.fails` (observed: 5 expected fail), flipped to `it` at
+ * Phase 1 GREEN. Provider-free; real AnnotateToolbar (its controls are the subject).
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render, fireEvent, within, 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 { ResourceViewer } from '../ResourceViewer';
+
+vi.mock('../../CodeMirrorRenderer', () => ({ CodeMirrorRenderer: () => <div>cm-mock</div> }));
+vi.mock('../../image-annotation/SvgDrawingCanvas', () => ({ SvgDrawingCanvas: () => <div>svg-mock</div> }));
+vi.mock('react-markdown', () => ({ default: ({ children }: { children: string }) => <div>{children}</div> }));
+vi.mock('remark-gfm', () => ({ default: () => ({}) }));
+
+function makeResource(mediaType = 'text/plain'): SemiontResource & { content: string } {
+  return {
+    '@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, byteSize: 10 }],
+    content: 'Prefs content.',
+  };
+}
+
+const annotations = { highlights: [], references: [], assessments: [], comments: [], tags: [] };
+
+/** Session double with a live subscribe registry so specs can fire legacy broadcasts. */
+function liveSession() {
+  const handlers = new Map<string, Set<(p: unknown) => void>>();
+  const client = {
+    browse: { click: vi.fn(), invalidateAnnotationList: vi.fn() },
+    beckon: { hover: vi.fn() },
+    mark: {
+      toggleMode: vi.fn(), delete: vi.fn(), request: vi.fn(),
+      changeSelection: vi.fn(), changeClick: vi.fn(), changeShape: vi.fn(),
+    },
+  };
+  const session = {
+    client,
+    subscribe: (channel: string, handler: (p: unknown) => void) => {
+      if (!handlers.has(channel)) handlers.set(channel, new Set());
+      handlers.get(channel)!.add(handler);
+      return () => { handlers.get(channel)!.delete(handler); };
+    },
+  } as unknown as SemiontSession;
+  const fire = (channel: string, payload?: unknown) =>
+    handlers.get(channel)?.forEach((h) => h(payload));
+  return { session, client, fire };
+}
+
+const isAnnotate = (c: HTMLElement) => !!c.querySelector('.semiont-annotate-view');
+const isBrowse = (c: HTMLElement) => !!c.querySelector('.semiont-browse-view');
+
+/** Open a bar dropdown group by aria-label and click an option in its menu. */
+async function pick(container: HTMLElement, group: string, option: string) {
+  const trigger = within(container).getByLabelText(group);
+  fireEvent.mouseEnter(trigger.parentElement!);
+  await waitFor(() => {
+    const menu = within(container).getByRole('menu');
+    fireEvent.click(within(menu).getByText(option));
+  });
+}
+
+const PREF_KEYS = ['annotateMode', 'semiont-toolbar-click', 'semiont-toolbar-selection'];
+let getSpy: ReturnType<typeof vi.spyOn>;
+let setSpy: ReturnType<typeof vi.spyOn>;
+const prefKeyTouched = (spy: ReturnType<typeof vi.spyOn>) =>
+  spy.mock.calls.some((call: unknown[]) => {
+    const key = String(call[0]);
+    return PREF_KEYS.includes(key) || key.includes('shape');
+  });
+
+describe('ResourceViewer — toolbar prefs as props', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    localStorage.clear();
+    getSpy = vi.spyOn(Storage.prototype, 'getItem');
+    setSpy = vi.spyOn(Storage.prototype, 'setItem');
+  });
+  afterEach(() => {
+    getSpy.mockRestore();
+    setSpy.mockRestore();
+  });
+
+  // ── Keystone: per-instance isolation across three viewers on one session ──
+  it('keystone: three viewers — controlled A/B independent, C uncontrolled; B\'s Mode click fires only B\'s callback', async () => {
+    const { session, client } = liveSession();
+    const onB = vi.fn();
+    const a = render(
+      <ResourceViewer session={session} resource={makeResource()} annotations={annotations}
+        annotateMode={true} clickAction="follow" onAnnotateModeChange={vi.fn()} onClickActionChange={vi.fn()} />,
+    );
+    const b = render(
+      <ResourceViewer session={session} resource={makeResource()} annotations={annotations}
+        annotateMode={false} onAnnotateModeChange={onB} />,
+    );
+    const c = render(
+      <ResourceViewer session={session} resource={makeResource()} annotations={annotations} />,
+    );
+
+    expect(isAnnotate(a.container)).toBe(true);   // A renders its controlled mode
+    expect(isBrowse(b.container)).toBe(true);
+    expect(isBrowse(c.container)).toBe(true);     // C: plain default (false)
+
+    await pick(b.container, 'Mode', 'Annotate');
+
+    expect(onB).toHaveBeenCalledWith(true);                 // B reports intent…
+    expect(isBrowse(b.container)).toBe(true);               // …and does not self-flip
+    expect(isAnnotate(a.container)).toBe(true);             // A unchanged
+    expect(isBrowse(c.container)).toBe(true);               // C unchanged
+    expect(client.mark.toggleMode).not.toHaveBeenCalled();  // no global emit
+    expect(prefKeyTouched(getSpy)).toBe(false);             // no localStorage traffic
+    expect(prefKeyTouched(setSpy)).toBe(false);
+  });
+
+  // ── Per-pref: mode ──
+  it('mode: uncontrolled uses the plain default and is inert to the legacy broadcast', () => {
+    localStorage.setItem('annotateMode', 'true'); // legacy key must be IGNORED
+    getSpy.mockClear(); setSpy.mockClear();
+    const { session, fire } = liveSession();
+    const u = render(
+      <ResourceViewer session={session} resource={makeResource()} annotations={annotations} />,
+    );
+    expect(isBrowse(u.container)).toBe(true);      // plain default, not the stored 'true'
+    fire('mark:mode-toggled');
+    expect(isBrowse(u.container)).toBe(true);      // inert: preference events are gone
+    expect(prefKeyTouched(getSpy)).toBe(false);
+    expect(prefKeyTouched(setSpy)).toBe(false);
+  });
+
+  // ── Per-pref: click action ──
+  it('clickAction: controlled renders the value; the bar control reports and does not mutate', async () => {
+    const { session, client } = liveSession();
+    const onChange = vi.fn();
+    const v = render(
+      <ResourceViewer session={session} resource={makeResource()} annotations={annotations}
+        clickAction="follow" onClickActionChange={onChange} />,
+    );
+    const bar = v.container.querySelector('.semiont-annotate-toolbar') as HTMLElement;
+    expect(within(bar).getByText('Follow')).toBeInTheDocument();  // renders the prop value
+
+    await pick(v.container, 'Click', 'Detail');
+    expect(onChange).toHaveBeenCalledWith('detail');              // reports intent
+    expect(within(bar).getByText('Follow')).toBeInTheDocument();  // does not self-mutate
+    expect(client.mark.changeClick).not.toHaveBeenCalled();
+  });
+
+  // ── Per-pref: selection motivation (annotate-mode bar) ──
+  it('selectionMotivation: controlled renders the value; picking reports; re-picking the current reports null', async () => {
+    const { session, client } = liveSession();
+    const onChange = vi.fn();
+    const v = render(
+      <ResourceViewer session={session} resource={makeResource()} annotations={annotations}
+        annotateMode={true} onAnnotateModeChange={vi.fn()}
+        selectionMotivation="highlighting" onSelectionMotivationChange={onChange} />,
+    );
+    const bar = v.container.querySelector('.semiont-annotate-toolbar') as HTMLElement;
+    expect(within(bar).getByText('Highlight')).toBeInTheDocument(); // renders the prop value
+
+    await pick(v.container, 'Motivation', 'Comment');
+    expect(onChange).toHaveBeenCalledWith('commenting');
+
+    await pick(v.container, 'Motivation', 'Highlight');             // current value → toggles off
+    expect(onChange).toHaveBeenCalledWith(null);
+    expect(client.mark.changeSelection).not.toHaveBeenCalled();
+  });
+
+  // ── Per-pref: shape (media-gated; image annotate bar) ──
+  it('shape: controlled renders the value; picking reports and does not mutate', async () => {
+    const { session, client } = liveSession();
+    const onChange = vi.fn();
+    const v = render(
+      <ResourceViewer session={session} resource={makeResource('image/png')} annotations={annotations}
+        annotateMode={true} onAnnotateModeChange={vi.fn()}
+        shape="circle" onShapeChange={onChange} />,
+    );
+    const bar = v.container.querySelector('.semiont-annotate-toolbar') as HTMLElement;
+    expect(within(bar).getByText('Circle')).toBeInTheDocument();    // renders the prop value
+
+    await pick(v.container, 'Shape', 'Polygon');
+    expect(onChange).toHaveBeenCalledWith('polygon');
+    expect(within(bar).getByText('Circle')).toBeInTheDocument();    // does not self-mutate
+    expect(client.mark.changeShape).not.toHaveBeenCalled();
+  });
+});

package/src/components/resource/__tests__/browse-renderers.test.tsx

@@ -0,0 +1,34 @@
+/**
+ * EMBEDDABLE-VIEWER-COMPLETION Phase 0 — regression: the browse `text` default
+ * renders markdown as **formatted prose**, not raw source.
+ *
+ * The other BrowseView suites mock `react-markdown` away for simplicity, so
+ * nothing currently pins that the default text renderer actually *formats*
+ * markdown. This spec uses the real renderer and guards against a regression to
+ * raw/source rendering.
+ */
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { TextBrowseRenderer, defaultBrowseRenderers } from '../browse-renderers';
+
+const base = { mimeType: 'text/markdown', resourceUri: 'res-1', annotations: [] };
+
+describe('browse-renderers — markdown-as-prose (Phase 0 regression)', () => {
+  it('TextBrowseRenderer is the default `text` renderer', () => {
+    expect(defaultBrowseRenderers.text).toBe(TextBrowseRenderer);
+  });
+
+  it('renders markdown as formatted HTML, not raw source', () => {
+    const { container } = render(
+      <TextBrowseRenderer content={'# Big Heading\n\nsome **bold** and a [link](https://x.test).'} {...base} />,
+    );
+    // Formatted: heading / strong / anchor elements exist (react-markdown output).
+    expect(container.querySelector('h1')?.textContent).toBe('Big Heading');
+    expect(container.querySelector('strong')?.textContent).toBe('bold');
+    expect(container.querySelector('a')?.getAttribute('href')).toBe('https://x.test');
+    // NOT raw: the literal markdown syntax must not survive to the text content.
+    expect(container.textContent).not.toContain('# Big Heading');
+    expect(container.textContent).not.toContain('**bold**');
+  });
+});

package/src/components/resource/__tests__/inline-embedding.test.tsx

@@ -0,0 +1,81 @@
+/**
+ * EMBEDDABLE-VIEWER-COMPLETION Phase 1 — inline embedding.
+ *
+ * `inline` is a display variant (default: today's pane behavior, frontend
+ * untouched): the viewer renders at content height in a bare container — no
+ * inner scroll container, no pane chrome. jsdom can't compute stylesheet
+ * layout, so this spec pins the two testable seams: (1) the components emit
+ * the `--inline` modifier classes; (2) the stylesheet contains the inline
+ * overrides (height:auto / overflow:visible / padding drop). The visual
+ * auto-height check is the plan's live smoke-test.
+ *
+ * Started RED (no `inline` prop) and GREEN once Phase 1 lands.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { render } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { SemiontSession } from '@semiont/sdk';
+import type { ResourceDescriptor as SemiontResource, ResourceId } from '@semiont/core';
+import { BrowseView } from '../BrowseView';
+import { ResourceViewer } from '../ResourceViewer';
+
+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;
+}
+
+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: 'Inline content.',
+};
+
+describe('inline embedding (Phase 1)', () => {
+  it('BrowseView: `inline` adds the modifier class; default does not', () => {
+    const props = {
+      content: 'x', mimeType: 'text/plain', resourceUri: 'res-1',
+      annotations: emptyAnnotations, annotateMode: false, session: fakeSession(),
+    };
+    const { container: pane } = render(<BrowseView {...props} />);
+    expect(pane.querySelector('.semiont-browse-view')).not.toHaveClass('semiont-browse-view--inline');
+
+    const { container } = render(<BrowseView {...props} inline />);
+    expect(container.querySelector('.semiont-browse-view')).toHaveClass('semiont-browse-view--inline');
+  });
+
+  it('ResourceViewer: `inline` marks its root and threads to BrowseView', () => {
+    const { container } = render(
+      <ResourceViewer
+        resource={resource} annotations={emptyAnnotations}
+        session={fakeSession()} inline
+      />,
+    );
+    expect(container.querySelector('.semiont-resource-viewer')).toHaveClass('semiont-resource-viewer--inline');
+    expect(container.querySelector('.semiont-browse-view')).toHaveClass('semiont-browse-view--inline');
+  });
+
+  it('stylesheet carries the inline overrides (static gate — layout itself is the live check)', () => {
+    // vitest runs with cwd = the package root (same in CI's per-workspace run).
+    const css = readFileSync(resolve(process.cwd(), 'src/styles/features/resource-viewer.css'), 'utf8');
+    // Auto-height roots, and the content area stops being a scroll container / drops the pane gutter.
+    expect(css).toMatch(/\.semiont-resource-viewer--inline\s*\{[^}]*height:\s*auto/);
+    expect(css).toMatch(/\.semiont-browse-view--inline\s*\{[^}]*height:\s*auto/);
+    expect(css).toMatch(/\.semiont-browse-view--inline\s+\.semiont-browse-view__content\s*\{[^}]*overflow:\s*visible/);
+    expect(css).toMatch(/\.semiont-browse-view--inline\s+\.semiont-browse-view__content\s*\{[^}]*padding:\s*0/);
+  });
+});

package/src/components/resource/__tests__/media-completeness.test.tsx

@@ -0,0 +1,88 @@
+/**
+ * EMBEDDABLE-VIEWER-COMPLETION Phase 4 — media-completeness sweep.
+ *
+ * ONE mounted component (`ResourceViewer`, inline, bare session, no providers)
+ * renders every standard media type from the DEFAULTS — text, markdown, image,
+ * pdf — with the annotation-overlay container present and zero per-type wiring.
+ * (Formatted-markdown correctness is pinned by browse-renderers.test; visual
+ * overlay alignment is the plan's live smoke-test. This sweep pins the routing
+ * parity: every type reaches its renderer from one component.)
+ */
+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 { ResourceDescriptor as SemiontResource, ResourceId } from '@semiont/core';
+import { ResourceViewer } from '../ResourceViewer';
+
+vi.mock('react-markdown', () => ({ default: ({ children }: { children: string }) => <div data-testid="md">{children}</div> }));
+vi.mock('remark-gfm', () => ({ default: () => ({}) }));
+// pdfjs can't load in jsdom — the sweep pins ROUTING to the pdf renderer, not pdf.js itself.
+vi.mock('../../pdf-annotation/PdfAnnotationCanvas.client', () => ({
+  PdfAnnotationCanvas: ({ pdfUrl }: { pdfUrl: string }) => <div data-testid="pdf-canvas">{pdfUrl}</div>,
+}));
+
+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;
+}
+
+function makeResource(mediaType: string, content: string): SemiontResource & { content: string } {
+  return {
+    '@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, byteSize: 10 }],
+    content,
+  };
+}
+
+function mount(mediaType: string, content: string) {
+  return render(
+    <ResourceViewer
+      resource={makeResource(mediaType, content)}
+      annotations={emptyAnnotations}
+      session={fakeSession()}
+      inline
+    />,
+  );
+}
+
+describe('media-completeness sweep (Phase 4) — one component, all types, inline, defaults only', () => {
+  it.each([
+    ['text/plain', 'plain body'],
+    ['text/markdown', '# md body'],
+  ])('%s renders via the text default with the overlay container', (mt, content) => {
+    const { container } = mount(mt, content);
+    expect(container.querySelector('.semiont-browse-view[data-mime-type="text"]')).toBeInTheDocument();
+    expect(screen.getByTestId('md')).toHaveTextContent(content.replace('# ', '# ').trim());
+    expect(container.querySelector('.semiont-browse-view__content')).toBeInTheDocument(); // overlay anchor
+    expect(container.querySelector('.semiont-browse-view')).toHaveClass('semiont-browse-view--inline');
+  });
+
+  it('image/png renders via the image default', () => {
+    const { container } = mount('image/png', 'https://media.test/img.png?token=t');
+    expect(container.querySelector('.semiont-browse-view[data-mime-type="image"]')).toBeInTheDocument();
+    expect(container.querySelector('img')).toBeInTheDocument();
+    expect(container.querySelector('.semiont-browse-view__content')).toBeInTheDocument();
+  });
+
+  it('application/pdf routes to the pdf default', async () => {
+    const { container } = mount('application/pdf', 'https://media.test/doc.pdf?token=t');
+    expect(container.querySelector('.semiont-browse-view[data-mime-type="pdf"]')).toBeInTheDocument();
+    expect(await screen.findByTestId('pdf-canvas')).toHaveTextContent('https://media.test/doc.pdf?token=t');
+  });
+
+  it('an unknown type degrades to metadata + download (no crash, no per-type wiring)', () => {
+    const { container } = mount('application/octet-stream', '');
+    expect(container.querySelector('[data-mime-type="unsupported"]')).toBeInTheDocument();
+    expect(screen.getByText(/Preview not available/)).toBeInTheDocument();
+  });
+});

package/src/components/resource/browse-renderers.tsx

@@ -0,0 +1,63 @@
+'use client';
+
+import { lazy, Suspense, memo, type ComponentType } from 'react';
+import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+import type { Annotation } from '@semiont/core';
+import { ImageViewer } from '../viewers';
+
+// Lazy-load the PDF component to avoid SSR issues with browser PDF.js loading.
+const PdfAnnotationCanvas = lazy(() => import('../pdf-annotation/PdfAnnotationCanvas.client').then(mod => ({ default: mod.PdfAnnotationCanvas })));
+
+/**
+ * Common props for a read-only ("browse") media renderer. `content` is decoded
+ * text for the text renderer, or a media URL for the image / PDF renderers.
+ * A consumer can implement this interface to swap in a custom renderer.
+ */
+export interface MediaRendererProps {
+  content: string;
+  mimeType: string;
+  resourceUri: string;
+  annotations: Annotation[];
+}
+
+/** Read-only media dispatch, keyed by the registry render mode. */
+export type BrowseMediaRenderers = Partial<Record<string, ComponentType<MediaRendererProps>>>;
+
+const MemoizedMarkdown = memo(function MemoizedMarkdown({ content }: { content: string }) {
+  // No annotation plugins: annotations are applied as a DOM overlay after paint.
+  return <ReactMarkdown remarkPlugins={[remarkGfm]}>{content}</ReactMarkdown>;
+});
+
+export function TextBrowseRenderer({ content }: MediaRendererProps) {
+  return <MemoizedMarkdown content={content} />;
+}
+
+export function ImageBrowseRenderer({ content, mimeType }: MediaRendererProps) {
+  return <ImageViewer imageUrl={content} mimeType={mimeType} alt="Resource content" />;
+}
+
+export function PdfBrowseRenderer({ content, resourceUri, annotations }: MediaRendererProps) {
+  return (
+    <Suspense fallback={<div className="semiont-browse-view__loading">Loading PDF viewer...</div>}>
+      <PdfAnnotationCanvas
+        pdfUrl={content}
+        resourceUri={resourceUri}
+        existingAnnotations={annotations}
+        drawingMode={null}
+        selectedMotivation={null}
+      />
+    </Suspense>
+  );
+}
+
+/**
+ * Default read-only media renderers. `BrowseView` merges a caller's `renderers`
+ * override on top of these, so a host can swap one renderer (e.g. its own PDF
+ * viewer) or add a mode without forking the view.
+ */
+export const defaultBrowseRenderers: Record<'text' | 'image' | 'pdf', ComponentType<MediaRendererProps>> = {
+  text: TextBrowseRenderer,
+  image: ImageBrowseRenderer,
+  pdf: PdfBrowseRenderer,
+};

package/src/components/resource/panels/AssessmentPanel.tsx

@@ -40,6 +40,8 @@ function getSelectorDisplayText(selector: Selector | Selector[]): string | null
 }
 
 interface AssessmentPanelProps {
+  /** The '@id' of the panel's resource — stamped as `source` on mark:submit (multi-viewer routing). */
+  resourceId: string;
   annotations: Annotation[];
   pendingAnnotation: PendingAnnotation | null;
   isAssisting?: boolean;
@@ -61,6 +63,7 @@ interface AssessmentPanelProps {
  * @subscribes browse:click - Annotation clicked. Payload: { annotationId: string }
  */
 export function AssessmentPanel({
+  resourceId,
   annotations,
   pendingAnnotation,
   isAssisting = false,
@@ -151,6 +154,7 @@ export function AssessmentPanel({
         : undefined;
 
       session?.client.mark.submit({
+        source: resourceId,
         motivation: 'assessing',
         selector: pendingAnnotation.selector,
         ...(body !== undefined ? { body } : {}),

package/src/components/resource/panels/CommentsPanel.tsx

@@ -40,6 +40,8 @@ function getSelectorDisplayText(selector: Selector | Selector[]): string | null
 }
 
 interface CommentsPanelProps {
+  /** The '@id' of the panel's resource — stamped as `source` on mark:submit (multi-viewer routing). */
+  resourceId: string;
   annotations: Annotation[];
   pendingAnnotation: PendingAnnotation | null;
   annotateMode?: boolean;
@@ -61,6 +63,7 @@ interface CommentsPanelProps {
  * @subscribes browse:click - Annotation clicked. Payload: { annotationId: string }
  */
 export function CommentsPanel({
+  resourceId,
   annotations,
   pendingAnnotation,
   annotateMode = true,
@@ -171,6 +174,7 @@ export function CommentsPanel({
   const handleSaveNewComment = () => {
     if (newCommentText.trim() && pendingAnnotation) {
       session?.client.mark.submit({
+        source: resourceId,
         motivation: 'commenting',
         selector: pendingAnnotation.selector,
         body: [{ type: 'TextualBody', value: newCommentText, purpose: 'commenting' }],

package/src/components/resource/panels/HighlightPanel.tsx

@@ -23,6 +23,8 @@ interface PendingAnnotation {
 }
 
 interface HighlightPanelProps {
+  /** The '@id' of the panel's resource — stamped as `source` on mark:submit (multi-viewer routing). */
+  resourceId: string;
   annotations: Annotation[];
   pendingAnnotation: PendingAnnotation | null;
   isAssisting?: boolean;
@@ -42,6 +44,7 @@ interface HighlightPanelProps {
  * @subscribes browse:click - Annotation clicked. Payload: { annotationId: string }
  */
 export function HighlightPanel({
+  resourceId,
   annotations,
   pendingAnnotation,
   isAssisting = false,
@@ -136,6 +139,7 @@ export function HighlightPanel({
   useEffect(() => {
     if (pendingAnnotation && pendingAnnotation.motivation === 'highlighting') {
       session?.client.mark.submit({
+        source: resourceId,
         motivation: 'highlighting',
         selector: pendingAnnotation.selector,
       });

package/src/components/resource/panels/ReferencesPanel.tsx

@@ -43,6 +43,8 @@ function getSelectorDisplayText(selector: Selector | Selector[]): string | null
 }
 
 interface Props {
+  /** The '@id' of the panel's resource — stamped as `source` on mark:submit (multi-viewer routing). */
+  resourceId: string;
   // Generic panel props
   annotations?: Annotation[];
   isAssisting: boolean;
@@ -76,6 +78,7 @@ interface Props {
  * @subscribes browse:click - Annotation clicked. Payload: { annotationId: string }
  */
 export function ReferencesPanel({
+  resourceId,
   annotations = [],
   isAssisting,
   progress,
@@ -255,6 +258,7 @@ export function ReferencesPanel({
     if (pendingAnnotation) {
       const entityType = pendingEntityTypes.join(',') || undefined;
       session?.client.mark.submit({
+        source: resourceId,
         motivation: 'linking',
         selector: pendingAnnotation.selector,
         body: entityType ? [{ type: 'TextualBody', value: entityType, purpose: 'tagging' }] : [],

package/src/components/resource/panels/TaggingPanel.tsx

@@ -39,6 +39,8 @@ function getSelectorDisplayText(selector: Selector | Selector[]): string | null
 }
 
 interface TaggingPanelProps {
+  /** The '@id' of the panel's resource — stamped as `source` on mark:submit (multi-viewer routing). */
+  resourceId: string;
   annotations: Annotation[];
   annotateMode?: boolean;
   isAssisting?: boolean;
@@ -62,6 +64,7 @@ interface TaggingPanelProps {
  * @subscribes browse:click - Annotation clicked. Payload: { annotationId: string }
  */
 export function TaggingPanel({
+  resourceId,
   annotations,
   annotateMode = true,
   isAssisting = false,
@@ -309,6 +312,7 @@ export function TaggingPanel({
                   onChange={(e) => {
                     if (e.target.value && pendingAnnotation) {
                       session?.client.mark.submit({
+                        source: resourceId,
                         motivation: 'tagging',
                         selector: pendingAnnotation.selector,
                         body: [

package/src/components/resource/panels/UnifiedAnnotationsPanel.tsx

@@ -59,8 +59,9 @@ interface UnifiedAnnotationsPanelProps {
   referencedBy?: any[];
   referencedByLoading?: boolean;
 
-  // Resource context
-  resourceId?: string;
+  // Resource context — threaded to every per-motivation panel, which stamps it
+  // as `source` on mark:submit (multi-viewer routing).
+  resourceId: string;
   initialTab?: TabKey;
   initialTabGeneration?: number; // Generation counter for tab switching
 
@@ -244,6 +245,7 @@ export function UnifiedAnnotationsPanel(props: UnifiedAnnotationsPanelProps) {
 
           // Common props for all annotation panels
           const commonProps = {
+            resourceId: props.resourceId,
             annotations,
             pendingAnnotation: props.pendingAnnotation,
             isAssisting,
@@ -268,6 +270,7 @@ export function UnifiedAnnotationsPanel(props: UnifiedAnnotationsPanelProps) {
           if (activeTab === 'reference') {
             return (
               <ReferencesPanel
+                resourceId={commonProps.resourceId}
                 annotations={commonProps.annotations}
                 pendingAnnotation={commonProps.pendingAnnotation}
                 isAssisting={commonProps.isAssisting}

package/src/components/resource/panels/__tests__/AssessmentPanel.test.tsx

@@ -140,6 +140,7 @@ const createPendingAnnotation = (exact: string) => ({
 
 describe('AssessmentPanel Component', () => {
   const defaultProps = {
+    resourceId: 'res-1',
     annotations: mockAssessments.empty,
     pendingAnnotation: null,
   };

package/src/components/resource/panels/__tests__/CommentsPanel.test.tsx

@@ -141,6 +141,7 @@ const createPendingAnnotation = (exact: string) => ({
 
 describe('CommentsPanel Component', () => {
   const defaultProps = {
+    resourceId: 'res-1',
     annotations: mockComments.empty,
     pendingAnnotation: null,
   };