@semiont/react-ui 0.2.33-build.78 → 0.2.33-build.80

package/src/components/resource/ResourceViewer.tsx

@@ -1,115 +1,78 @@
 'use client';
 
-import React, { useState, useEffect, useCallback, useRef, useMemo } from 'react';
-// useRouter removed - using window.location for navigation
+import React, { useState, useEffect, useCallback, useRef } from 'react';
 import { useTranslations } from '../../contexts/TranslationContext';
 import { AnnotateView, type SelectionMotivation, type ClickAction, type ShapeType } from './AnnotateView';
 import { BrowseView } from './BrowseView';
 import { PopupContainer } from '../annotation-popups/SharedPopupElements';
 import { JsonLdView } from '../annotation-popups/JsonLdView';
-import type { components, Selector } from '@semiont/api-client';
+import type { components } from '@semiont/api-client';
 import { getExactText, getTargetSelector, resourceUri, isHighlight, isAssessment, isReference, isComment, isTag, getBodySource } from '@semiont/api-client';
-import { useResourceAnnotations } from '../../contexts/ResourceAnnotationsContext';
-import type { Annotator } from '../../lib/annotation-registry';
+import { useEventBus } from '../../contexts/EventBusContext';
+import { useEventSubscriptions } from '../../contexts/useEventSubscription';
+import { useCacheManager } from '../../contexts/CacheContext';
+import { useObservableExternalNavigation } from '../../hooks/useObservableNavigation';
+import { ANNOTATORS } from '../../lib/annotation-registry';
 import type { AnnotationsCollection } from '../../types/annotation-props';
 import { getSelectorType, getSelectedShapeForSelectorType, saveSelectedShapeForSelectorType } from '../../lib/media-shapes';
 
 type Annotation = components['schemas']['Annotation'];
 type SemiontResource = components['schemas']['ResourceDescriptor'];
-type Motivation = components['schemas']['Motivation'];
-
-// Unified pending annotation type - all human-created annotations flow through this
-interface PendingAnnotation {
-  selector: Selector | Selector[];
-  motivation: Motivation;
-}
 
+/**
+ * ResourceViewer - Display and interact with resource content and annotations
+ *
+ * This component uses event-driven architecture for real-time updates:
+ * - Subscribes to make-meaning events (annotation:added, annotation:removed, annotation:updated)
+ * - Automatically invalidates cache when annotations change
+ * - No manual refetch needed - events handle cache invalidation
+ *
+ * Requirements:
+ * - Must be wrapped in MakeMeaningEventBusProvider (provides event bus)
+ * - Must be wrapped in CacheContext (provides cache manager)
+ *
+ * Event flow:
+ *   make-meaning → EventLog → SSE → EventBus → ResourceViewer → Cache invalidation
+ *
+ * Phase 2 complete: Event-based cache invalidation replaces manual refetch
+ * Phase 3 complete: Fully event-driven - all user interactions use unified event bus
+ */
 interface Props {
   resource: SemiontResource & { content: string };
   annotations: AnnotationsCollection;
-  onRefetchAnnotations?: () => void;
-  annotateMode: boolean;
-  onAnnotateModeToggle: () => void;
   generatingReferenceId?: string | null;
-  onAnnotationHover?: (annotationId: string | null) => void;
-  onCommentHover?: (commentId: string | null) => void;
-  hoveredAnnotationId?: string | null;
-  hoveredCommentId?: string | null;
-  scrollToAnnotationId?: string | null;
   showLineNumbers?: boolean;
-  onAnnotationRequested?: (pending: PendingAnnotation) => void;
-  onCommentCreationRequested?: (selection: { exact: string; start: number; end: number; svgSelector?: string; fragmentSelector?: string; conformsTo?: string }) => void;
-  onTagCreationRequested?: (selection: { exact: string; start: number; end: number; svgSelector?: string; fragmentSelector?: string; conformsTo?: string }) => void;
-  onAssessmentCreationRequested?: (selection: { exact: string; start: number; end: number; svgSelector?: string; fragmentSelector?: string; conformsTo?: string }) => void;
-  onReferenceCreationRequested?: (selection: {
-    exact: string;
-    start: number;
-    end: number;
-    prefix?: string;
-    suffix?: string;
-    svgSelector?: string;
-    fragmentSelector?: string;
-    conformsTo?: string;
-  }) => void;
-  onCommentClick?: (commentId: string) => void;
-  onReferenceClick?: (referenceId: string) => void;
-  onHighlightClick?: (highlightId: string) => void;
-  onAssessmentClick?: (assessmentId: string) => void;
-  onTagClick?: (tagId: string) => void;
-  annotators: Record<string, Annotator>;
+  hoveredAnnotationId?: string | null;
 }
 
