@semiont/react-ui 0.5.10 → 0.5.12

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,85 @@
+'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 type { SemiontSession } from '@semiont/sdk';
+import { SvgDrawingCanvas } from '../image-annotation/SvgDrawingCanvas';
+
+// 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[];
+  /**
+   * Session for interaction routing inside annotation-bearing renderers — the
+   * canvases emit clicks/hover via `session.client.browse/beckon`. Absent/null
+   * → the annotations still PAINT, but are inert (paint-only). Threaded by
+   * BrowseView's dispatch; custom renderers may ignore it.
+   */
+  session?: SemiontSession | null;
+}
+
+/** 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, resourceUri, annotations, session }: MediaRendererProps) {
+  // The annotate-mode canvas, read-only (drawingMode=null): paints SvgSelector
+  // shapes over the image and routes click/hover via the session — the same
+  // shapes browse mode silently dropped when this was a bare ImageViewer
+  // (bugs/image-browse-renderer-drops-annotations.md).
+  return (
+    <SvgDrawingCanvas
+      imageUrl={content}
+      resourceUri={resourceUri}
+      existingAnnotations={annotations}
+      drawingMode={null}
+      selectedMotivation={null}
+      session={session}
+    />
+  );
+}
+
+export function PdfBrowseRenderer({ content, resourceUri, annotations, session }: 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}
+        session={session}
+      />
+    </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/AssessmentEntry.tsx

@@ -3,8 +3,7 @@
 import type { Ref } from 'react';
 import type { Annotation } from '@semiont/core';
 import { getAnnotationExactText } from '@semiont/core';
-import { useSemiont } from '../../../session/SemiontProvider';
-import { useObservable } from '../../../hooks/useObservable';
+import type { SemiontSession } from '@semiont/sdk';
 import { useHoverEmitter } from '../../../hooks/useHoverEmitter';
 import { renderAgentLabel } from './agent-label';
 
@@ -17,6 +16,8 @@ interface TextualBody {
 }
 
 interface AssessmentEntryProps {
+  /** Session for interaction routing (browse.click etc.); the panel threads it. */
+  session: SemiontSession | null;
   assessment: Annotation;
   isFocused: boolean;
   isHovered?: boolean;