+/**
+ * @emits annotation:delete - User requested to delete annotation. Payload: { annotationId: string }
+ * @emits panel:open - Request to open panel with annotation. Payload: { panel: string, scrollToAnnotationId?: string, motivation?: Motivation }
+ *
+ * @subscribes view:mode-toggled - Toggles between browse and annotate mode. Payload: { mode: 'browse' | 'annotate' }
+ * @subscribes annotation:added - New annotation was added. Payload: { annotation: Annotation }
+ * @subscribes annotation:removed - Annotation was removed. Payload: { annotationId: string }
+ * @subscribes annotation:updated - Annotation was updated. Payload: { annotation: Annotation }
+ * @subscribes toolbar:selection-changed - Text selection tool changed. Payload: { selection: boolean }
+ * @subscribes toolbar:click-changed - Click annotation tool changed. Payload: { click: 'detail' | 'scroll' | null }
+ * @subscribes toolbar:shape-changed - Drawing shape changed. Payload: { shape: string }
+ * @subscribes annotation:click - User clicked on annotation. Payload: { annotationId: string }
+ */
 export function ResourceViewer({
   resource,
   annotations,
-  onRefetchAnnotations,
-  annotateMode,
-  onAnnotateModeToggle,
   generatingReferenceId,
-  onAnnotationHover,
-  onCommentHover,
-  hoveredAnnotationId,
-  hoveredCommentId,
-  scrollToAnnotationId,
   showLineNumbers = false,
-  onAnnotationRequested,
-  onCommentCreationRequested,
-  onTagCreationRequested,
-  onAssessmentCreationRequested,
-  onReferenceCreationRequested,
-  onCommentClick,
-  onReferenceClick,
-  onHighlightClick,
-  onAssessmentClick,
-  onTagClick,
-  annotators
+  hoveredAnnotationId: hoveredAnnotationIdProp
 }: Props) {
   const t = useTranslations('ResourceViewer');
   const documentViewerRef = useRef<HTMLDivElement>(null);
 
-  // Use refs for function props to prevent infinite rerenders
-  const onRefetchAnnotationsRef = useRef(onRefetchAnnotations);
-  const onCommentCreationRequestedRef = useRef(onCommentCreationRequested);
-  const onTagCreationRequestedRef = useRef(onTagCreationRequested);
-  const onReferenceCreationRequestedRef = useRef(onReferenceCreationRequested);
-  const onCommentClickRef = useRef(onCommentClick);
-  const onReferenceClickRef = useRef(onReferenceClick);
-  const onHighlightClickRef = useRef(onHighlightClick);
-  const onAssessmentClickRef = useRef(onAssessmentClick);
-  const onTagClickRef = useRef(onTagClick);
-
-  // Keep refs up to date
-  useEffect(() => {
-    onRefetchAnnotationsRef.current = onRefetchAnnotations;
-    onCommentCreationRequestedRef.current = onCommentCreationRequested;
-    onTagCreationRequestedRef.current = onTagCreationRequested;
-    onReferenceCreationRequestedRef.current = onReferenceCreationRequested;
-    onCommentClickRef.current = onCommentClick;
-    onReferenceClickRef.current = onReferenceClick;
-    onHighlightClickRef.current = onHighlightClick;
-    onAssessmentClickRef.current = onAssessmentClick;
-    onTagClickRef.current = onTagClick;
-  });
+  // Get unified event bus for emitting UI events
+  const eventBus = useEventBus();
+
+  // Get observable navigation for event-driven routing
+  const navigate = useObservableExternalNavigation();
 
   const { highlights, references, assessments, comments, tags } = annotations;
 
@@ -131,12 +94,50 @@ export function ResourceViewer({
 
   const mimeType = getMimeType();
 
-  // Use prop directly instead of internal state
+  // Annotate mode state - persisted in localStorage
+  const [annotateMode, setAnnotateMode] = useState<boolean>(() => {
+    if (typeof window !== 'undefined') {
+      return localStorage.getItem('annotateMode') === 'true';
+    }
+    return false;
+  });
+
+  // Persist annotateMode to localStorage
+  useEffect(() => {
+    if (typeof window !== 'undefined') {
+      localStorage.setItem('annotateMode', annotateMode.toString());
+    }
+  }, [annotateMode]);
+
+  // Event handlers (extracted to avoid inline arrow functions)
+  const handleViewModeToggle = useCallback(() => {
+    setAnnotateMode(prev => !prev);
+  }, []);
+
+  // Determine active view based on annotate mode
   const activeView = annotateMode ? 'annotate' : 'browse';
-  const {
-    deleteAnnotation,
-    createAnnotation
-  } = useResourceAnnotations();
+
+  // Event-based cache invalidation - subscribe to make-meaning events
+  // This replaces manual onRefetchAnnotations calls with automatic updates
+  const cacheManager = useCacheManager();
+
+  const handleAnnotationAdded = useCallback(() => {
+    if (cacheManager) {
+      cacheManager.invalidateAnnotations(rUri);
+    }
+  }, [cacheManager, rUri]);
+
+  const handleAnnotationRemoved = useCallback(() => {
+    if (cacheManager) {
+      cacheManager.invalidateAnnotations(rUri);
+    }
+  }, [cacheManager, rUri]);
+
+  const handleAnnotationUpdated = useCallback(() => {
+    if (cacheManager) {
+      cacheManager.invalidateAnnotations(rUri);
+    }
+  }, [cacheManager, rUri]);
 
   // Annotation toolbar state - persisted in localStorage
   const [selectedMotivation, setSelectedMotivation] = useState<SelectionMotivation | null>(() => {
@@ -168,6 +169,19 @@ export function ResourceViewer({
     return getSelectedShapeForSelectorType(selectorType);
   });
 
+  // Toolbar event handlers (extracted to avoid inline arrow functions)
+  const handleToolbarSelectionChanged = useCallback(({ motivation }: { motivation: string | null }) => {
+    setSelectedMotivation(motivation as SelectionMotivation | null);
+  }, []);
+
+  const handleToolbarClickChanged = useCallback(({ action }: { action: string }) => {
+    setSelectedClick(action as ClickAction);
+  }, []);
+
+  const handleToolbarShapeChanged = useCallback(({ shape }: { shape: string }) => {
+    setSelectedShape(shape as ShapeType);
+  }, []);
+
   // Persist toolbar state to localStorage
   useEffect(() => {
     if (selectedMotivation === null) {
@@ -204,8 +218,24 @@ export function ResourceViewer({
     position: { x: number; y: number };
   } | null>(null);
 
+  // Internal UI state for hover, focus, and scroll
+  // Use prop value when provided (controlled by parent), otherwise null
+  const hoveredAnnotationId = hoveredAnnotationIdProp ?? null;
+  const [hoveredCommentId, _setHoveredCommentId] = useState<string | null>(null);
+  const [scrollToAnnotationId, setScrollToAnnotationId] = useState<string | null>(null);
+  const [_focusedAnnotationId, setFocusedAnnotationId] = useState<string | null>(null);
+
+  // Focus annotation helper
+  const focusAnnotation = useCallback((annotationId: string) => {
+    setFocusedAnnotationId(annotationId);
+    setScrollToAnnotationId(annotationId);
+
+    // Clear focus after 3 seconds
+    setTimeout(() => setFocusedAnnotationId(null), 3000);
+  }, []);
+
   // Calculate centered position for JSON-LD modal
-  const jsonLdModalPosition = useMemo(() => {
+  const getJsonLdModalPosition = () => {
     if (typeof window === 'undefined') return { x: 0, y: 0 };
 
     const popupWidth = 800;
@@ -215,47 +245,24 @@ export function ResourceViewer({
       x: Math.max(0, (window.innerWidth - popupWidth) / 2),
       y: Math.max(0, (window.innerHeight - popupHeight) / 2),
     };
-  }, []);
+  };
 
-  // Handle deleting annotations - memoized
-  const handleDeleteAnnotation = useCallback(async (id: string) => {
-    try {
-      await deleteAnnotation(id, rUri);
-      onRefetchAnnotationsRef.current?.();
-    } catch (err) {
-      console.error('Failed to delete annotation:', err);
-    }
-  }, [deleteAnnotation, rUri]);
+  // Handle deleting annotations - emit event instead of direct call
+  const handleDeleteAnnotation = useCallback((id: string) => {
+    eventBus.emit('annotation:delete', { annotationId: id });
+  }, []); // eventBus is stable
 
   // Handle annotation clicks - memoized
   const handleAnnotationClick = useCallback((annotation: Annotation, event?: React.MouseEvent) => {
-    const metadata = Object.values(annotators).find(a => a.matchesAnnotation(annotation));
+    const metadata = Object.values(ANNOTATORS).find(a => a.matchesAnnotation(annotation));
 
     // If annotation has a side panel, only open it when Detail mode is active
     // For delete/jsonld/follow modes, let those handlers below process it
     if (metadata?.hasSidePanel) {
       if (selectedClick === 'detail') {
-        // Route to appropriate panel based on annotation type
-        if (isComment(annotation) && onCommentClickRef.current) {
-          onCommentClickRef.current(annotation.id);
-          return;
-        }
-        if (isReference(annotation) && onReferenceClickRef.current) {
-          onReferenceClickRef.current(annotation.id);
-          return;
-        }
-        if (isHighlight(annotation) && onHighlightClickRef.current) {
-          onHighlightClickRef.current(annotation.id);
-          return;
-        }
-        if (isAssessment(annotation) && onAssessmentClickRef.current) {
-          onAssessmentClickRef.current(annotation.id);
-          return;
-        }
-        if (isTag(annotation) && onTagClickRef.current) {
-          onTagClickRef.current(annotation.id);
-          return;
-        }
+        // Focus annotation (sets internal focus and scroll state, plus calls parent callback for backward compat)
+        focusAnnotation(annotation.id);
+        return;
       }
       // Don't return early for delete/jsonld/follow modes - let them be handled below
       if (selectedClick !== 'deleting' && selectedClick !== 'jsonld' && selectedClick !== 'follow') {
@@ -270,10 +277,10 @@ export function ResourceViewer({
     if (selectedClick === 'follow' && isReference(annotation)) {
       const bodySource = getBodySource(annotation.body);
       if (bodySource) {
-        // Navigate to the linked resource
+        // Navigate to the linked resource - emits 'navigation:external-navigate' event
         const resourceId = bodySource.split('/resources/')[1];
         if (resourceId) {
-          window.location.href = `/know/resource/${resourceId}`;
+          navigate(`/know/resource/${resourceId}`, { resourceId });
         }
       }
       return;
@@ -299,238 +306,79 @@ export function ResourceViewer({
       setDeleteConfirmation({ annotation, position });
       return;
     }
-  }, [annotateMode, selectedClick, handleDeleteAnnotation, annotators]);
-
-  // Unified annotation creation handler - works for both text and images
-  const handleAnnotationCreate = useCallback(async (params: import('../../types/annotation-props').UICreateAnnotationParams) => {
-    const { motivation, selector } = params;
-
-    try {
-      switch (motivation) {
-        case 'highlighting':
-        case 'assessing':
-          // Create highlight/assessment immediately using generic createAnnotation
-          if (selector.type === 'TextQuoteSelector' && selector.exact) {
-            // Build selectors array for text annotation
-            const selectors: any[] = [
-              {
-                type: 'TextQuoteSelector',
-                exact: selector.exact,
-                ...(selector.prefix && { prefix: selector.prefix }),
-                ...(selector.suffix && { suffix: selector.suffix })
-              },
-              {
-                type: 'TextPositionSelector',
-                start: selector.start || 0,
-                end: selector.end || 0
-              }
-            ];
-
-            const annotation = await createAnnotation(
-              rUri,
-              motivation,
-              selectors,
-              []
-            );
-
-            // Focus the new annotation to trigger panel tab switch
-            if (annotation) {
-              if (motivation === 'highlighting' && onHighlightClickRef.current) {
-                onHighlightClickRef.current(annotation.id);
-              } else if (motivation === 'assessing' && onAssessmentClickRef.current) {
-                onAssessmentClickRef.current(annotation.id);
-              }
-            }
-            onRefetchAnnotationsRef.current?.();
-          } else if (selector.type === 'SvgSelector' && selector.value) {
-            // Image annotations use generic createAnnotation
-            await createAnnotation(
-              rUri,
-              motivation,
-              { type: 'SvgSelector', value: selector.value },
-              []
-            );
-            onRefetchAnnotationsRef.current?.();
-          } else if (selector.type === 'FragmentSelector' && selector.value) {
-            // PDF annotations use FragmentSelector
-            await createAnnotation(
-              rUri,
-              motivation,
-              {
-                type: 'FragmentSelector',
-                value: selector.value,
-                ...(selector.conformsTo && { conformsTo: selector.conformsTo })
-              },
-              []
-            );
-            onRefetchAnnotationsRef.current?.();
-          }
-          break;
-
-        case 'commenting':
-          if (selector.type === 'TextQuoteSelector' && selector.exact) {
-            // Text: notify parent to open Comments Panel
-            if (onCommentCreationRequestedRef.current) {
-              onCommentCreationRequestedRef.current({
-                exact: selector.exact,
-                start: selector.start || 0,
-                end: selector.end || 0
-              });
-            }
-          } else if (selector.type === 'SvgSelector' && selector.value) {
-            // Image: create annotation, then open panel
-            const annotation = await createAnnotation(
-              rUri,
-              motivation,
-              { type: 'SvgSelector', value: selector.value },
-              []
-            );
-            if (annotation && onCommentClickRef.current) {
-              onCommentClickRef.current(annotation.id);
-            }
-            onRefetchAnnotationsRef.current?.();
-          } else if (selector.type === 'FragmentSelector' && selector.value) {
-            // PDF: create annotation, then open panel
-            const annotation = await createAnnotation(
-              rUri,
-              motivation,
-              {
-                type: 'FragmentSelector',
-                value: selector.value,
-                ...(selector.conformsTo && { conformsTo: selector.conformsTo })
-              },
-              []
-            );
-            if (annotation && onCommentClickRef.current) {
-              onCommentClickRef.current(annotation.id);
-            }
-            onRefetchAnnotationsRef.current?.();
-          }
-          break;
-
-        case 'tagging':
-          if (selector.type === 'TextQuoteSelector' && selector.exact) {
-            // Text: notify parent to open Tags Panel
-            if (onTagCreationRequestedRef.current) {
-              onTagCreationRequestedRef.current({
-                exact: selector.exact,
-                start: selector.start || 0,
-                end: selector.end || 0
-              });
-            }
-          } else if (selector.type === 'SvgSelector' && selector.value) {
-            // Image: create annotation, then open panel
-            const annotation = await createAnnotation(
-              rUri,
-              motivation,
-              { type: 'SvgSelector', value: selector.value },
-              []
-            );
-            if (annotation && onTagClickRef.current) {
-              onTagClickRef.current(annotation.id);
-            }
-            onRefetchAnnotationsRef.current?.();
-          } else if (selector.type === 'FragmentSelector' && selector.value) {
-            // PDF: create annotation, then open panel
-            const annotation = await createAnnotation(
-              rUri,
-              motivation,
-              {
-                type: 'FragmentSelector',
-                value: selector.value,
-                ...(selector.conformsTo && { conformsTo: selector.conformsTo })
-              },
-              []
-            );
-            if (annotation && onTagClickRef.current) {
-              onTagClickRef.current(annotation.id);
-            }
-            onRefetchAnnotationsRef.current?.();
-          }
-          break;
-
-        case 'linking':
-          // Call onReferenceCreationRequested for text, image, and PDF selections
-          if (onReferenceCreationRequestedRef.current) {
-            if (selector.type === 'TextQuoteSelector' && selector.exact) {
-              const selection = {
-                exact: selector.exact,
-                start: selector.start || 0,
-                end: selector.end || 0,
-                ...(selector.prefix && { prefix: selector.prefix }),
-                ...(selector.suffix && { suffix: selector.suffix })
-              };
-              onReferenceCreationRequestedRef.current(selection);
-            } else if (selector.type === 'SvgSelector' && selector.value) {
-              const selection = {
-                exact: '',  // Images don't have exact text
-                start: 0,
-                end: 0,
-                svgSelector: selector.value
-              };
-              onReferenceCreationRequestedRef.current(selection);
-            } else if (selector.type === 'FragmentSelector' && selector.value) {
-              const selection = {
-                exact: '',  // PDFs don't have exact text
-                start: 0,
-                end: 0,
-                fragmentSelector: selector.value,
-                ...(selector.conformsTo && { conformsTo: selector.conformsTo })
-              };
-              onReferenceCreationRequestedRef.current(selection);
-            }
-          }
-          break;
+  }, [annotateMode, selectedClick, focusAnnotation]);
+
+  // Annotation click coordinator - handles panel opening and scrolling
+  const handleAnnotationClickEvent = useCallback(({ annotationId, motivation }: {
+    annotationId: string;
+    motivation: components['schemas']['Motivation'];
+  }) => {
+    // Find the annotation metadata
+    const metadata = Object.values(ANNOTATORS).find(a => a.matchesAnnotation({ motivation } as Annotation));
+
+    if (!metadata?.hasSidePanel) {
+      // Annotation doesn't have a side panel - let handleAnnotationClick handle it
+      const allAnnotations = [...highlights, ...references, ...assessments, ...comments, ...tags];
+      const annotation = allAnnotations.find(a => a.id === annotationId);
+      if (annotation) {
+        handleAnnotationClick(annotation);
       }
-    } catch (err) {
-      console.error('Failed to create annotation:', err);
+      return;
     }
-  }, [rUri, createAnnotation]);
 
-  // Quick action: Delete annotation from widget
-  const handleDeleteAnnotationWidget = useCallback(async (annotation: Annotation) => {
-    await handleDeleteAnnotation(annotation.id);
-  }, [handleDeleteAnnotation]);
-
-  // Memoize objects to prevent infinite re-renders
-  const annotationsCollection = useMemo(
-    () => ({ highlights, references, assessments, comments, tags }),
-    [highlights, references, assessments, comments, tags]
-  );
+    if (selectedClick !== 'detail') {
+      // Only open panels in detail mode - for other modes, let handleAnnotationClick handle it
+      const allAnnotations = [...highlights, ...references, ...assessments, ...comments, ...tags];
+      const annotation = allAnnotations.find(a => a.id === annotationId);
+      if (annotation) {
+        handleAnnotationClick(annotation);
+      }
+      return;
+    }
 
-  const handlersForAnnotate = useMemo(
-    () => ({
-      onClick: handleAnnotationClick,
-      ...(onAnnotationHover && { onHover: onAnnotationHover }),
-      ...(onCommentHover && { onCommentHover })
-    }),
-    [handleAnnotationClick, onAnnotationHover, onCommentHover]
-  );
+    // All annotations open the unified annotations panel
+    // The panel internally switches tabs based on the motivation → tab mapping in UnifiedAnnotationsPanel
+    eventBus.emit('panel:open', { panel: 'annotations', scrollToAnnotationId: annotationId, motivation });
+  }, [highlights, references, assessments, comments, tags, handleAnnotationClick, selectedClick]);
+
+  // Event subscriptions - Combined into single useEventSubscriptions call to prevent hook ordering issues
+  // IMPORTANT: All event subscriptions MUST be in a single call to maintain consistent hook order between renders
+  useEventSubscriptions({
+    // View mode
+    'view:mode-toggled': handleViewModeToggle,
+
+    // Annotation cache invalidation
+    'annotation:added': handleAnnotationAdded,
+    'annotation:removed': handleAnnotationRemoved,
+    'annotation:updated': handleAnnotationUpdated,
+
+    // Toolbar state
+    'toolbar:selection-changed': handleToolbarSelectionChanged,
+    'toolbar:click-changed': handleToolbarClickChanged,
+    'toolbar:shape-changed': handleToolbarShapeChanged,
+
+    // Annotation clicks
+    'annotation:click': handleAnnotationClickEvent,
+  });
 
-  const handlersForBrowse = useMemo(
-    () => ({
-      onClick: handleAnnotationClick,
-      ...(onCommentHover && { onCommentHover })
-    }),
-    [handleAnnotationClick, onCommentHover]
-  );
+  // Prepare props for child components
+  // Note: These objects are created inline - React's reconciliation handles re-renders efficiently
+  const annotationsCollection = { highlights, references, assessments, comments, tags };
 
-  const creationHandler = useMemo(
-    () => ({ onCreate: handleAnnotationCreate }),
-    [handleAnnotationCreate]
-  );
+  const uiState = {
+    selectedMotivation,
+    selectedClick,
+    selectedShape,
+    hoveredAnnotationId,
+    scrollToAnnotationId
+  };
 
-  const uiState = useMemo(
-    () => ({
-      selectedMotivation,
-      selectedClick,
-      selectedShape,
-      ...(hoveredAnnotationId !== undefined && { hoveredAnnotationId }),
-      ...(hoveredCommentId !== undefined && { hoveredCommentId }),
-      ...(scrollToAnnotationId !== undefined && { scrollToAnnotationId })
-    }),
-    [selectedMotivation, selectedClick, selectedShape, hoveredAnnotationId, hoveredCommentId, scrollToAnnotationId]
-  );
+  // Define getTargetDocumentName callback OUTSIDE the conditional
+  // IMPORTANT: This must be defined before the return statement to avoid hook ordering violations
+  const getTargetDocumentName = useCallback((documentId: string) => {
+    const referencedResource = references.find((a: Annotation) => getBodySource(a.body) === documentId);
+    return referencedResource ? getExactText(getTargetSelector(referencedResource.target)) : undefined;
+  }, [references]);
 
   return (
     <div ref={documentViewerRef} className="semiont-resource-viewer">
@@ -541,8 +389,6 @@ export function ResourceViewer({
           mimeType={mimeType}
           resourceUri={resource['@id']}
           annotations={annotationsCollection}
-          handlers={handlersForAnnotate}
-          creationHandler={creationHandler}
           uiState={uiState}
           onUIStateChange={(updates) => {
             if ('selectedMotivation' in updates) setSelectedMotivation(updates.selectedMotivation!);
@@ -550,21 +396,10 @@ export function ResourceViewer({
             if ('selectedShape' in updates) setSelectedShape(updates.selectedShape!);
           }}
           enableWidgets={true}
-          onEntityTypeClick={(entityType) => {
-            window.location.href = `/know?entityType=${encodeURIComponent(entityType)}`;
-          }}
-          onUnresolvedReferenceClick={handleAnnotationClick}
+          getTargetDocumentName={getTargetDocumentName}
           {...(generatingReferenceId !== undefined && { generatingReferenceId })}
-          onDeleteAnnotation={handleDeleteAnnotationWidget}
           showLineNumbers={showLineNumbers}
           annotateMode={annotateMode}
-          onAnnotateModeToggle={onAnnotateModeToggle}
-          {...(onAnnotationRequested && { onAnnotationRequested })}
-          {...(onCommentCreationRequested && { onCommentCreationRequested })}
-          {...(onTagCreationRequested && { onTagCreationRequested })}
-          {...(onAssessmentCreationRequested && { onAssessmentCreationRequested })}
-          {...(onReferenceCreationRequested && { onReferenceCreationRequested })}
-          annotators={annotators}
         />
       ) : (
         <BrowseView
@@ -572,13 +407,9 @@ export function ResourceViewer({
           mimeType={mimeType}
           resourceUri={resource['@id']}
           annotations={annotationsCollection}
-          handlers={handlersForBrowse}
-          {...(hoveredCommentId !== undefined && { hoveredCommentId })}
+          hoveredCommentId={hoveredCommentId}
           selectedClick={selectedClick}
-          onClickChange={setSelectedClick}
           annotateMode={annotateMode}
-          onAnnotateModeToggle={onAnnotateModeToggle}
-          annotators={annotators}
         />
       )}
 
@@ -587,7 +418,7 @@ export function ResourceViewer({
         <PopupContainer
           isOpen={showJsonLdView}
           onClose={() => setShowJsonLdView(false)}
-          position={jsonLdModalPosition}
+          position={getJsonLdModalPosition()}
           wide={true}
         >
           <JsonLdView
@@ -603,7 +434,7 @@ export function ResourceViewer({
       {/* Delete Confirmation Modal */}
       {deleteConfirmation && (() => {
         const annotation = deleteConfirmation.annotation;
-        const metadata = Object.values(annotators).find(a => a.matchesAnnotation(annotation));
+        const metadata = Object.values(ANNOTATORS).find(a => a.matchesAnnotation(annotation));
         const targetSelector = getTargetSelector(annotation.target);
         const selectedText = getExactText(targetSelector);
         const motivationEmoji = metadata?.iconEmoji || '📝';
@@ -641,8 +472,8 @@ export function ResourceViewer({
                 {t('deleteConfirmationCancel')}
               </button>
               <button
-                onClick={async () => {
-                  await handleDeleteAnnotation(deleteConfirmation.annotation.id);
+                onClick={() => {
+                  handleDeleteAnnotation(deleteConfirmation.annotation.id);
                   setDeleteConfirmation(null);
                 }}
                 className="semiont-button semiont-button--danger"