@@ -69,13 +70,13 @@ function getAssessmentText(annotation: Annotation): string | null {
 }
 
 export function AssessmentEntry({
+  session,
   assessment,
   isFocused,
   isHovered = false,
   ref,
 }: AssessmentEntryProps) {
-  const session = useObservable(useSemiont().activeSession$);
-  const hoverProps = useHoverEmitter(assessment.id);
+  const hoverProps = useHoverEmitter(session, assessment.id);
 
   const selectedText = getAnnotationExactText(assessment);
   const assessmentText = getAssessmentText(assessment);

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

@@ -2,9 +2,8 @@
 
 import { useState, useEffect, useRef, useCallback, useMemo } from 'react';
 import { useTranslations } from '../../../contexts/TranslationContext';
-import { useSemiont } from '../../../session/SemiontProvider';
-import { useObservable } from '../../../hooks/useObservable';
-import { useEventSubscriptions } from '../../../contexts/useEventSubscription';
+import type { SemiontSession } from '@semiont/sdk';
+import { useSessionEventSubscriptions } from '../../../hooks/useSessionEventSubscriptions';
 import type { components, Selector } from '@semiont/core';
 import { getTextPositionSelector, getTargetSelector } from '@semiont/core';
 import { AssessmentEntry } from './AssessmentEntry';
@@ -40,6 +39,10 @@ function getSelectorDisplayText(selector: Selector | Selector[]): string | null
 }
 
 interface AssessmentPanelProps {
+  /** Session carrying the client and event bus; null renders inert. */
+  session: SemiontSession | null;
+  /** 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 +64,8 @@ interface AssessmentPanelProps {
  * @subscribes browse:click - Annotation clicked. Payload: { annotationId: string }
  */
 export function AssessmentPanel({
+  session,
+  resourceId,
   annotations,
   pendingAnnotation,
   isAssisting = false,
@@ -73,7 +78,6 @@ export function AssessmentPanel({
   hoveredAnnotationId,
 }: AssessmentPanelProps) {
   const t = useTranslations('AssessmentPanel');
-  const session = useObservable(useSemiont().activeSession$);
   const [newAssessmentText, setNewAssessmentText] = useState('');
   const [focusedAnnotationId, setFocusedAnnotationId] = useState<string | null>(null);
   const containerRef = useRef<HTMLDivElement>(null);
@@ -151,6 +155,7 @@ export function AssessmentPanel({
         : undefined;
 
       session?.client.mark.submit({
+        source: resourceId,
         motivation: 'assessing',
         selector: pendingAnnotation.selector,
         ...(body !== undefined ? { body } : {}),
@@ -181,7 +186,7 @@ export function AssessmentPanel({
   }, []);
 
   // Subscribe to click events - update focused state
-  useEventSubscriptions({
+  useSessionEventSubscriptions(session, {
     'browse:click': handleAnnotationClick,
   });
 
@@ -243,6 +248,7 @@ export function AssessmentPanel({
         {/* Assist Section - only in Annotate mode and for text resources */}
         {annotateMode && (
           <AssistSection
+            session={session}
             annotationType="assessment"
             isAssisting={isAssisting}
             locale={locale}
@@ -260,6 +266,7 @@ export function AssessmentPanel({
           ) : (
             sortedAnnotations.map((assessment) => (
               <AssessmentEntry
+                session={session}
                 key={assessment.id}
                 assessment={assessment}
                 isFocused={assessment.id === focusedAnnotationId}

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

@@ -2,14 +2,15 @@
 
 import { useState, useEffect, useCallback } from 'react';
 import { useTranslations } from '../../../contexts/TranslationContext';
-import { useSemiont } from '../../../session/SemiontProvider';
-import { useObservable } from '../../../hooks/useObservable';
+import type { SemiontSession } from '@semiont/sdk';
 import type { Motivation, components } from '@semiont/core';
 import './AssistSection.css';
 
 type JobProgress = components['schemas']['JobProgress'];
 
 interface AssistSectionProps {
+  /** Session carrying the client and event bus; null renders inert. */
+  session: SemiontSession | null;
   annotationType: 'highlight' | 'assessment' | 'comment';
   isAssisting: boolean;
   /** User UI locale — written into the annotation body's `language` field for comment/assessment. */
@@ -34,6 +35,7 @@ interface AssistSectionProps {
  * @emits mark:progress-dismiss - Dismiss the annotation progress display
  */
 export function AssistSection({
+  session,
   annotationType,
   isAssisting,
   locale,
@@ -45,7 +47,6 @@ export function AssistSection({
                      annotationType === 'assessment' ? 'AssessmentPanel' :
                      'CommentsPanel';
   const t = useTranslations(panelName);
-  const session = useObservable(useSemiont().activeSession$);
   const [instructions, setInstructions] = useState('');
   type ToneValue = 'scholarly' | 'explanatory' | 'conversational' | 'technical' | 'analytical' | 'critical' | 'balanced' | 'constructive' | '';
   const [tone, setTone] = useState<ToneValue>('');

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

@@ -4,12 +4,13 @@ import { useState, useEffect, useRef, useImperativeHandle, type Ref } from 'reac
 import { useTranslations } from '../../../contexts/TranslationContext';
 import type { Annotation } from '@semiont/core';
 import { getAnnotationExactText, getCommentText } from '@semiont/core';
-import { useSemiont } from '../../../session/SemiontProvider';
-import { useObservable } from '../../../hooks/useObservable';
+import type { SemiontSession } from '@semiont/sdk';
 import { useHoverEmitter } from '../../../hooks/useHoverEmitter';
 import { renderAgentLabel } from './agent-label';
 
 interface CommentEntryProps {
+  /** Session for interaction routing (browse.click etc.); the panel threads it. */
+  session: SemiontSession | null;
   comment: Annotation;
   isFocused: boolean;
   isHovered?: boolean;
@@ -35,6 +36,7 @@ function formatRelativeTime(isoString: string): string {
 }
 
 export function CommentEntry({
+  session,
   comment,
   isFocused,
   isHovered = false,
@@ -42,8 +44,7 @@ export function CommentEntry({
   ref,
 }: CommentEntryProps) {
   const t = useTranslations('CommentsPanel');
-  const session = useObservable(useSemiont().activeSession$);
-  const hoverProps = useHoverEmitter(comment.id);
+  const hoverProps = useHoverEmitter(session, comment.id);
   const [isEditing, setIsEditing] = useState(false);
   const [editText, setEditText] = useState('');
   const internalRef = useRef<HTMLDivElement>(null);

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

@@ -2,9 +2,8 @@
 
 import { useState, useEffect, useRef, useCallback, useMemo } from 'react';
 import { useTranslations } from '../../../contexts/TranslationContext';
-import { useSemiont } from '../../../session/SemiontProvider';
-import { useObservable } from '../../../hooks/useObservable';
-import { useEventSubscriptions } from '../../../contexts/useEventSubscription';
+import type { SemiontSession } from '@semiont/sdk';
+import { useSessionEventSubscriptions } from '../../../hooks/useSessionEventSubscriptions';
 import type { components, Selector } from '@semiont/core';
 import { getTextPositionSelector, getTargetSelector } from '@semiont/core';
 import { CommentEntry } from './CommentEntry';
@@ -40,6 +39,10 @@ function getSelectorDisplayText(selector: Selector | Selector[]): string | null
 }
 
 interface CommentsPanelProps {
+  /** Session carrying the client and event bus; null renders inert. */
+  session: SemiontSession | null;
+  /** 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 +64,8 @@ interface CommentsPanelProps {
  * @subscribes browse:click - Annotation clicked. Payload: { annotationId: string }
  */
 export function CommentsPanel({
+  session,
+  resourceId,
   annotations,
   pendingAnnotation,
   annotateMode = true,
@@ -73,7 +78,6 @@ export function CommentsPanel({
   hoveredAnnotationId,
 }: CommentsPanelProps) {
   const t = useTranslations('CommentsPanel');
-  const session = useObservable(useSemiont().activeSession$);
   const [newCommentText, setNewCommentText] = useState('');
   const [focusedAnnotationId, setFocusedAnnotationId] = useState<string | null>(null);
   const containerRef = useRef<HTMLDivElement>(null);
@@ -164,13 +168,14 @@ export function CommentsPanel({
     setTimeout(() => setFocusedAnnotationId(null), 3000);
   }, []);
 
-  useEventSubscriptions({
+  useSessionEventSubscriptions(session, {
     'browse:click': handleAnnotationClick,
   });
 
   const handleSaveNewComment = () => {
     if (newCommentText.trim() && pendingAnnotation) {
       session?.client.mark.submit({
+        source: resourceId,
         motivation: 'commenting',
         selector: pendingAnnotation.selector,
         body: [{ type: 'TextualBody', value: newCommentText, purpose: 'commenting' }],
@@ -253,6 +258,7 @@ export function CommentsPanel({
         {/* Assist Section - only in Annotate mode and for text resources */}
         {annotateMode && (
           <AssistSection
+            session={session}
             annotationType="comment"
             isAssisting={isAssisting}
             locale={locale}
@@ -270,6 +276,7 @@ export function CommentsPanel({
           ) : (
             sortedAnnotations.map((comment) => (
               <CommentEntry
+                session={session}
                 key={comment.id}
                 comment={comment}
                 isFocused={comment.id === focusedAnnotationId}

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

@@ -3,12 +3,13 @@
 import type { Ref } from 'react';
 import type { Annotation } from '@semiont/core';
 import { getAnnotationExactText } from '@semiont/core';
-import { useSemiont } from '../../../session/SemiontProvider';
-import { useObservable } from '../../../hooks/useObservable';
+import type { SemiontSession } from '@semiont/sdk';
 import { useHoverEmitter } from '../../../hooks/useHoverEmitter';
 import { renderAgentLabel } from './agent-label';
 
 interface HighlightEntryProps {
+  /** Session for interaction routing (browse.click etc.); the panel threads it. */
+  session: SemiontSession | null;
   highlight: Annotation;
   isFocused: boolean;
   isHovered?: boolean;
@@ -33,13 +34,13 @@ function formatRelativeTime(isoString: string): string {
 }
 
 export function HighlightEntry({
+  session,
   highlight,
   isFocused,
   isHovered = false,
   ref,
 }: HighlightEntryProps) {
-  const session = useObservable(useSemiont().activeSession$);
-  const hoverProps = useHoverEmitter(highlight.id);
+  const hoverProps = useHoverEmitter(session, highlight.id);
 
   const selectedText = getAnnotationExactText(highlight);
 

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

@@ -2,9 +2,8 @@
 
 import { useEffect, useState, useRef, useCallback, useMemo } from 'react';
 import { useTranslations } from '../../../contexts/TranslationContext';
-import { useSemiont } from '../../../session/SemiontProvider';
-import { useObservable } from '../../../hooks/useObservable';
-import { useEventSubscriptions } from '../../../contexts/useEventSubscription';
+import type { SemiontSession } from '@semiont/sdk';
+import { useSessionEventSubscriptions } from '../../../hooks/useSessionEventSubscriptions';
 import type { components, Selector } from '@semiont/core';
 import { getTextPositionSelector, getTargetSelector } from '@semiont/core';
 import { HighlightEntry } from './HighlightEntry';
@@ -23,6 +22,10 @@ interface PendingAnnotation {
 }
 
 interface HighlightPanelProps {
+  /** Session carrying the client and event bus; null renders inert. */
+  session: SemiontSession | null;
+  /** 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 +45,8 @@ interface HighlightPanelProps {
  * @subscribes browse:click - Annotation clicked. Payload: { annotationId: string }
  */
 export function HighlightPanel({
+  session,
+  resourceId,
   annotations,
   pendingAnnotation,
   isAssisting = false,
@@ -54,7 +59,6 @@ export function HighlightPanel({
 }: HighlightPanelProps) {
 
   const t = useTranslations('HighlightPanel');
-  const session = useObservable(useSemiont().activeSession$);
   const [focusedAnnotationId, setFocusedAnnotationId] = useState<string | null>(null);
   const containerRef = useRef<HTMLDivElement>(null);
 
@@ -125,7 +129,7 @@ export function HighlightPanel({
     setTimeout(() => setFocusedAnnotationId(null), 3000);
   }, []);
 
-  useEventSubscriptions({
+  useSessionEventSubscriptions(session, {
     'browse:click': handleAnnotationClick,
   });
 
@@ -136,6 +140,7 @@ export function HighlightPanel({
   useEffect(() => {
     if (pendingAnnotation && pendingAnnotation.motivation === 'highlighting') {
       session?.client.mark.submit({
+        source: resourceId,
         motivation: 'highlighting',
         selector: pendingAnnotation.selector,
       });
@@ -151,6 +156,7 @@ export function HighlightPanel({
         {/* Assist Section - only in Annotate mode and for text resources */}
         {annotateMode && (
           <AssistSection
+            session={session}
             annotationType="highlight"
             isAssisting={isAssisting}
             progress={progress}
@@ -167,6 +173,7 @@ export function HighlightPanel({
           ) : (
             sortedAnnotations.map((highlight) => (
               <HighlightEntry
+                session={session}
                 key={highlight.id}
                 highlight={highlight}
                 isFocused={highlight.id === focusedAnnotationId}

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

@@ -1,17 +1,14 @@
 'use client';
 
 import type { Ref } from 'react';
-import type { RouteBuilder } from '../../../contexts/RoutingContext';
 import { useTranslations } from '../../../contexts/TranslationContext';
 import type { Annotation } from '@semiont/core';
 import { resourceId } from '@semiont/core';
 import { getAnnotationExactText, isBodyResolved, getBodySource, getFragmentSelector, getSvgSelector, getTargetSelector } from '@semiont/core';
 import { getEntityTypes } from '@semiont/ontology';
 import { getResourceIcon } from '../../../lib/resource-utils';
-import { useSemiont } from '../../../session/SemiontProvider';
-import { useObservable } from '../../../hooks/useObservable';
+import type { SemiontSession } from '@semiont/sdk';
 import { renderAgentLabel } from './agent-label';
-import { useObservableExternalNavigation } from '../../../hooks/useObservableBrowse';
 import { useHoverEmitter } from '../../../hooks/useHoverEmitter';
 
 // Extended annotation type with runtime properties added by backend enrichment
@@ -21,29 +18,31 @@ interface EnrichedAnnotation extends Annotation {
 }
 
 interface ReferenceEntryProps {
+  /** Session for interaction routing (browse.click etc.); the panel threads it. */
+  session: SemiontSession | null;
   reference: Annotation;
   isFocused: boolean;
   isHovered?: boolean;
-  routes: RouteBuilder;
+  /** Host-owned navigation: called with the resolved resource id when the entry's link opens. */
+  onOpenResource?: (resourceId: string) => void;
   annotateMode?: boolean;
   isGenerating?: boolean;
   ref?: Ref<HTMLDivElement>;
 }
 
 export function ReferenceEntry({
+  session,
   reference,
   isFocused,
   isHovered = false,
-  routes,
+  onOpenResource,
   annotateMode = true,
   isGenerating = false,
   ref,
 }: ReferenceEntryProps) {
   const t = useTranslations('ReferencesPanel');
-  const session = useObservable(useSemiont().activeSession$);
   const semiont = session?.client;
-  const navigate = useObservableExternalNavigation();
-  const hoverProps = useHoverEmitter(reference.id);
+  const hoverProps = useHoverEmitter(session, reference.id);
 
   const selectedText = getAnnotationExactText(reference) || '';
   const isResolved = isBodyResolved(reference.body);
@@ -65,7 +64,7 @@ export function ReferenceEntry({
   const handleOpen = () => {
     if (resolvedResourceUri) {
       // resolvedResourceUri is already a bare resource ID
-      navigate(routes.resourceDetail(resolvedResourceUri), { resourceId: resolvedResourceUri });
+      onOpenResource?.(resolvedResourceUri);
     }
   };
 

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

@@ -2,9 +2,8 @@
 
 import React, { useState, useRef, useEffect, useCallback, useMemo } from 'react';
 import { useTranslations } from '../../../contexts/TranslationContext';
-import { useSemiont } from '../../../session/SemiontProvider';
-import { useObservable } from '../../../hooks/useObservable';
-import { useEventSubscriptions } from '../../../contexts/useEventSubscription';
+import type { SemiontSession } from '@semiont/sdk';
+import { useSessionEventSubscriptions } from '../../../hooks/useSessionEventSubscriptions';
 import type { RouteBuilder, LinkComponentProps } from '../../../contexts/RoutingContext';
 import { AnnotateReferencesProgressWidget } from '../../AnnotateReferencesProgressWidget';
 import { ReferenceEntry } from './ReferenceEntry';
@@ -43,6 +42,12 @@ function getSelectorDisplayText(selector: Selector | Selector[]): string | null
 }
 
 interface Props {
+  /** Session carrying the client and event bus; null renders inert. */
+  session: SemiontSession | null;
+  /** Host-owned navigation: called with the resolved resource id when a reference entry opens. */
+  onOpenResource?: (resourceId: string) => void;
+  /** 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 +81,9 @@ interface Props {
  * @subscribes browse:click - Annotation clicked. Payload: { annotationId: string }
  */
 export function ReferencesPanel({
+  session,
+  onOpenResource,
+  resourceId,
   annotations = [],
   isAssisting,
   progress,
@@ -94,7 +102,6 @@ export function ReferencesPanel({
   sourceLanguage,
 }: Props) {
   const t = useTranslations('ReferencesPanel');
-  const session = useObservable(useSemiont().activeSession$);
   const [selectedEntityTypes, setSelectedEntityTypes] = useState<string[]>([]);
   const [lastAnnotationLog, setLastDetectionLog] = useState<Array<{ entityType: string; foundCount: number }> | null>(null);
   const [pendingEntityTypes, setPendingEntityTypes] = useState<string[]>([]);
@@ -203,7 +210,7 @@ export function ReferencesPanel({
     setTimeout(() => setFocusedAnnotationId(null), 3000);
   }, []);
 
-  useEventSubscriptions({
+  useSessionEventSubscriptions(session, {
     'browse:click': handleAnnotationClick,
   });
 
@@ -255,6 +262,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' }] : [],
@@ -488,11 +496,12 @@ export function ReferencesPanel({
             ) : (
               sortedAnnotations.map((reference) => (
                 <ReferenceEntry
+                  session={session}
                   key={reference.id}
                   reference={reference}
                   isFocused={reference.id === focusedAnnotationId}
                   isHovered={reference.id === hoveredAnnotationId}
-                  routes={routes}
+                  onOpenResource={onOpenResource}
                   annotateMode={annotateMode}
                   isGenerating={reference.id === generatingReferenceId}
                   ref={(el) => setEntryRef(reference.id, el)}