@semiont/react-ui 0.2.33-build.79 → 0.2.33-build.81

package/dist/index.d.mts

@@ -1,10 +1,10 @@
 import * as _semiont_api_client from '@semiont/api-client';
-import { components, ResourceUri, Selector, SemiontApiClient, AnnotationUri, ResourceAnnotationUri, ValidationResult, DetectionProgress as DetectionProgress$1, GenerationProgress as GenerationProgress$1, GenerationContext, paths } from '@semiont/api-client';
+import { components, ResourceUri, Selector, SemiontApiClient, SSEStream, AnnotationUri, ResourceAnnotationUri, ValidationResult, paths, Motivation as Motivation$9, GenerationContext } from '@semiont/api-client';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React$1 from 'react';
 import React__default, { ComponentType, ReactNode, MutableRefObject, KeyboardEvent as KeyboardEvent$1, Component, ErrorInfo } from 'react';
-import { A as ApiClientManager, O as OpenResourcesManager, S as SessionManager, T as TranslationManager } from './TranslationManager-Co_5fSxl.mjs';
-export { a as OpenResourceFromManager, b as SessionState } from './TranslationManager-Co_5fSxl.mjs';
+import { D as DetectionProgress, E as EventBus, a as EventMap, O as OpenResourcesManager, S as SessionManager, T as TranslationManager, G as GenerationProgress } from './EventBusContext-CJjL_cCf.mjs';
+export { e as EventBusProvider, d as EventBusProviderProps, b as OpenResourceFromManager, c as SessionState, r as resetEventBusForTesting, u as useEventBus } from './EventBusContext-CJjL_cCf.mjs';
 import * as _tanstack_react_query from '@tanstack/react-query';
 import { UseQueryOptions } from '@tanstack/react-query';
 import * as _codemirror_state from '@codemirror/state';
@@ -16,19 +16,19 @@ import { VFile } from 'vfile';
 import { TagSchema } from '@semiont/ontology';
 export { TAG_SCHEMAS, TagCategory, TagSchema, getAllTagSchemas, getSchemaCategory as getTagCategory, getTagSchema, getTagSchemasByDomain, isValidCategory } from '@semiont/ontology';
 import { ResourceEvent, StoredEvent } from '@semiont/core';
-import mitt from 'mitt';
+import { Emitter } from 'mitt';
 
-type Annotation$p = components['schemas']['Annotation'];
+type Annotation$m = components['schemas']['Annotation'];
 /**
  * Collection of all annotation types for a resource.
  * Replaces separate highlights, references, assessments, comments, tags props.
  */
 interface AnnotationsCollection {
-    highlights: Annotation$p[];
-    references: Annotation$p[];
-    assessments: Annotation$p[];
-    comments: Annotation$p[];
-    tags: Annotation$p[];
+    highlights: Annotation$m[];
+    references: Annotation$m[];
+    assessments: Annotation$m[];
+    comments: Annotation$m[];
+    tags: Annotation$m[];
 }
 /**
  * Event handlers for annotation interactions.
@@ -36,7 +36,7 @@ interface AnnotationsCollection {
  */
 interface AnnotationHandlers {
     /** Unified click handler - routes based on annotation type and current mode */
-    onClick?: (annotation: Annotation$p, event?: React.MouseEvent) => void;
+    onClick?: (annotation: Annotation$m, event?: React.MouseEvent) => void;
     /** Unified hover handler for all annotation types */
     onHover?: (annotationId: string | null) => void;
     /** Hover handler specifically for comment panel highlighting */
@@ -85,7 +85,7 @@ interface UICreateAnnotationParams {
  * - linking: Shows Quick Reference popup FIRST, creates when user confirms
  */
 interface AnnotationCreationHandler {
-    onCreate?: (params: UICreateAnnotationParams) => void | Promise<void> | Promise<Annotation$p | undefined>;
+    onCreate?: (params: UICreateAnnotationParams) => void | Promise<void> | Promise<Annotation$m | undefined>;
 }
 /**
  * UI state for annotation toolbar and interactions.
@@ -120,7 +120,7 @@ interface AnnotationConfig {
     annotateMode?: boolean;
 }
 
-type Annotation$o = components['schemas']['Annotation'];
+type Annotation$l = components['schemas']['Annotation'];
 /**
  * Parameters for creating an annotation
  */
@@ -167,7 +167,7 @@ interface AnnotationManager {
      * @param params - Creation parameters (rUri, motivation, selector, body)
      * @returns Promise resolving to the created annotation, or undefined if creation fails
      */
-    createAnnotation: (params: CreateAnnotationParams) => Promise<Annotation$o | undefined>;
+    createAnnotation: (params: CreateAnnotationParams) => Promise<Annotation$l | undefined>;
     /**
      * Delete an annotation
      * @param params - Deletion parameters (annotationId, rUri)
@@ -270,9 +270,9 @@ interface NavigationProps {
  * Type definitions for resource viewer feature
  */
 
-type SemiontResource$3 = components['schemas']['ResourceDescriptor'];
-type Annotation$n = components['schemas']['Annotation'];
-type Motivation$b = components['schemas']['Motivation'];
+type SemiontResource$4 = components['schemas']['ResourceDescriptor'];
+type Annotation$k = components['schemas']['Annotation'];
+type Motivation$8 = components['schemas']['Motivation'];
 /**
  * Selection for creating annotations
  */
@@ -299,17 +299,17 @@ interface TextSelection {
  * No aliasing, wrappers, or compatibility layers elsewhere.
  */
 
-type Annotation$m = components['schemas']['Annotation'];
-type Motivation$a = components['schemas']['Motivation'];
+type Annotation$j = components['schemas']['Annotation'];
+type Motivation$7 = components['schemas']['Motivation'];
 /**
  * Detection configuration for SSE-based annotation detection
  */
 interface DetectionConfig {
-    sseMethod: 'detectAnnotations' | 'detectHighlights' | 'detectAssessments' | 'detectComments' | 'detectTags';
+    sseMethod: 'detectReferences' | 'detectHighlights' | 'detectAssessments' | 'detectComments' | 'detectTags';
     countField: 'foundCount' | 'createdCount' | 'tagsCreated';
     displayNamePlural: string;
     displayNameSingular: string;
-    formatRequestParams?: (args: any[]) => Array<{
+    formatRequestParams?: (args: unknown[]) => Array<{
         label: string;
         value: string;
     }>;
@@ -327,7 +327,7 @@ interface CreateConfig {
  * Handles clicks, hovers, detection, and other operations for one annotation type
  */
 interface Annotator {
-    motivation: Motivation$a;
+    motivation: Motivation$7;
     internalType: string;
     displayName: string;
     description: string;
@@ -336,7 +336,7 @@ interface Annotator {
     isClickable: boolean;
     hasHoverInteraction: boolean;
     hasSidePanel: boolean;
-    matchesAnnotation: (annotation: Annotation$m) => boolean;
+    matchesAnnotation: (annotation: Annotation$j) => boolean;
     announceOnCreate: string;
     detection?: DetectionConfig;
     create: CreateConfig;
@@ -353,23 +353,23 @@ declare const ANNOTATORS: Record<string, Annotator>;
  * (handleDetectHighlights, handleDetectAssessments, etc.)
  */
 declare function createDetectionHandler(annotator: Annotator, context: {
-    client: any;
-    rUri: any;
-    setDetectingMotivation: (motivation: Motivation$a | null) => void;
-    setMotivationDetectionProgress: (progress: any) => void;
-    detectionStreamRef: MutableRefObject<any>;
+    client: SemiontApiClient;
+    rUri: ResourceUri;
+    setDetectingMotivation: (motivation: Motivation$7 | null) => void;
+    setMotivationDetectionProgress: (progress: DetectionProgress | null) => void;
+    detectionStreamRef: MutableRefObject<SSEStream<DetectionProgress, object> | null>;
     cacheManager: CacheManager;
     showSuccess: (message: string) => void;
     showError: (message: string) => void;
-}): (...args: any[]) => Promise<void>;
+}): (...args: unknown[]) => Promise<void>;
 /**
  * Generic detection cancellation handler
  * Cancels any active detection stream
  */
 declare function createCancelDetectionHandler(context: {
-    detectionStreamRef: MutableRefObject<any>;
-    setDetectingMotivation: (motivation: Motivation$a | null) => void;
-    setMotivationDetectionProgress: (progress: any) => void;
+    detectionStreamRef: MutableRefObject<SSEStream<DetectionProgress, object> | null>;
+    setDetectingMotivation: (motivation: Motivation$7 | null) => void;
+    setMotivationDetectionProgress: (progress: DetectionProgress | null) => void;
 }): () => void;
 
 /**
@@ -407,6 +407,9 @@ declare function useResources(): {
             referencedBy: any[];
         }, Error>;
     };
+    representation: {
+        useQuery: (rUri: ResourceUri, mediaType: string) => _tanstack_react_query.UseQueryResult<string, Error>;
+    };
     search: {
         useQuery: (query: string, limit: number) => _tanstack_react_query.UseQueryResult<{
             resources: _semiont_api_client.components["schemas"]["ResourceDescriptor"][];
@@ -448,7 +451,7 @@ declare function useResources(): {
         }, Error, ResourceUri, unknown>;
     };
     getByToken: {
-        useQuery: (token: string) => _tanstack_react_query.UseQueryResult<{
+        useQuery: (cloneTokenStr: string) => _tanstack_react_query.UseQueryResult<{
             sourceResource: _semiont_api_client.components["schemas"]["ResourceDescriptor"];
             expiresAt: string;
         }, Error>;
@@ -540,7 +543,10 @@ declare function useAnnotations(): {
         }, unknown>;
     };
     delete: {
-        useMutation: () => _tanstack_react_query.UseMutationResult<void, Error, ResourceAnnotationUri, unknown>;
+        useMutation: () => _tanstack_react_query.UseMutationResult<void, Error, {
+            annotationUri: ResourceAnnotationUri;
+            resourceUri: ResourceUri;
+        }, unknown>;
     };
     updateBody: {
         useMutation: () => _tanstack_react_query.UseMutationResult<{
@@ -815,18 +821,17 @@ declare const jsonLightHighlightStyle: HighlightStyle;
  * - Entity type badges
  */
 
-type Annotation$l = components['schemas']['Annotation'];
+type Annotation$i = components['schemas']['Annotation'];
 /**
  * Reference Resolution Widget
  * Shows a small indicator next to references with hover preview
  */
 declare class ReferenceResolutionWidget extends WidgetType {
-    readonly annotation: Annotation$l;
+    readonly annotation: Annotation$i;
     readonly targetDocumentName?: string | undefined;
-    readonly onNavigate?: ((documentId: string) => void) | undefined;
-    readonly onUnresolvedClick?: ((annotation: Annotation$l) => void) | undefined;
+    readonly eventBus?: EventBus | undefined;
     readonly isGenerating?: boolean | undefined;
-    constructor(annotation: Annotation$l, targetDocumentName?: string | undefined, onNavigate?: ((documentId: string) => void) | undefined, onUnresolvedClick?: ((annotation: Annotation$l) => void) | undefined, isGenerating?: boolean | undefined);
+    constructor(annotation: Annotation$i, targetDocumentName?: string | undefined, eventBus?: EventBus | undefined, isGenerating?: boolean | undefined);
     eq(other: ReferenceResolutionWidget): boolean;
     toDOM(): HTMLSpanElement;
     private showPreview;
@@ -840,19 +845,23 @@ type ShapeType = 'rectangle' | 'circle' | 'polygon';
 interface AnnotateToolbarProps {
     selectedMotivation: SelectionMotivation | null;
     selectedClick: ClickAction;
-    onSelectionChange: (motivation: SelectionMotivation | null) => void;
-    onClickChange: (motivation: ClickAction) => void;
     showSelectionGroup?: boolean;
     showDeleteButton?: boolean;
     showShapeGroup?: boolean;
     selectedShape?: ShapeType;
-    onShapeChange?: (shape: ShapeType) => void;
     mediaType?: string | null;
     annotateMode: boolean;
-    onAnnotateModeToggle: () => void;
     annotators: Record<string, Annotator>;
 }
-declare function AnnotateToolbar({ selectedMotivation, selectedClick, onSelectionChange, onClickChange, showSelectionGroup, showDeleteButton, showShapeGroup, selectedShape, onShapeChange, mediaType, annotateMode, onAnnotateModeToggle, annotators }: AnnotateToolbarProps): react_jsx_runtime.JSX.Element;
+/**
+ * Toolbar for annotation controls with mode, selection, click, and shape options
+ *
+ * @emits toolbar:selection-changed - Selection motivation changed. Payload: { motivation: SelectionMotivation | null }
+ * @emits toolbar:click-changed - Click action mode changed. Payload: { action: ClickAction }
+ * @emits toolbar:shape-changed - Drawing shape changed. Payload: { shape: ShapeType }
+ * @emits view:mode-toggled - View mode toggled between browse and annotate. Payload: undefined
+ */
+declare function AnnotateToolbar({ selectedMotivation, selectedClick, showSelectionGroup, showDeleteButton, showShapeGroup, selectedShape, mediaType, annotateMode, annotators }: AnnotateToolbarProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Media Type Shape Support
@@ -933,6 +942,7 @@ declare const QUERY_KEYS: {
         events: (rUri: ResourceUri) => readonly ["resources", ResourceUri, "events"];
         annotations: (rUri: ResourceUri) => readonly ["resources", ResourceUri, "annotations"];
         referencedBy: (rUri: ResourceUri) => readonly ["resources", ResourceUri, "referenced-by"];
+        representation: (rUri: ResourceUri) => readonly ["resources", ResourceUri, "representation"];
     };
     annotations: {
         detail: (aUri: AnnotationUri) => readonly ["annotations", AnnotationUri];
@@ -951,21 +961,6 @@ declare const QUERY_KEYS: {
             config: () => readonly ["admin", "oauth", "config"];
         };
     };
-    documents: {
-        all: (limit?: number, archived?: boolean) => readonly ["resources", {
-            readonly limit: number | undefined;
-            readonly archived: boolean | undefined;
-        }];
-        detail: (rUri: ResourceUri) => readonly ["resources", ResourceUri];
-        byToken: (token: string) => readonly ["resources", "by-token", string];
-        search: (query: string, limit: number) => readonly ["resources", "search", {
-            readonly query: string;
-            readonly limit: number;
-        }];
-        events: (rUri: ResourceUri) => readonly ["resources", ResourceUri, "events"];
-        annotations: (rUri: ResourceUri) => readonly ["resources", ResourceUri, "annotations"];
-        referencedBy: (rUri: ResourceUri) => readonly ["resources", ResourceUri, "referenced-by"];
-    };
 };
 
 declare function rehypeRenderAnnotations(): (tree: Root, file: any) => void;
@@ -1057,23 +1052,6 @@ declare const OAuthUserSchema: {
  */
 declare function sanitizeImageURL(url: string): string | null;
 
-type Annotation$k = components['schemas']['Annotation'];
-/**
- * Shared logic for annotation panel components
- *
- * Handles:
- * - Sorting annotations by position in the resource
- * - Hover effects: scroll to annotation and pulse highlight
- * - Ref management for annotation elements
- *
- * Used by: HighlightPanel, AssessmentPanel, CommentsPanel, ReferencesPanel
- */
-declare function useAnnotationPanel<T extends Annotation$k>(annotations: T[], hoveredId: string | null | undefined): {
-    sortedAnnotations: T[];
-    containerRef: React$1.RefObject<HTMLDivElement>;
-    handleAnnotationRef: (id: string, el: HTMLElement | null) => void;
-};
-
 /**
  * Creates a debounced version of a callback function
  *
@@ -1103,79 +1081,7 @@ declare function useDebouncedCallback<T extends (...args: any[]) => any>(callbac
  */
 declare function useDebounce<T>(value: T, delay: number): T;
 
-interface DetectionProgress extends DetectionProgress$1 {
-    completedEntityTypes?: Array<{
-        entityType: string;
-        foundCount: number;
-    }>;
-}
-interface UseDetectionProgressOptions {
-    rUri: ResourceUri;
-    onComplete?: (progress: DetectionProgress) => void;
-    onError?: (error: string) => void;
-    onProgress?: (progress: DetectionProgress) => void;
-}
-declare function useDetectionProgress({ rUri, onComplete, onError, onProgress }: UseDetectionProgressOptions): {
-    isDetecting: boolean;
-    progress: DetectionProgress | null;
-    startDetection: (entityTypes: string[]) => Promise<void>;
-    cancelDetection: () => void;
-};
-
-declare function useFormattedTime(milliseconds: number | null): string | null;
-
-interface UseFormValidationOptions {
-    announceErrors?: boolean;
-}
-declare function useFormValidation(options?: UseFormValidationOptions): {
-    errors: Record<string, string>;
-    setFieldError: (field: string, message: string) => void;
-    clearFieldError: (field: string) => void;
-    clearAllErrors: () => void;
-    validateField: (field: string, value: any, rules: Record<string, (value: any) => string | null>) => boolean;
-    announceSuccess: (message: string) => void;
-    getFieldError: (field: string) => string | null;
-    hasErrors: () => boolean;
-    getFieldProps: (fieldName: string) => {
-        'aria-invalid': boolean;
-        'aria-describedby': string | undefined;
-        id: string;
-    };
-    getErrorProps: (fieldName: string) => {
-        id: string;
-        role: string;
-        'aria-live': string;
-    };
-};
-declare const validationRules: {
-    required: (message?: string) => (value: any) => string | null;
-    minLength: (min: number, message?: string) => (value: string) => string | null;
-    maxLength: (max: number, message?: string) => (value: string) => string | null;
-    email: (message?: string) => (value: string) => string | null;
-    url: (message?: string) => (value: string) => string | null;
-    pattern: (regex: RegExp, message: string) => (value: string) => string | null;
-};
-
-type GenerationProgress = GenerationProgress$1;
-interface UseGenerationProgressOptions {
-    onComplete?: (progress: GenerationProgress) => void;
-    onError?: (error: string) => void;
-    onProgress?: (progress: GenerationProgress) => void;
-}
-declare function useGenerationProgress({ onComplete, onError, onProgress }: UseGenerationProgressOptions): {
-    isGenerating: boolean;
-    progress: GenerationProgress$1 | null;
-    startGeneration: (referenceId: AnnotationUri, resourceId: ResourceUri, options: {
-        title?: string;
-        prompt?: string;
-        language?: string;
-        context: GenerationContext;
-        temperature?: number;
-        maxTokens?: number;
-    }) => Promise<void>;
-    cancelGeneration: () => void;
-    clearProgress: () => void;
-};
+declare function formatTime(milliseconds: number | null): string | null;
 
 interface KeyboardShortcut {
     key: string;
@@ -1214,6 +1120,75 @@ declare function useLineNumbers(): {
     toggleLineNumbers: () => void;
 };
 
+/**
+ * Generic router interface - works with any router that has push/replace methods
+ * (Next.js App Router, Next.js Pages Router, React Router, etc.)
+ */
+interface Router {
+    push: (path: string) => void;
+    replace?: (path: string) => void;
+    [key: string]: any;
+}
+/**
+ * Hook that wraps any router with event emission for observability
+ *
+ * Use this to wrap your router (Next.js, React Router, etc.) when you want
+ * navigation actions to be observable through the NavigationEventBus.
+ *
+ * @emits navigation:router-push - Router navigation requested. Payload: { path: string, reason?: string }
+ *
+ * @example
+ * ```typescript
+ * // Next.js App Router
+ * import { useRouter } from 'next/navigation';
+ * const nextRouter = useRouter();
+ * const router = useObservableRouter(nextRouter);
+ * router.push('/know/discover', { reason: 'resource-closed' });
+ *
+ * // React Router
+ * import { useNavigate } from 'react-router-dom';
+ * const navigate = useNavigate();
+ * const router = useObservableRouter({ push: navigate });
+ * router.push('/know/discover', { reason: 'resource-closed' });
+ * ```
+ */
+declare function useObservableRouter<T extends Router>(baseRouter: T): T;
+/**
+ * Request navigation with event emission
+ *
+ * This hook emits a navigation request event. The app must subscribe to
+ * 'navigation:external-navigate' and perform the actual navigation using
+ * its router (Next.js, React Router, etc.) to enable client-side routing.
+ *
+ * If no subscriber handles the event, falls back to window.location.href
+ * after a brief delay to allow for event handling.
+ *
+ * @emits navigation:external-navigate - External navigation requested. Payload: { url: string, resourceId?: string, cancelFallback: () => void }
+ *
+ * The payload includes a `cancelFallback` function that subscribers must call to
+ * prevent the window.location fallback from firing. Subscribers that handle the
+ * navigation (e.g. via client-side routing) should always call cancelFallback().
+ *
+ * @example
+ * ```typescript
+ * // In component (react-ui package)
+ * const navigate = useObservableExternalNavigation();
+ * navigate('/know/resource/123', { resourceId: '123' });
+ *
+ * // In app (frontend package) - subscribe, cancel fallback, and handle with Next.js router
+ * const router = useRouter();
+ * useEventSubscriptions({
+ *   'navigation:external-navigate': ({ url, cancelFallback }) => {
+ *     cancelFallback(); // Prevent window.location fallback
+ *     router.push(url); // Client-side navigation
+ *   },
+ * });
+ * ```
+ */
+declare function useObservableExternalNavigation(): (url: string, metadata?: {
+    resourceId?: string;
+}) => void;
+
 interface UsePanelWidthOptions {
     defaultWidth?: number;
     minWidth?: number;
@@ -1329,27 +1304,16 @@ declare function useSessionExpiry(): {
 
 type Theme = 'light' | 'dark' | 'system';
 type ResolvedTheme = 'light' | 'dark';
-declare function useTheme(): {
+interface ThemeContextValue {
     theme: Theme;
-    setTheme: (newTheme: Theme) => void;
+    setTheme: (theme: Theme) => void;
     resolvedTheme: ResolvedTheme;
     systemTheme: ResolvedTheme;
-};
-
-type ToolbarPanelType = 'document' | 'history' | 'info' | 'annotations' | 'settings' | 'collaboration' | 'user' | 'jsonld';
-interface UseToolbarOptions {
-    /** Initial panel to show (default: null) */
-    initialPanel?: ToolbarPanelType | null;
-    /** Whether to persist active panel to localStorage (default: false) */
-    persistToStorage?: boolean;
-    /** Storage key for persistence (default: 'activeToolbarPanel') */
-    storageKey?: string;
 }
-declare function useToolbar(options?: UseToolbarOptions): {
-    activePanel: ToolbarPanelType | null;
-    togglePanel: (panel: ToolbarPanelType) => void;
-    setActivePanel: React$1.Dispatch<React$1.SetStateAction<ToolbarPanelType | null>>;
-};
+declare function ThemeProvider({ children }: {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useTheme(): ThemeContextValue;
 
 /**
  * Hook for managing dropdown/menu visibility with click outside handling
@@ -1375,6 +1339,19 @@ declare function useLoadingState(minLoadingTime?: number): {
  */
 declare function useLocalStorage<T>(key: string, initialValue: T): [T, (value: T | ((val: T) => T)) => void];
 
+type SemiontResource$3 = components['schemas']['ResourceDescriptor'];
+interface UseResourceContentResult {
+    content: string;
+    loading: boolean;
+}
+/**
+ * Hook to load resource content (representation)
+ *
+ * Fetches the primary representation of a resource based on its media type.
+ * Uses React Query for caching, deduplication, and consistent loading state.
+ */
+declare function useResourceContent(rUri: ResourceUri, resource: SemiontResource$3): UseResourceContentResult;
+
 interface AnnotationProviderProps {
     annotationManager: AnnotationManager;
     children: React__default.ReactNode;
@@ -1388,6 +1365,8 @@ interface AnnotationProviderProps {
  * Example usage:
  * ```typescript
  * // In app (apps/frontend/src/hooks/useAnnotationManager.ts)
+ * import { uriToAnnotationIdOrPassthrough } from '@semiont/core';
+ *
  * function useAnnotationManager(): AnnotationManager {
  *   const annotations = useAnnotations();
  *   const createMutation = annotations.create.useMutation();
@@ -1402,7 +1381,7 @@ interface AnnotationProviderProps {
  *       return result.annotation;
  *     },
  *     deleteAnnotation: async (params) => {
- *       const annotationIdSegment = params.annotationId.split('/').pop() || params.annotationId;
+ *       const annotationIdSegment = uriToAnnotationIdOrPassthrough(params.annotationId);
  *       await deleteMutation.mutateAsync(resourceAnnotationUri(`${params.rUri}/annotations/${annotationIdSegment}`));
  *     }
  *   };
@@ -1424,51 +1403,42 @@ declare function AnnotationProvider({ annotationManager, children }: AnnotationP
  */
 declare function useAnnotationManager(): AnnotationManager;
 
-interface AnnotationUIContextType {
-    newAnnotationIds: Set<string>;
-    clearNewAnnotationId: (id: AnnotationUri) => void;
-    triggerSparkleAnimation: (annotationId: string) => void;
-}
-interface AnnotationUIProviderProps {
-    children: React__default.ReactNode;
+interface ApiClientProviderProps {
+    baseUrl: string;
+    children: ReactNode;
 }
 /**
- * Annotation UI Provider
- *
- * Manages UI-only state for annotation interactions (sparkle animations).
- * This is NOT part of the Provider Pattern - it's internal react-ui state management.
- *
- * Usage:
- * ```typescript
- * <AnnotationUIProvider>
- *   <ResourceViewer ... />
- * </AnnotationUIProvider>
- * ```
+ * Provider for API client - creates a stateless singleton client
+ * The client instance never changes (no token dependency)
+ * Auth tokens are passed per-request via useAuthToken() in calling code
  */
-declare function AnnotationUIProvider({ children }: AnnotationUIProviderProps): react_jsx_runtime.JSX.Element;
+declare function ApiClientProvider({ baseUrl: url, children, }: ApiClientProviderProps): react_jsx_runtime.JSX.Element;
 /**
- * Hook to access annotation UI state
- *
- * @throws Error if used outside AnnotationUIProvider
- * @returns AnnotationUI context
+ * Hook to access the stateless API client singleton
+ * Must be used within an ApiClientProvider
+ * @returns Stateless SemiontApiClient instance
  */
-declare function useAnnotationUI(): AnnotationUIContextType;
+declare function useApiClient(): SemiontApiClient;
 
-interface ApiClientProviderProps {
-    apiClientManager: ApiClientManager;
+interface AuthTokenProviderProps {
+    token: string | null;
     children: ReactNode;
 }
 /**
- * Provider for API client management
- * Apps must provide an ApiClientManager implementation
+ * Provider for auth token
+ * Pass the current token value - React handles the rest
  */
-declare function ApiClientProvider({ apiClientManager, children, }: ApiClientProviderProps): react_jsx_runtime.JSX.Element;
+declare function AuthTokenProvider({ token, children, }: AuthTokenProviderProps): react_jsx_runtime.JSX.Element;
 /**
- * Hook to access the API client
- * Must be used within an ApiClientProvider
- * @returns API client instance (null if not authenticated)
+ * Hook to get current auth token
+ *
+ * Returns the current token value from context.
+ * Re-renders automatically when token changes (normal React behavior).
+ *
+ * @returns Current access token (null if not authenticated)
+ * @throws Error if used outside AuthTokenProvider
  */
-declare function useApiClient(): _semiont_api_client.SemiontApiClient | null;
+declare function useAuthToken(): string | null;
 
 interface CacheProviderProps {
     cacheManager: CacheManager;
@@ -1512,60 +1482,56 @@ declare function CacheProvider({ cacheManager, children }: CacheProviderProps):
  */
 declare function useCacheManager(): CacheManager;
 
-/**
- * Selection data for annotation creation
- */
-interface SelectionData {
-    exact: string;
-    start: number;
-    end: number;
-    svgSelector?: string;
-    fragmentSelector?: string;
-    conformsTo?: string;
-    prefix?: string;
-    suffix?: string;
+interface ResolutionFlowConfig {
+    client: SemiontApiClient;
+    resourceUri: ResourceUri;
 }
-type EventBus = ReturnType<typeof mitt<MakeMeaningEventMap>>;
-interface MakeMeaningEventBusProviderProps {
-    rUri: ResourceUri;
-    children: ReactNode;
+interface ResolutionFlowState {
+    searchModalOpen: boolean;
+    pendingReferenceId: string | null;
+    onCloseSearchModal: () => void;
 }
 /**
- * Unified event bus provider for all events (backend + UI)
+ * Hook that handles the Resolution capability: resolving reference annotations
+ * to existing resources (search) or new resources (manual creation).
  *
- * Backend events: Make-meaning's event-sourced domain events from SSE
- * UI events: Local user interactions (enables real-time collaboration)
+ * Handles: annotation:update-body, reference:link, resolution:search-requested
  *
- * This unified bus allows:
- * 1. Components to emit UI events (selections, requests)
- * 2. Other components to react to those events
- * 3. Backend events to flow through the same bus
- * 4. Foundation for peer-to-peer real-time collaboration
+ * @param emitter - The mitt event bus instance
+ * @param config - Configuration including API client and resource URI
+ * @returns Resolution flow state (search modal open state and close handler)
  */
-declare function MakeMeaningEventBusProvider({ rUri, children }: MakeMeaningEventBusProviderProps): react_jsx_runtime.JSX.Element;
+declare function useResolutionFlow(emitter: Emitter<EventMap>, config: ResolutionFlowConfig): ResolutionFlowState;
+
 /**
- * Hook to access make-meaning event bus
+ * Subscribe to an event bus event with automatic cleanup.
  *
- * Use this to subscribe to make-meaning's domain events directly.
- * Think in detection, generation, annotation semantics - not HTTP.
+ * This hook solves the "stale closure" problem by always using the latest
+ * version of the handler without re-subscribing.
  *
  * @example
- * ```typescript
- * const eventBus = useMakeMeaningEvents();
- *
- * useEffect(() => {
- *   // Listen to make-meaning's detection progress
- *   const handler = (event) => {
- *     console.log('Make-meaning is detecting:', event.payload.currentStep);
- *     console.log('Found so far:', event.payload.foundCount);
- *   };
+ * ```tsx
+ * useEventSubscription('annotation:created', ({ annotation }) => {
+ *   // This always uses the latest props/state
+ *   triggerSparkleAnimation(annotation.id);
+ * });
+ * ```
+ */
+declare function useEventSubscription<K extends keyof EventMap>(eventName: K, handler: (payload: EventMap[K]) => void): void;
+/**
+ * Subscribe to multiple events at once.
  *
- *   eventBus.on('detection:progress', handler);
- *   return () => eventBus.off('detection:progress', handler);
- * }, [eventBus]);
+ * @example
+ * ```tsx
+ * useEventSubscriptions({
+ *   'annotation:created': ({ annotation }) => setNewAnnotation(annotation),
+ *   'annotation:deleted': ({ annotationId }) => removeAnnotation(annotationId),
+ * });
  * ```
  */
-declare function useMakeMeaningEvents(): EventBus;
+declare function useEventSubscriptions(subscriptions: {
+    [K in keyof EventMap]?: (payload: EventMap[K]) => void;
+}): void;
 
 /**
  * Provider Pattern: Accepts OpenResourcesManager implementation as prop
@@ -1594,11 +1560,10 @@ declare function OpenResourcesProvider({ openResourcesManager, children }: {
  */
 declare function useOpenResources(): OpenResourcesManager;
 
-type Annotation$j = components['schemas']['Annotation'];
+type Annotation$h = components['schemas']['Annotation'];
 interface ResourceAnnotationsContextType {
     newAnnotationIds: Set<string>;
-    createAnnotation: (rUri: ResourceUri, motivation: 'highlighting' | 'linking' | 'assessing' | 'commenting' | 'tagging', selector: Selector | Selector[], body?: any[]) => Promise<Annotation$j | undefined>;
-    deleteAnnotation: (annotationId: string, rUri: ResourceUri) => Promise<void>;
+    createAnnotation: (rUri: ResourceUri, motivation: 'highlighting' | 'linking' | 'assessing' | 'commenting' | 'tagging', selector: Selector | Selector[], body?: any[]) => Promise<Annotation$h | undefined>;
     clearNewAnnotationId: (id: AnnotationUri) => void;
     triggerSparkleAnimation: (annotationId: string) => void;
 }
@@ -1741,18 +1706,16 @@ declare function usePreloadTranslations(): {
     isLoaded: (locale: string) => boolean;
 };
 
-type Annotation$i = components['schemas']['Annotation'];
+type Annotation$g = components['schemas']['Annotation'];
 interface TextSegment {
     exact: string;
-    annotation?: Annotation$i;
+    annotation?: Annotation$g;
     start: number;
     end: number;
 }
 interface Props$b {
     content: string;
-    segments: TextSegment[];
-    onAnnotationClick?: (annotation: Annotation$i) => void;
-    onAnnotationHover?: (annotationId: string | null) => void;
+    segments?: TextSegment[];
     onTextSelect?: (exact: string, position: {
         start: number;
         end: number;
@@ -1766,23 +1729,23 @@ interface Props$b {
     sourceView?: boolean;
     showLineNumbers?: boolean;
     enableWidgets?: boolean;
-    onEntityTypeClick?: (entityType: string) => void;
-    onReferenceNavigate?: (documentId: string) => void;
-    onUnresolvedReferenceClick?: (annotation: Annotation$i) => void;
+    eventBus?: EventBus;
     getTargetDocumentName?: (documentId: string) => string | undefined;
     generatingReferenceId?: string | null;
-    onDeleteAnnotation?: (annotation: Annotation$i) => void;
-    annotators: Record<string, Annotator>;
 }
-declare function CodeMirrorRenderer({ content, segments, onAnnotationClick, onAnnotationHover, onChange, editable, newAnnotationIds, hoveredAnnotationId, hoveredCommentId, scrollToAnnotationId, sourceView, showLineNumbers, enableWidgets, onEntityTypeClick, onReferenceNavigate, onUnresolvedReferenceClick, getTargetDocumentName, generatingReferenceId, onDeleteAnnotation, annotators }: Props$b): react_jsx_runtime.JSX.Element;
+declare function CodeMirrorRenderer({ content, segments, onChange, editable, newAnnotationIds, hoveredAnnotationId, hoveredCommentId, scrollToAnnotationId, sourceView, showLineNumbers, enableWidgets, eventBus, getTargetDocumentName, generatingReferenceId }: Props$b): react_jsx_runtime.JSX.Element;
 
-type Motivation$9 = components['schemas']['Motivation'];
+type Motivation$6 = components['schemas']['Motivation'];
 interface DetectionProgressWidgetProps {
     progress: DetectionProgress | null;
-    onCancel?: () => void;
-    annotationType?: Motivation$9 | 'reference';
+    annotationType?: Motivation$6 | 'reference';
 }
-declare function DetectionProgressWidget({ progress, onCancel, annotationType }: DetectionProgressWidgetProps): react_jsx_runtime.JSX.Element | null;
+/**
+ * Widget for displaying detection progress with cancel functionality
+ *
+ * @emits job:cancel-requested - User requested to cancel detection job. Payload: { jobType: string }
+ */
+declare function DetectionProgressWidget({ progress, annotationType }: DetectionProgressWidgetProps): react_jsx_runtime.JSX.Element | null;
 
 interface Props$a {
     children: ReactNode;
@@ -1812,7 +1775,7 @@ declare function AsyncErrorBoundary({ children }: {
     children: ReactNode;
 }): react_jsx_runtime.JSX.Element;
 
-type Annotation$h = components['schemas']['Annotation'];
+type Annotation$f = components['schemas']['Annotation'];
 interface LiveRegionContextType {
     announce: (message: string, priority?: 'polite' | 'assertive') => void;
 }
@@ -1828,9 +1791,9 @@ declare function useSearchAnnouncements(): {
 declare function useDocumentAnnouncements(annotators?: Record<string, Annotator>): {
     announceDocumentSaved: () => void;
     announceDocumentDeleted: () => void;
-    announceAnnotationCreated: (annotation: Annotation$h) => void;
+    announceAnnotationCreated: (annotation: Annotation$f) => void;
     announceAnnotationDeleted: () => void;
-    announceAnnotationUpdated: (annotation: Annotation$h) => void;
+    announceAnnotationUpdated: (annotation: Annotation$f) => void;
     announceError: (message: string) => void;
 };
 declare function useResourceLoadingAnnouncements(): {
@@ -1924,25 +1887,33 @@ type ToolbarContext = 'document' | 'simple';
 interface Props$9<T extends string = string> {
     context: ToolbarContext;
     activePanel: T | null;
-    onPanelToggle: (panel: T) => void;
     isArchived?: boolean;
 }
-declare function Toolbar<T extends string = string>({ context, activePanel, onPanelToggle, isArchived }: Props$9<T>): react_jsx_runtime.JSX.Element;
+/**
+ * Toolbar component for panel navigation
+ *
+ * @emits panel:toggle - Toggle panel visibility. Payload: { panel: string }
+ */
+declare function Toolbar<T extends string = string>({ context, activePanel, isArchived }: Props$9<T>): react_jsx_runtime.JSX.Element;
 
 interface SettingsPanelProps {
     showLineNumbers: boolean;
-    onLineNumbersToggle: () => void;
     theme: 'light' | 'dark' | 'system';
-    onThemeChange: (theme: 'light' | 'dark' | 'system') => void;
     locale: string;
-    onLocaleChange: (locale: string) => void;
     isPendingLocaleChange?: boolean;
 }
-declare function SettingsPanel({ showLineNumbers, onLineNumbersToggle, theme, onThemeChange, locale, onLocaleChange, isPendingLocaleChange }: SettingsPanelProps): react_jsx_runtime.JSX.Element;
+/**
+ * Settings panel for application preferences
+ *
+ * @emits settings:locale-changed - Locale changed by user. Payload: { locale: string }
+ * @emits settings:line-numbers-toggled - Line numbers toggled on/off. Payload: undefined
+ * @emits settings:theme-changed - Theme changed by user. Payload: { theme: 'light' | 'dark' | 'system' }
+ */
+declare function SettingsPanel({ showLineNumbers, theme, locale, isPendingLocaleChange }: SettingsPanelProps): react_jsx_runtime.JSX.Element;
 
-type Annotation$g = components['schemas']['Annotation'];
+type Annotation$e = components['schemas']['Annotation'];
 interface JsonLdViewProps {
-    annotation: Annotation$g;
+    annotation: Annotation$e;
     onBack: () => void;
 }
 declare function JsonLdView({ annotation, onBack }: JsonLdViewProps): react_jsx_runtime.JSX.Element;
@@ -1973,40 +1944,43 @@ interface PopupContainerProps {
 }
 declare function PopupContainer({ children, position, onClose, isOpen, wide }: PopupContainerProps): react_jsx_runtime.JSX.Element;
 
-type Annotation$f = components['schemas']['Annotation'];
+type Annotation$d = components['schemas']['Annotation'];
 interface AnnotationOverlayProps {
-    annotations: Annotation$f[];
+    annotations: Annotation$d[];
     imageWidth: number;
     imageHeight: number;
     displayWidth: number;
     displayHeight: number;
-    onAnnotationClick?: (annotation: Annotation$f) => void;
-    onAnnotationHover?: (annotationId: string | null) => void;
+    eventBus?: EventBus;
     hoveredAnnotationId?: string | null;
     selectedAnnotationId?: string | null;
 }
 /**
  * Render annotation overlay - displays existing annotations as SVG shapes
+ *
+ * @emits annotation:hover - Annotation hovered or unhovered. Payload: { annotationId: string | null }
+ * @emits annotation:click - Annotation clicked. Payload: { annotationId: string, motivation: Motivation }
  */
-declare function AnnotationOverlay({ annotations, imageWidth, imageHeight, displayWidth, displayHeight, onAnnotationClick, onAnnotationHover, hoveredAnnotationId, selectedAnnotationId }: AnnotationOverlayProps): react_jsx_runtime.JSX.Element;
+declare function AnnotationOverlay({ annotations, imageWidth, imageHeight, displayWidth, displayHeight, eventBus, hoveredAnnotationId, selectedAnnotationId }: AnnotationOverlayProps): react_jsx_runtime.JSX.Element;
 
-type Annotation$e = components['schemas']['Annotation'];
+type Annotation$c = components['schemas']['Annotation'];
 type DrawingMode = 'rectangle' | 'polygon' | 'circle' | 'freeform' | null;
 interface SvgDrawingCanvasProps {
     resourceUri: ResourceUri;
-    existingAnnotations?: Annotation$e[];
+    existingAnnotations?: Annotation$c[];
     drawingMode: DrawingMode;
     selectedMotivation?: SelectionMotivation | null;
-    onAnnotationCreate?: (svg: string, position?: {
-        x: number;
-        y: number;
-    }) => void;
-    onAnnotationClick?: (annotation: Annotation$e) => void;
-    onAnnotationHover?: (annotationId: string | null) => void;
+    eventBus?: EventBus;
     hoveredAnnotationId?: string | null;
     selectedAnnotationId?: string | null;
 }
-declare function SvgDrawingCanvas({ resourceUri, existingAnnotations, drawingMode, selectedMotivation, onAnnotationCreate, onAnnotationClick, onAnnotationHover, hoveredAnnotationId, selectedAnnotationId }: SvgDrawingCanvasProps): react_jsx_runtime.JSX.Element;
+/**
+ * SVG-based drawing canvas for creating image annotations with shapes
+ *
+ * @emits annotation:click - Annotation clicked on canvas. Payload: { annotationId: string, motivation: Motivation }
+ * @emits annotation:requested - New annotation drawn on canvas. Payload: { selector: SvgSelector, motivation: SelectionMotivation }
+ */
+declare function SvgDrawingCanvas({ resourceUri, existingAnnotations, drawingMode, selectedMotivation, eventBus, hoveredAnnotationId, selectedAnnotationId }: SvgDrawingCanvasProps): react_jsx_runtime.JSX.Element;
 
 interface KeyboardShortcutsHelpModalProps {
     isOpen: boolean;
@@ -2021,37 +1995,30 @@ interface ProposeEntitiesModalProps {
 }
 declare function ProposeEntitiesModal({ isOpen, onConfirm, onCancel }: ProposeEntitiesModalProps): react_jsx_runtime.JSX.Element;
 
-type Annotation$d = components['schemas']['Annotation'];
-type Motivation$8 = components['schemas']['Motivation'];
-interface PendingAnnotation$7 {
-    selector: Selector | Selector[];
-    motivation: Motivation$8;
-}
-
 interface Props$8 {
     content: string;
     mimeType?: string;
     resourceUri?: string;
     annotations: AnnotationsCollection;
-    handlers?: AnnotationHandlers;
-    creationHandler?: AnnotationCreationHandler;
     uiState: AnnotationUIState;
     onUIStateChange?: (state: Partial<AnnotationUIState>) => void;
     editable?: boolean;
     enableWidgets?: boolean;
-    onEntityTypeClick?: (entityType: string) => void;
-    onReferenceNavigate?: (documentId: string) => void;
-    onUnresolvedReferenceClick?: (annotation: Annotation$d) => void;
     getTargetDocumentName?: (documentId: string) => string | undefined;
     generatingReferenceId?: string | null;
-    onDeleteAnnotation?: (annotation: Annotation$d) => void;
     showLineNumbers?: boolean;
     annotateMode: boolean;
-    onAnnotateModeToggle: () => void;
-    onAnnotationRequested?: (pending: PendingAnnotation$7) => void;
-    annotators: Record<string, Annotator>;
 }
-declare function AnnotateView({ content, mimeType, resourceUri, annotations, handlers, creationHandler, uiState, onUIStateChange, enableWidgets, onEntityTypeClick, onReferenceNavigate, onUnresolvedReferenceClick, getTargetDocumentName, generatingReferenceId, onDeleteAnnotation, showLineNumbers, annotateMode, onAnnotateModeToggle, onAnnotationRequested, annotators }: Props$8): react_jsx_runtime.JSX.Element;
+/**
+ * View component for annotating resources with text selection and drawing
+ *
+ * @emits annotation:requested - User requested to create annotation. Payload: { selector: Selector | Selector[], motivation: SelectionMotivation }
+ * @subscribes toolbar:selection-changed - Toolbar selection changed. Payload: { motivation: string | null }
+ * @subscribes toolbar:click-changed - Toolbar click action changed. Payload: { action: string }
+ * @subscribes toolbar:shape-changed - Toolbar shape changed. Payload: { shape: string }
+ * @subscribes annotation:hover - Annotation hovered. Payload: { annotationId: string | null }
+ */
+declare function AnnotateView({ content, mimeType, resourceUri, annotations, uiState, onUIStateChange, enableWidgets, getTargetDocumentName, generatingReferenceId, showLineNumbers, annotateMode }: Props$8): react_jsx_runtime.JSX.Element;
 
 interface Props$7 {
     rUri: ResourceUri;
@@ -2068,16 +2035,21 @@ interface Props$6 {
     mimeType: string;
     resourceUri: string;
     annotations: AnnotationsCollection;
-    handlers?: AnnotationHandlers;
     hoveredAnnotationId?: string | null;
     hoveredCommentId?: string | null;
     selectedClick?: ClickAction;
-    onClickChange?: (motivation: ClickAction) => void;
     annotateMode: boolean;
-    onAnnotateModeToggle: () => void;
-    annotators: Record<string, Annotator>;
 }
-declare function BrowseView({ content, mimeType, resourceUri, annotations, handlers, hoveredAnnotationId, hoveredCommentId, selectedClick, onClickChange, annotateMode, onAnnotateModeToggle, annotators }: Props$6): react_jsx_runtime.JSX.Element;
+/**
+ * View component for browsing annotated resources in read-only mode
+ *
+ * @emits annotation:click - User clicked on annotation. Payload: { annotationId: string, motivation: Motivation }
+ * @emits annotation:hover - User hovered over annotation. Payload: { annotationId: string | null }
+ *
+ * @subscribes annotation:hover - Highlight annotation on hover. Payload: { annotationId: string | null }
+ * @subscribes annotation:focus - Scroll to and highlight annotation. Payload: { annotationId: string }
+ */
+declare function BrowseView({ content, mimeType, resourceUri, annotations, selectedClick, annotateMode }: Props$6): react_jsx_runtime.JSX.Element;
 
 type TranslateFn$4 = (key: string, params?: Record<string, string | number>) => string;
 interface Props$5 {
@@ -2095,11 +2067,6 @@ interface Props$5 {
 declare function HistoryEvent({ event, annotations, allEvents, isRelated, t, Link, routes, onEventRef, onEventClick, onEventHover }: Props$5): react_jsx_runtime.JSX.Element;
 
 type SemiontResource$2 = components['schemas']['ResourceDescriptor'];
-type Motivation$7 = components['schemas']['Motivation'];
-interface PendingAnnotation$6 {
-    selector: Selector | Selector[];
-    motivation: Motivation$7;
-}
 /**
  * ResourceViewer - Display and interact with resource content and annotations
  *
@@ -2125,36 +2092,40 @@ interface Props$4 {
     annotations: AnnotationsCollection;
     generatingReferenceId?: string | null;
     showLineNumbers?: boolean;
-    onAnnotationRequested?: (pending: PendingAnnotation$6) => void;
-    annotators: Record<string, Annotator>;
+    hoveredAnnotationId?: string | null;
 }
-declare function ResourceViewer({ resource, annotations, generatingReferenceId, showLineNumbers, onAnnotationRequested, annotators }: Props$4): react_jsx_runtime.JSX.Element;
+/**
+ * @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 }
+ */
+declare function ResourceViewer({ resource, annotations, generatingReferenceId, showLineNumbers, hoveredAnnotationId: hoveredAnnotationIdProp }: Props$4): react_jsx_runtime.JSX.Element;
 
-type Annotation$c = components['schemas']['Annotation'];
+type Annotation$b = components['schemas']['Annotation'];
 interface AssessmentEntryProps {
-    assessment: Annotation$c;
+    assessment: Annotation$b;
     isFocused: boolean;
-    onClick: () => void;
-    onAssessmentRef: (assessmentId: string, el: HTMLElement | null) => void;
-    onAssessmentHover?: (assessmentId: string | null) => void;
+    isHovered?: boolean;
 }
-declare function AssessmentEntry({ assessment, isFocused, onClick, onAssessmentRef, onAssessmentHover, }: AssessmentEntryProps): react_jsx_runtime.JSX.Element;
+declare const AssessmentEntry: React$1.ForwardRefExoticComponent<AssessmentEntryProps & React$1.RefAttributes<HTMLDivElement>>;
 
-type Annotation$b = components['schemas']['Annotation'];
-type Motivation$6 = components['schemas']['Motivation'];
-interface PendingAnnotation$5 {
+type Annotation$a = components['schemas']['Annotation'];
+type Motivation$5 = components['schemas']['Motivation'];
+interface PendingAnnotation$6 {
     selector: Selector | Selector[];
-    motivation: Motivation$6;
+    motivation: Motivation$5;
 }
 interface AssessmentPanelProps {
-    annotations: Annotation$b[];
-    onAnnotationClick: (annotation: Annotation$b) => void;
-    focusedAnnotationId: string | null;
-    hoveredAnnotationId?: string | null;
-    onAnnotationHover?: (annotationId: string | null) => void;
-    onCreate: (assessmentText: string) => void;
-    pendingAnnotation: PendingAnnotation$5 | null;
-    onDetect?: (instructions?: string) => void | Promise<void>;
+    annotations: Annotation$a[];
+    pendingAnnotation: PendingAnnotation$6 | null;
     isDetecting?: boolean;
     detectionProgress?: {
         status: string;
@@ -2162,8 +2133,18 @@ interface AssessmentPanelProps {
         message?: string;
     } | null;
     annotateMode?: boolean;
+    scrollToAnnotationId?: string | null;
+    onScrollCompleted?: () => void;
+    hoveredAnnotationId?: string | null;
 }
-declare function AssessmentPanel({ annotations, onAnnotationClick, focusedAnnotationId, hoveredAnnotationId, onAnnotationHover, onCreate, pendingAnnotation, onDetect, isDetecting, detectionProgress, annotateMode, }: AssessmentPanelProps): react_jsx_runtime.JSX.Element;
+/**
+ * Panel for managing assessment annotations with text input
+ *
+ * @emits annotation:create - Create new assessment annotation. Payload: { motivation: 'assessing', selector: Selector | Selector[], body: Body[] }
+ * @emits annotation:cancel-pending - Cancel pending assessment annotation. Payload: undefined
+ * @subscribes annotation:click - Annotation clicked. Payload: { annotationId: string }
+ */
+declare function AssessmentPanel({ annotations, pendingAnnotation, isDetecting, detectionProgress, annotateMode, scrollToAnnotationId, onScrollCompleted, hoveredAnnotationId, }: AssessmentPanelProps): react_jsx_runtime.JSX.Element;
 
 interface Props$3 {
     isConnected: boolean;
@@ -2172,41 +2153,43 @@ interface Props$3 {
 }
 declare function CollaborationPanel({ isConnected, eventCount, lastEventTimestamp }: Props$3): react_jsx_runtime.JSX.Element;
 
-type Annotation$a = components['schemas']['Annotation'];
+type Annotation$9 = components['schemas']['Annotation'];
 interface CommentEntryProps {
-    comment: Annotation$a;
+    comment: Annotation$9;
     isFocused: boolean;
-    onClick: () => void;
-    onCommentRef: (commentId: string, el: HTMLElement | null) => void;
-    onCommentHover?: (commentId: string | null) => void;
+    isHovered?: boolean;
     annotateMode?: boolean;
 }
-declare function CommentEntry({ comment, isFocused, onClick, onCommentRef, onCommentHover, annotateMode, }: CommentEntryProps): react_jsx_runtime.JSX.Element;
+declare const CommentEntry: React$1.ForwardRefExoticComponent<CommentEntryProps & React$1.RefAttributes<HTMLDivElement>>;
 
-type Annotation$9 = components['schemas']['Annotation'];
-type Motivation$5 = components['schemas']['Motivation'];
-interface PendingAnnotation$4 {
+type Annotation$8 = components['schemas']['Annotation'];
+type Motivation$4 = components['schemas']['Motivation'];
+interface PendingAnnotation$5 {
     selector: Selector | Selector[];
-    motivation: Motivation$5;
+    motivation: Motivation$4;
 }
 interface CommentsPanelProps {
-    annotations: Annotation$9[];
-    onAnnotationClick: (annotation: Annotation$9) => void;
-    onCreate: (commentText: string) => void;
-    focusedAnnotationId: string | null;
-    hoveredAnnotationId?: string | null;
-    onAnnotationHover?: (annotationId: string | null) => void;
-    pendingAnnotation: PendingAnnotation$4 | null;
+    annotations: Annotation$8[];
+    pendingAnnotation: PendingAnnotation$5 | null;
     annotateMode?: boolean;
-    onDetect?: (instructions?: string, tone?: string) => void | Promise<void>;
     isDetecting?: boolean;
     detectionProgress?: {
         status: string;
         percentage?: number;
         message?: string;
     } | null;
+    scrollToAnnotationId?: string | null;
+    onScrollCompleted?: () => void;
+    hoveredAnnotationId?: string | null;
 }
-declare function CommentsPanel({ annotations, onAnnotationClick, onCreate, focusedAnnotationId, hoveredAnnotationId, onAnnotationHover, pendingAnnotation, annotateMode, onDetect, isDetecting, detectionProgress, }: CommentsPanelProps): react_jsx_runtime.JSX.Element;
+/**
+ * Panel for managing comment annotations with text input
+ *
+ * @emits annotation:create - Create new comment annotation. Payload: { motivation: 'commenting', selector: Selector | Selector[], body: Body[] }
+ * @emits annotation:cancel-pending - Cancel pending comment annotation. Payload: undefined
+ * @subscribes annotation:click - Annotation clicked. Payload: { annotationId: string }
+ */
+declare function CommentsPanel({ annotations, pendingAnnotation, annotateMode, isDetecting, detectionProgress, scrollToAnnotationId, onScrollCompleted, hoveredAnnotationId, }: CommentsPanelProps): react_jsx_runtime.JSX.Element;
 
 interface DetectSectionProps {
     annotationType: 'highlight' | 'assessment' | 'comment';
@@ -2220,7 +2203,6 @@ interface DetectSectionProps {
             value: string;
         }>;
     } | null | undefined;
-    onDetect: (instructions?: string, tone?: string, density?: number) => void | Promise<void>;
 }
 /**
  * Shared detect section for Highlight, Assessment, and Comment panels
@@ -2230,34 +2212,29 @@ interface DetectSectionProps {
  * - Optional tone selector (for comments)
  * - Detect button with sparkle animation
  * - Progress display during detection
+ *
+ * @emits detection:start - Start detection for annotation type. Payload: { motivation: Motivation, options: { instructions?: string, tone?: string, density?: number } }
+ * @emits detection:dismiss-progress - Dismiss the detection progress display
  */
-declare function DetectSection({ annotationType, isDetecting, detectionProgress, onDetect }: DetectSectionProps): react_jsx_runtime.JSX.Element;
+declare function DetectSection({ annotationType, isDetecting, detectionProgress, }: DetectSectionProps): react_jsx_runtime.JSX.Element;
 
-type Annotation$8 = components['schemas']['Annotation'];
+type Annotation$7 = components['schemas']['Annotation'];
 interface HighlightEntryProps {
-    highlight: Annotation$8;
+    highlight: Annotation$7;
     isFocused: boolean;
-    onClick: () => void;
-    onHighlightRef: (highlightId: string, el: HTMLElement | null) => void;
-    onHighlightHover?: (highlightId: string | null) => void;
+    isHovered?: boolean;
 }
-declare function HighlightEntry({ highlight, isFocused, onClick, onHighlightRef, onHighlightHover, }: HighlightEntryProps): react_jsx_runtime.JSX.Element;
+declare const HighlightEntry: React$1.ForwardRefExoticComponent<HighlightEntryProps & React$1.RefAttributes<HTMLDivElement>>;
 
-type Annotation$7 = components['schemas']['Annotation'];
-type Motivation$4 = components['schemas']['Motivation'];
-interface PendingAnnotation$3 {
+type Annotation$6 = components['schemas']['Annotation'];
+type Motivation$3 = components['schemas']['Motivation'];
+interface PendingAnnotation$4 {
     selector: Selector | Selector[];
-    motivation: Motivation$4;
+    motivation: Motivation$3;
 }
 interface HighlightPanelProps {
-    annotations: Annotation$7[];
-    onAnnotationClick: (annotation: Annotation$7) => void;
-    focusedAnnotationId: string | null;
-    hoveredAnnotationId?: string | null;
-    onAnnotationHover?: (annotationId: string | null) => void;
-    onDetect?: (instructions?: string) => void | Promise<void>;
-    onCreate: (selector: Selector | Selector[]) => void;
-    pendingAnnotation: PendingAnnotation$3 | null;
+    annotations: Annotation$6[];
+    pendingAnnotation: PendingAnnotation$4 | null;
     isDetecting?: boolean;
     detectionProgress?: {
         status: string;
@@ -2265,8 +2242,17 @@ interface HighlightPanelProps {
         message?: string;
     } | null;
     annotateMode?: boolean;
+    scrollToAnnotationId?: string | null;
+    onScrollCompleted?: () => void;
+    hoveredAnnotationId?: string | null;
 }
-declare function HighlightPanel({ annotations, onAnnotationClick, focusedAnnotationId, hoveredAnnotationId, onAnnotationHover, onDetect, onCreate, pendingAnnotation, isDetecting, detectionProgress, annotateMode, }: HighlightPanelProps): react_jsx_runtime.JSX.Element;
+/**
+ * Panel for managing highlight annotations with auto-creation
+ *
+ * @emits annotation:create - Create new highlight annotation (auto-triggered). Payload: { motivation: 'highlighting', selector: Selector | Selector[], body: Body[] }
+ * @subscribes annotation:click - Annotation clicked. Payload: { annotationId: string }
+ */
+declare function HighlightPanel({ annotations, pendingAnnotation, isDetecting, detectionProgress, annotateMode, scrollToAnnotationId, onScrollCompleted, hoveredAnnotationId, }: HighlightPanelProps): react_jsx_runtime.JSX.Element;
 
 type SemiontResource$1 = components['schemas']['ResourceDescriptor'];
 interface Props$2 {
@@ -2286,28 +2272,19 @@ interface PanelHeaderProps {
  */
 declare function PanelHeader({ count, title }: PanelHeaderProps): react_jsx_runtime.JSX.Element;
 
-type Annotation$6 = components['schemas']['Annotation'];
+type Annotation$5 = components['schemas']['Annotation'];
 interface ReferenceEntryProps {
-    reference: Annotation$6;
+    reference: Annotation$5;
     isFocused: boolean;
-    onClick: () => void;
+    isHovered?: boolean;
     routes: RouteBuilder;
-    onReferenceRef: (referenceId: string, el: HTMLElement | null) => void;
-    onReferenceHover?: (referenceId: string | null) => void;
-    onGenerateDocument?: (referenceId: string, options: {
-        title: string;
-        prompt?: string;
-    }) => void;
-    onCreateDocument?: (annotationUri: string, title: string, entityTypes: string[]) => void;
-    onSearchDocuments?: (referenceId: string, searchTerm: string) => void;
-    onUpdateReference?: (referenceId: string, updates: Partial<Annotation$6>) => void;
     annotateMode?: boolean;
     isGenerating?: boolean;
 }
-declare function ReferenceEntry({ reference, isFocused, onClick, routes, onReferenceRef, onReferenceHover, onGenerateDocument, onCreateDocument, onSearchDocuments, onUpdateReference, annotateMode, isGenerating, }: ReferenceEntryProps): react_jsx_runtime.JSX.Element;
+declare const ReferenceEntry: React$1.ForwardRefExoticComponent<ReferenceEntryProps & React$1.RefAttributes<HTMLDivElement>>;
 
-type Annotation$5 = components['schemas']['Annotation'];
-type Motivation$3 = components['schemas']['Motivation'];
+type Annotation$4 = components['schemas']['Annotation'];
+type Motivation$2 = components['schemas']['Motivation'];
 type ResponseContent<T> = T extends {
     responses: {
         200: {
@@ -2318,37 +2295,35 @@ type ResponseContent<T> = T extends {
     };
 } ? R : never;
 type ReferencedBy = ResponseContent<paths['/resources/{id}/referenced-by']['get']>['referencedBy'][number];
-interface PendingAnnotation$2 {
+interface PendingAnnotation$3 {
     selector: Selector | Selector[];
-    motivation: Motivation$3;
+    motivation: Motivation$2;
 }
 interface Props$1 {
-    annotations?: Annotation$5[];
-    onAnnotationClick?: (annotation: Annotation$5) => void;
-    focusedAnnotationId?: string | null;
-    hoveredAnnotationId?: string | null;
-    onAnnotationHover?: (annotationId: string | null) => void;
-    onDetect?: (selectedTypes: string[], includeDescriptiveReferences?: boolean) => void;
-    onCreate: (entityType?: string) => void;
+    annotations?: Annotation$4[];
     isDetecting: boolean;
     detectionProgress: any;
     annotateMode?: boolean;
     Link: React__default.ComponentType<LinkComponentProps>;
     routes: RouteBuilder;
     allEntityTypes: string[];
-    onCancelDetection: () => void;
-    onSearchDocuments?: (referenceId: string, searchTerm: string) => void;
-    onGenerateDocument?: (referenceId: string, options: {
-        title: string;
-        prompt?: string;
-    }) => void;
-    onCreateDocument?: (annotationUri: string, title: string, entityTypes: string[]) => void;
     generatingReferenceId?: string | null;
     referencedBy?: ReferencedBy[];
     referencedByLoading?: boolean;
-    pendingAnnotation: PendingAnnotation$2 | null;
+    pendingAnnotation: PendingAnnotation$3 | null;
+    scrollToAnnotationId?: string | null;
+    onScrollCompleted?: () => void;
+    hoveredAnnotationId?: string | null;
 }
-declare function ReferencesPanel({ annotations, onAnnotationClick, focusedAnnotationId, hoveredAnnotationId, onAnnotationHover, onDetect, onCreate, isDetecting, detectionProgress, annotateMode, Link, routes, allEntityTypes, onCancelDetection, onSearchDocuments, onGenerateDocument, onCreateDocument, generatingReferenceId, referencedBy, referencedByLoading, pendingAnnotation, }: Props$1): react_jsx_runtime.JSX.Element;
+/**
+ * Panel for managing reference annotations with entity type detection
+ *
+ * @emits detection:start - Start reference detection. Payload: { motivation: 'linking', options: { entityTypes: string[], includeDescriptiveReferences: boolean } }
+ * @emits annotation:create - Create new reference annotation. Payload: { motivation: 'linking', selector: Selector | Selector[], body: Body[] }
+ * @emits annotation:cancel-pending - Cancel pending reference annotation. Payload: undefined
+ * @subscribes annotation:click - Annotation clicked. Payload: { annotationId: string }
+ */
+declare function ReferencesPanel({ annotations, isDetecting, detectionProgress, annotateMode, Link, routes, allEntityTypes, generatingReferenceId, referencedBy, referencedByLoading, pendingAnnotation, scrollToAnnotationId, onScrollCompleted, hoveredAnnotationId, }: Props$1): react_jsx_runtime.JSX.Element;
 
 interface Props {
     documentEntityTypes: string[];
@@ -2356,47 +2331,43 @@ interface Props {
     primaryMediaType?: string | undefined;
     primaryByteSize?: number | undefined;
     isArchived?: boolean;
-    onArchive?: () => void;
-    onUnarchive?: () => void;
-    onClone?: () => void;
 }
-declare function ResourceInfoPanel({ documentEntityTypes, documentLocale, primaryMediaType, primaryByteSize, isArchived, onArchive, onUnarchive, onClone }: Props): react_jsx_runtime.JSX.Element;
+/**
+ * Panel for displaying resource metadata and management actions
+ *
+ * @emits resource:clone - Clone this resource. Payload: undefined
+ * @emits resource:unarchive - Unarchive this resource. Payload: undefined
+ * @emits resource:archive - Archive this resource. Payload: undefined
+ */
+declare function ResourceInfoPanel({ documentEntityTypes, documentLocale, primaryMediaType, primaryByteSize, isArchived, }: Props): react_jsx_runtime.JSX.Element;
 
-type Annotation$4 = components['schemas']['Annotation'];
+type Annotation$3 = components['schemas']['Annotation'];
 interface StatisticsPanelProps {
-    highlights: Annotation$4[];
-    comments: Annotation$4[];
-    assessments: Annotation$4[];
-    references: Annotation$4[];
-    tags: Annotation$4[];
+    highlights: Annotation$3[];
+    comments: Annotation$3[];
+    assessments: Annotation$3[];
+    references: Annotation$3[];
+    tags: Annotation$3[];
 }
 declare function StatisticsPanel({ highlights, comments, assessments, references, tags }: StatisticsPanelProps): react_jsx_runtime.JSX.Element;
 
-type Annotation$3 = components['schemas']['Annotation'];
+type Annotation$2 = components['schemas']['Annotation'];
 interface TagEntryProps {
-    tag: Annotation$3;
+    tag: Annotation$2;
     isFocused: boolean;
-    onClick: () => void;
-    onTagRef: (tagId: string, el: HTMLElement | null) => void;
-    onTagHover?: (tagId: string | null) => void;
+    isHovered?: boolean;
 }
-declare function TagEntry({ tag, isFocused, onClick, onTagRef, onTagHover, }: TagEntryProps): react_jsx_runtime.JSX.Element;
+declare const TagEntry: React$1.ForwardRefExoticComponent<TagEntryProps & React$1.RefAttributes<HTMLDivElement>>;
 
-type Annotation$2 = components['schemas']['Annotation'];
-type Motivation$2 = components['schemas']['Motivation'];
-interface PendingAnnotation$1 {
+type Annotation$1 = components['schemas']['Annotation'];
+type Motivation$1 = components['schemas']['Motivation'];
+interface PendingAnnotation$2 {
     selector: Selector | Selector[];
-    motivation: Motivation$2;
+    motivation: Motivation$1;
 }
 interface TaggingPanelProps {
-    annotations: Annotation$2[];
-    onAnnotationClick: (annotation: Annotation$2) => void;
-    focusedAnnotationId: string | null;
-    hoveredAnnotationId?: string | null;
-    onAnnotationHover?: (annotationId: string | null) => void;
+    annotations: Annotation$1[];
     annotateMode?: boolean;
-    onDetect?: (schemaId: string, categories: string[]) => void | Promise<void>;
-    onCreate: (schemaId: string, category: string) => void | Promise<void>;
     isDetecting?: boolean;
     detectionProgress?: {
         status: string;
@@ -2410,46 +2381,42 @@ interface TaggingPanelProps {
             value: string;
         }>;
     } | null;
-    pendingAnnotation: PendingAnnotation$1 | null;
+    pendingAnnotation: PendingAnnotation$2 | null;
+    scrollToAnnotationId?: string | null;
+    onScrollCompleted?: () => void;
+    hoveredAnnotationId?: string | null;
 }
-declare function TaggingPanel({ annotations, onAnnotationClick, focusedAnnotationId, hoveredAnnotationId, onAnnotationHover, annotateMode, onDetect, onCreate, isDetecting, detectionProgress, pendingAnnotation }: TaggingPanelProps): react_jsx_runtime.JSX.Element;
+/**
+ * Panel for managing tag annotations with schema-based detection
+ *
+ * @emits detection:start - Start tag detection. Payload: { motivation: 'tagging', options: { schemaId: string, categories: string[] } }
+ * @emits annotation:cancel-pending - Cancel pending tag annotation. Payload: undefined
+ * @emits annotation:create - Create new tag annotation. Payload: { motivation: 'tagging', selector: Selector | Selector[], body: Body[] }
+ * @subscribes annotation:click - Annotation clicked. Payload: { annotationId: string }
+ */
+declare function TaggingPanel({ annotations, annotateMode, isDetecting, detectionProgress, pendingAnnotation, scrollToAnnotationId, onScrollCompleted, hoveredAnnotationId, }: TaggingPanelProps): react_jsx_runtime.JSX.Element;
 
-type Annotation$1 = components['schemas']['Annotation'];
-type Motivation$1 = components['schemas']['Motivation'];
+type Annotation = components['schemas']['Annotation'];
+type Motivation = components['schemas']['Motivation'];
 type TabKey = 'statistics' | 'reference' | 'highlight' | 'assessment' | 'comment' | 'tag';
-interface PendingAnnotation {
+interface PendingAnnotation$1 {
     selector: Selector | Selector[];
-    motivation: Motivation$1;
+    motivation: Motivation;
 }
 /**
- * Simplified UnifiedAnnotationsPanel using Annotator abstraction
+ * Simplified UnifiedAnnotationsPanel using event-driven architecture
  *
  * Key simplifications:
  * - Single annotations array (grouped internally by motivation)
  * - Single focusedAnnotationId (motivation-agnostic)
- * - Single hoveredAnnotationId (motivation-agnostic)
- * - Single onCreateAnnotation handler (motivation-based dispatch)
+ * - Hover state managed via event bus (no props needed)
+ * - All operations managed via event bus (no callback props)
  */
 interface UnifiedAnnotationsPanelProps {
-    annotations: Annotation$1[];
+    annotations: Annotation[];
     annotators: Record<string, Annotator>;
-    detectionContext?: {
-        client: any;
-        rUri: any;
-        setDetectingMotivation: (motivation: Motivation$1 | null) => void;
-        setMotivationDetectionProgress: (progress: any) => void;
-        detectionStreamRef: any;
-        cacheManager: any;
-        showSuccess: (message: string) => void;
-        showError: (message: string) => void;
-    };
-    focusedAnnotationId: string | null;
-    hoveredAnnotationId?: string | null;
-    onAnnotationClick: (annotation: Annotation$1) => void;
-    onAnnotationHover?: (annotationId: string | null) => void;
-    onCreateAnnotation: (motivation: Motivation$1, ...args: any[]) => void;
     annotateMode?: boolean;
-    detectingMotivation?: Motivation$1 | null;
+    detectingMotivation?: Motivation | null;
     detectionProgress?: {
         status: string;
         percentage?: number;
@@ -2458,21 +2425,17 @@ interface UnifiedAnnotationsPanelProps {
         processedCategories?: number;
         totalCategories?: number;
     } | null;
-    pendingAnnotation: PendingAnnotation | null;
+    pendingAnnotation: PendingAnnotation$1 | null;
     allEntityTypes?: string[];
     generatingReferenceId?: string | null;
-    onGenerateDocument?: (referenceId: string, options: {
-        title: string;
-        prompt?: string;
-    }) => void;
-    onCreateDocument?: (annotationUri: string, title: string, entityTypes: string[]) => void;
-    onSearchDocuments?: (referenceId: string, searchTerm: string) => void;
-    onCancelDetection?: () => void;
-    mediaType?: string;
     referencedBy?: any[];
     referencedByLoading?: boolean;
     resourceId?: string;
     initialTab?: TabKey;
+    initialTabGeneration?: number;
+    scrollToAnnotationId?: string | null;
+    onScrollCompleted?: () => void;
+    hoveredAnnotationId?: string | null;
     Link: React__default.ComponentType<LinkComponentProps>;
     routes: RouteBuilder;
 }
@@ -2514,6 +2477,57 @@ interface NavigationMenuProps {
 }
 declare function NavigationMenu({ Link, routes, t, isAdmin, isModerator, onItemClick, className, currentPath }: NavigationMenuProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Props for ObservableLink component
+ *
+ * Accepts any props that a standard anchor element accepts,
+ * plus optional navigation metadata for event emission.
+ */
+interface ObservableLinkProps extends React__default.AnchorHTMLAttributes<HTMLAnchorElement> {
+    /** The URL to navigate to */
+    href: string;
+    /** Optional label for the link (used in event metadata) */
+    label?: string;
+    /** Children to render inside the link */
+    children: React__default.ReactNode;
+}
+/**
+ * Link component that emits navigation events for observability
+ *
+ * Use this instead of Next.js <Link> when you want link clicks to be
+ * observable through the NavigationEventBus. This is useful for:
+ * - Analytics tracking
+ * - State coordination before navigation
+ * - Logging navigation flows
+ *
+ * The component emits 'navigation:link-clicked' event before allowing
+ * the browser to follow the link.
+ *
+ * @example
+ * ```typescript
+ * <ObservableLink
+ *   href="/know/discover"
+ *   label="Discover"
+ * >
+ *   Discover Resources
+ * </ObservableLink>
+ * ```
+ *
+ * @example With Next.js Link integration
+ * ```typescript
+ * import Link from 'next/link';
+ *
+ * <Link href="/know/discover" legacyBehavior passHref>
+ *   <ObservableLink label="Discover">
+ *     Discover Resources
+ *   </ObservableLink>
+ * </Link>
+ * ```
+ *
+ * @emits navigation:link-clicked - Link clicked by user. Payload: { href: string, label?: string }
+ */
+declare function ObservableLink({ href, label, onClick, children, ...anchorProps }: ObservableLinkProps): react_jsx_runtime.JSX.Element;
+
 interface SimpleNavigationItem$1 {
     name: string;
     href: string;
@@ -2529,7 +2543,6 @@ interface SimpleNavigationProps$1 {
     LinkComponent: React__default.ComponentType<any>;
     dropdownContent?: (onClose: () => void) => React__default.ReactNode;
     isCollapsed: boolean;
-    onToggleCollapse: () => void;
     icons: {
         chevronLeft: React__default.ComponentType<{
             className?: string;
@@ -2544,8 +2557,10 @@ interface SimpleNavigationProps$1 {
 /**
  * Simple navigation component for Admin and Moderation modes.
  * Renders a section header with optional dropdown and static navigation tabs.
+ *
+ * @emits navigation:sidebar-toggle - Toggle sidebar collapsed/expanded state. Payload: undefined
  */
-declare function SimpleNavigation({ title, items, currentPath, LinkComponent, dropdownContent, isCollapsed, onToggleCollapse, icons, collapseSidebarLabel, expandSidebarLabel }: SimpleNavigationProps$1): react_jsx_runtime.JSX.Element;
+declare function SimpleNavigation({ title, items, currentPath, LinkComponent, dropdownContent, isCollapsed, icons, collapseSidebarLabel, expandSidebarLabel }: SimpleNavigationProps$1): react_jsx_runtime.JSX.Element;
 
 /**
  * Represents an open resource/document in the navigation
@@ -2592,10 +2607,6 @@ interface CollapsibleResourceNavigationProps {
     }>;
     resources: OpenResource[];
     isCollapsed: boolean;
-    onToggleCollapse: () => void;
-    onResourceClose: (id: string) => void;
-    onResourceReorder: (oldIndex: number, newIndex: number) => void;
-    onResourceSelect?: (id: string) => void;
     currentPath: string;
     LinkComponent: ComponentType<any>;
     onNavigate?: (path: string) => void;
@@ -2622,8 +2633,12 @@ interface CollapsibleResourceNavigationProps {
  * A comprehensive collapsible navigation component with fixed items and dynamic resource tabs.
  * Supports drag and drop for resource reordering when expanded.
  * Platform-agnostic design for use across different React environments.
+ *
+ * @emits navigation:resource-reorder - Resource tab reordered. Payload: { oldIndex: number, newIndex: number }
+ * @emits navigation:resource-close - Resource tab closed. Payload: { resourceId: string }
+ * @emits navigation:sidebar-toggle - Toggle sidebar collapsed/expanded state. Payload: undefined
  */
-declare function CollapsibleResourceNavigation({ fixedItems, resources, isCollapsed, onToggleCollapse, onResourceClose, onResourceReorder, currentPath, LinkComponent, onNavigate, getResourceHref, className, translations, icons, navigationMenu }: CollapsibleResourceNavigationProps): react_jsx_runtime.JSX.Element;
+declare function CollapsibleResourceNavigation({ fixedItems, resources, isCollapsed, currentPath, LinkComponent, onNavigate, getResourceHref, className, translations, icons, navigationMenu }: CollapsibleResourceNavigationProps): react_jsx_runtime.JSX.Element;
 
 /**
  * A sortable tab for an open resource in the navigation sidebar.
@@ -3126,11 +3141,8 @@ interface DevOpsFeature {
 interface AdminDevOpsPageProps {
     suggestedFeatures: DevOpsFeature[];
     theme: 'light' | 'dark' | 'system';
-    onThemeChange: (theme: 'light' | 'dark' | 'system') => void;
     showLineNumbers: boolean;
-    onLineNumbersToggle: () => void;
     activePanel: string | null;
-    onPanelToggle: (panel: string | null) => void;
     translations: {
         title: string;
         subtitle: string;
@@ -3144,7 +3156,7 @@ interface AdminDevOpsPageProps {
     ToolbarPanels: React__default.ComponentType<any>;
     Toolbar: React__default.ComponentType<any>;
 }
-declare function AdminDevOpsPage({ suggestedFeatures, theme, onThemeChange, showLineNumbers, onLineNumbersToggle, activePanel, onPanelToggle, translations: t, StatusDisplay, ToolbarPanels, Toolbar, }: AdminDevOpsPageProps): react_jsx_runtime.JSX.Element;
+declare function AdminDevOpsPage({ suggestedFeatures, theme, showLineNumbers, activePanel, translations: t, StatusDisplay, ToolbarPanels, Toolbar, }: AdminDevOpsPageProps): react_jsx_runtime.JSX.Element;
 
 interface OAuthProvider {
     name: string;
@@ -3155,11 +3167,8 @@ interface AdminSecurityPageProps {
     allowedDomains: string[];
     isLoading: boolean;
     theme: 'light' | 'dark' | 'system';
-    onThemeChange: (theme: 'light' | 'dark' | 'system') => void;
     showLineNumbers: boolean;
-    onLineNumbersToggle: () => void;
     activePanel: string | null;
-    onPanelToggle: (panel: string | null) => void;
     translations: {
         title: string;
         subtitle: string;
@@ -3182,7 +3191,7 @@ interface AdminSecurityPageProps {
     ToolbarPanels: React__default.ComponentType<any>;
     Toolbar: React__default.ComponentType<any>;
 }
-declare function AdminSecurityPage({ providers, allowedDomains, isLoading, theme, onThemeChange, showLineNumbers, onLineNumbersToggle, activePanel, onPanelToggle, translations: t, ToolbarPanels, Toolbar, }: AdminSecurityPageProps): react_jsx_runtime.JSX.Element;
+declare function AdminSecurityPage({ providers, allowedDomains, isLoading, theme, showLineNumbers, activePanel, translations: t, ToolbarPanels, Toolbar, }: AdminSecurityPageProps): react_jsx_runtime.JSX.Element;
 
 interface AdminUser {
     id: string;
@@ -3213,11 +3222,8 @@ interface AdminUsersPageProps {
     onAddUser: () => void;
     onExportUsers: () => void;
     theme: 'light' | 'dark' | 'system';
-    onThemeChange: (theme: 'light' | 'dark' | 'system') => void;
     showLineNumbers: boolean;
-    onLineNumbersToggle: () => void;
     activePanel: string | null;
-    onPanelToggle: (panel: string | null) => void;
     translations: {
         title: string;
         subtitle: string;
@@ -3266,7 +3272,7 @@ interface AdminUsersPageProps {
         };
     };
 }
-declare function AdminUsersPage({ users, userStats, isLoadingUsers, isLoadingStats, onUpdateUser, onDeleteUser, onAddUser, onExportUsers, theme, onThemeChange, showLineNumbers, onLineNumbersToggle, activePanel, onPanelToggle, translations: t, ToolbarPanels, Toolbar, buttonStyles, }: AdminUsersPageProps): react_jsx_runtime.JSX.Element;
+declare function AdminUsersPage({ users, userStats, isLoadingUsers, isLoadingStats, onUpdateUser, onDeleteUser, onAddUser, onExportUsers, theme, showLineNumbers, activePanel, translations: t, ToolbarPanels, Toolbar, buttonStyles, }: AdminUsersPageProps): react_jsx_runtime.JSX.Element;
 
 interface SignInFormProps {
     /**
@@ -3446,11 +3452,8 @@ interface EntityTagsPageProps {
     onAddTag: () => void;
     isAddingTag: boolean;
     theme: 'light' | 'dark' | 'system';
-    onThemeChange: (theme: 'light' | 'dark' | 'system') => void;
     showLineNumbers: boolean;
-    onLineNumbersToggle: () => void;
     activePanel: string | null;
-    onPanelToggle: (panel: string | null) => void;
     translations: {
         pageTitle: string;
         pageDescription: string;
@@ -3463,17 +3466,14 @@ interface EntityTagsPageProps {
     ToolbarPanels: React__default.ComponentType<any>;
     Toolbar: React__default.ComponentType<any>;
 }
-declare function EntityTagsPage({ entityTypes, error, newTag, onNewTagChange, onAddTag, isAddingTag, theme, onThemeChange, showLineNumbers, onLineNumbersToggle, activePanel, onPanelToggle, translations: t, ToolbarPanels, Toolbar, }: EntityTagsPageProps): react_jsx_runtime.JSX.Element;
+declare function EntityTagsPage({ entityTypes, error, newTag, onNewTagChange, onAddTag, isAddingTag, theme, showLineNumbers, activePanel, translations: t, ToolbarPanels, Toolbar, }: EntityTagsPageProps): react_jsx_runtime.JSX.Element;
 
 interface RecentDocumentsPageProps {
     hasDocuments: boolean;
     isLoading: boolean;
     theme: 'light' | 'dark' | 'system';
-    onThemeChange: (theme: 'light' | 'dark' | 'system') => void;
     showLineNumbers: boolean;
-    onLineNumbersToggle: () => void;
     activePanel: string | null;
-    onPanelToggle: (panel: string | null) => void;
     translations: {
         pageTitle: string;
         pageDescription: string;
@@ -3486,17 +3486,14 @@ interface RecentDocumentsPageProps {
     ToolbarPanels: React__default.ComponentType<any>;
     Toolbar: React__default.ComponentType<any>;
 }
-declare function RecentDocumentsPage({ isLoading, theme, onThemeChange, showLineNumbers, onLineNumbersToggle, activePanel, onPanelToggle, translations: t, ToolbarPanels, Toolbar, }: RecentDocumentsPageProps): react_jsx_runtime.JSX.Element;
+declare function RecentDocumentsPage({ isLoading, theme, showLineNumbers, activePanel, translations: t, ToolbarPanels, Toolbar, }: RecentDocumentsPageProps): react_jsx_runtime.JSX.Element;
 
 interface TagSchemasPageProps {
     schemas: TagSchema[];
     isLoading: boolean;
     theme: 'light' | 'dark' | 'system';
-    onThemeChange: (theme: 'light' | 'dark' | 'system') => void;
     showLineNumbers: boolean;
-    onLineNumbersToggle: () => void;
     activePanel: string | null;
-    onPanelToggle: (panel: string | null) => void;
     translations: {
         pageTitle: string;
         pageDescription: string;
@@ -3506,7 +3503,7 @@ interface TagSchemasPageProps {
     ToolbarPanels: React__default.ComponentType<any>;
     Toolbar: React__default.ComponentType<any>;
 }
-declare function TagSchemasPage({ schemas, isLoading, theme, onThemeChange, showLineNumbers, onLineNumbersToggle, activePanel, onPanelToggle, translations: t, ToolbarPanels, Toolbar, }: TagSchemasPageProps): react_jsx_runtime.JSX.Element;
+declare function TagSchemasPage({ schemas, isLoading, theme, showLineNumbers, activePanel, translations: t, ToolbarPanels, Toolbar, }: TagSchemasPageProps): react_jsx_runtime.JSX.Element;
 
 type ResourceDescriptor$2 = components['schemas']['ResourceDescriptor'];
 interface ResourceComposePageProps {
@@ -3524,11 +3521,8 @@ interface ResourceComposePageProps {
     availableEntityTypes: string[];
     initialLocale: string;
     theme: 'light' | 'dark';
-    onThemeChange: (theme: 'light' | 'dark') => void;
     showLineNumbers: boolean;
-    onLineNumbersToggle: () => void;
     activePanel: string | null;
-    onPanelToggle: (panel: string) => void;
     onSaveResource: (params: SaveResourceParams) => Promise<void>;
     onCancel: () => void;
     translations: {
@@ -3580,7 +3574,7 @@ interface SaveResourceParams {
     annotationUri?: string;
     sourceDocumentId?: string;
 }
-declare function ResourceComposePage({ mode, cloneData, referenceData, availableEntityTypes, initialLocale, theme, onThemeChange, showLineNumbers, onLineNumbersToggle, activePanel, onPanelToggle, onSaveResource, onCancel, translations: t, ToolbarPanels, Toolbar, }: ResourceComposePageProps): react_jsx_runtime.JSX.Element;
+declare function ResourceComposePage({ mode, cloneData, referenceData, availableEntityTypes, initialLocale, theme, showLineNumbers, activePanel, onSaveResource, onCancel, translations: t, ToolbarPanels, Toolbar, }: ResourceComposePageProps): react_jsx_runtime.JSX.Element;
 
 type ResourceDescriptor$1 = components['schemas']['ResourceDescriptor'];
 interface ResourceDiscoveryPageProps {
@@ -3590,11 +3584,8 @@ interface ResourceDiscoveryPageProps {
     isLoadingRecent: boolean;
     isSearching: boolean;
     theme: 'light' | 'dark';
-    onThemeChange: (theme: 'light' | 'dark') => void;
     showLineNumbers: boolean;
-    onLineNumbersToggle: () => void;
     activePanel: string | null;
-    onPanelToggle: (panel: string) => void;
     onNavigateToResource: (resourceId: string) => void;
     onNavigateToCompose: () => void;
     translations: {
@@ -3617,7 +3608,7 @@ interface ResourceDiscoveryPageProps {
     };
     ToolbarPanels: React__default.ComponentType<any>;
 }
-declare function ResourceDiscoveryPage({ recentDocuments, searchDocuments, entityTypes, isLoadingRecent, isSearching, theme, onThemeChange, showLineNumbers, onLineNumbersToggle, activePanel, onPanelToggle, onNavigateToResource, onNavigateToCompose, translations: t, ToolbarPanels, }: ResourceDiscoveryPageProps): react_jsx_runtime.JSX.Element;
+declare function ResourceDiscoveryPage({ recentDocuments, searchDocuments, entityTypes, isLoadingRecent, isSearching, theme, showLineNumbers, activePanel, onNavigateToResource, onNavigateToCompose, translations: t, ToolbarPanels, }: ResourceDiscoveryPageProps): react_jsx_runtime.JSX.Element;
 
 type ResourceDescriptor = components['schemas']['ResourceDescriptor'];
 interface ResourceCardProps {
@@ -3630,8 +3621,6 @@ interface ResourceCardProps {
 declare const ResourceCard: React__default.MemoExoticComponent<({ resource, onOpen, tabIndex, archivedLabel, createdLabel }: ResourceCardProps) => react_jsx_runtime.JSX.Element>;
 
 type SemiontResource = components['schemas']['ResourceDescriptor'];
-type Annotation = components['schemas']['Annotation'];
-type Motivation = components['schemas']['Motivation'];
 interface ResourceViewerPageProps {
     /**
      * The resource to display
@@ -3641,76 +3630,14 @@ interface ResourceViewerPageProps {
      * Resource URI
      */
     rUri: ResourceUri;
-    /**
-     * Document content (already loaded)
-     */
-    content: string;
-    /**
-     * Whether content is still loading
-     */
-    contentLoading: boolean;
-    /**
-     * All annotations for this resource
-     */
-    annotations: Annotation[];
-    /**
-     * Resources that reference this resource
-     */
-    referencedBy: any[];
-    /**
-     * Whether referencedBy is loading
-     */
-    referencedByLoading: boolean;
-    /**
-     * All available entity types
-     */
-    allEntityTypes: string[];
     /**
      * Current locale
      */
     locale: string;
-    /**
-     * Theme state
-     */
-    theme: any;
-    onThemeChange: (theme: any) => void;
-    /**
-     * Line numbers state
-     */
-    showLineNumbers: boolean;
-    onLineNumbersToggle: () => void;
-    /**
-     * Active toolbar panel
-     */
-    activePanel: any;
-    onPanelToggle: (panel: any) => void;
-    setActivePanel: (panel: any) => void;
-    /**
-     * Callbacks for resource actions
-     */
-    onArchive: () => Promise<void>;
-    onUnarchive: () => Promise<void>;
-    onClone: () => Promise<void>;
-    onUpdateAnnotationBody: (annotationUri: string, data: any) => Promise<void>;
-    /**
-     * Annotation CRUD callbacks
-     */
-    onCreateAnnotation: (rUri: ResourceUri, motivation: Motivation, selector: any, body: any[]) => Promise<void>;
-    onTriggerSparkleAnimation: (annotationId: string) => void;
-    onClearNewAnnotationId: (annotationId: string) => void;
-    /**
-     * Toast notifications
-     */
-    showSuccess: (message: string) => void;
-    showError: (message: string) => void;
     /**
      * Cache manager for detection
      */
     cacheManager: any;
-    /**
-     * API client
-     */
-    client: any;
     /**
      * Link component for routing
      */
@@ -3720,12 +3647,226 @@ interface ResourceViewerPageProps {
      */
     routes: any;
     /**
-     * Component dependencies - passed from frontend
+     * Component dependencies - passed from framework layer
      */
     ToolbarPanels: React__default.ComponentType<any>;
     SearchResourcesModal: React__default.ComponentType<any>;
     GenerationConfigModal: React__default.ComponentType<any>;
+    /**
+     * Callback to refetch document from parent
+     */
+    refetchDocument: () => Promise<unknown>;
+}
+/**
+ * ResourceViewerPage - Main component
+ *
+ * Uses hooks directly (NO containers, NO render props, NO ResourceViewerPageContent wrapper)
+ *
+ * @emits navigation:router-push - Navigate to a resource or filtered view
+ * @emits annotation:sparkle - Trigger sparkle animation on an annotation
+ * @emits annotation:update-body - Update annotation body content
+ * @subscribes resource:archive - Archive the current resource
+ * @subscribes resource:unarchive - Unarchive the current resource
+ * @subscribes resource:clone - Clone the current resource
+ * @subscribes annotation:sparkle - Trigger sparkle animation
+ * @subscribes annotation:created - Annotation was created
+ * @subscribes annotation:deleted - Annotation was deleted
+ * @subscribes annotation:create-failed - Annotation creation failed
+ * @subscribes annotation:delete-failed - Annotation deletion failed
+ * @subscribes annotation:body-updated - Annotation body was updated
+ * @subscribes annotation:body-update-failed - Annotation body update failed
+ * @subscribes settings:theme-changed - UI theme changed
+ * @subscribes settings:line-numbers-toggled - Line numbers display toggled
+ * @subscribes detection:complete - Detection completed
+ * @subscribes detection:failed - Detection failed
+ * @subscribes generation:complete - Generation completed
+ * @subscribes generation:failed - Generation failed
+ * @subscribes navigation:reference-navigate - Navigate to a referenced document
+ * @subscribes navigation:entity-type-clicked - Navigate filtered by entity type
+ */
+declare function ResourceViewerPage({ resource, rUri, locale, cacheManager, Link, routes, ToolbarPanels, SearchResourcesModal, GenerationConfigModal, refetchDocument, }: ResourceViewerPageProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * useDetectionFlow - Detection state management hook
+ *
+ * Manages all annotation detection (manual and AI-driven):
+ * - Pending annotation state (user selected text, waiting for confirmation)
+ * - Selection events → pending annotation conversion
+ * - Annotation interaction (hover, click)
+ * - Annotation request routing to appropriate panel
+ * - Tracking currently detecting motivation (AI-driven detection)
+ * - Detection progress updates from SSE
+ * - Detection lifecycle (start, progress, complete, failed)
+ * - Auto-dismiss progress after completion (5 seconds)
+ * - Manual dismiss via detection:dismiss-progress event
+ * - Annotation create/delete API calls
+ * - AI detection SSE streams (all 5 motivation types)
+ *
+ * "Detection" covers both forms: a human selecting text is manual detection;
+ * AI-driven SSE streams are automated detection. Same concept, same hook.
+ *
+ * Follows react-rxjs-guide.md Layer 2 pattern: Hook bridge that
+ * subscribes to events and pushes values into React state.
+ */
+
+interface PendingAnnotation {
+    selector: Selector | Selector[];
+    motivation: Motivation$9;
+}
+interface DetectionFlowState {
+    pendingAnnotation: PendingAnnotation | null;
+    hoveredAnnotationId: string | null;
+    detectingMotivation: Motivation$9 | null;
+    detectionProgress: DetectionProgress | null;
+    detectionStreamRef: React.MutableRefObject<AbortController | null>;
+}
+/**
+ * Hook for annotation detection flow (manual and AI-driven)
+ *
+ * @param rUri - Resource URI being detected
+ * @emits panel:open - Open the annotations panel when annotation is requested
+ * @emits annotation:sparkle - Trigger sparkle animation on hovered annotation
+ * @emits annotation:focus - Focus/scroll to clicked annotation
+ * @emits annotation:created - Annotation successfully created
+ * @emits annotation:create-failed - Annotation creation failed
+ * @emits annotation:deleted - Annotation successfully deleted
+ * @emits annotation:delete-failed - Annotation deletion failed
+ * @emits detection:progress - Progress update from SSE stream
+ * @emits detection:complete - SSE detection completed
+ * @emits detection:failed - SSE detection failed
+ * @emits detection:cancelled - SSE detection cancelled
+ * @subscribes annotation:requested - User requested a new annotation
+ * @subscribes annotation:create - Create annotation via API
+ * @subscribes annotation:delete - Delete annotation via API
+ * @subscribes selection:comment-requested - User selected text for a comment
+ * @subscribes selection:tag-requested - User selected text for a tag
+ * @subscribes selection:assessment-requested - User selected text for an assessment
+ * @subscribes selection:reference-requested - User selected text for a reference
+ * @subscribes annotation:cancel-pending - Cancel pending annotation creation
+ * @subscribes annotation:hover - Annotation hover state change
+ * @subscribes annotation:click - Annotation clicked
+ * @subscribes detection:start - Trigger AI detection SSE stream
+ * @subscribes job:cancel-requested - Cancels in-flight detection stream (detection half only)
+ * @subscribes detection:progress - Progress update during detection
+ * @subscribes detection:complete - Detection completed successfully
+ * @subscribes detection:failed - Error during detection
+ * @subscribes detection:dismiss-progress - Manually dismiss progress display
+ * @returns Detection state
+ */
+declare function useDetectionFlow(rUri: ResourceUri): DetectionFlowState;
+
+/**
+ * usePanelNavigation - Panel navigation and scroll coordination hook
+ *
+ * Manages sidebar panel state:
+ * - Active panel tracking (which panel is open)
+ * - Scroll coordination (scrollToAnnotationId)
+ * - Panel routing with initial tab
+ * - LocalStorage persistence
+ *
+ * Follows react-rxjs-guide.md Layer 2 pattern: Hook bridge that
+ * subscribes to events and pushes values into React state.
+ */
+type ToolbarPanelType = 'document' | 'history' | 'info' | 'annotations' | 'settings' | 'collaboration' | 'user' | 'jsonld';
+interface PanelNavigationState {
+    activePanel: ToolbarPanelType | null;
+    scrollToAnnotationId: string | null;
+    panelInitialTab: {
+        tab: string;
+        generation: number;
+    } | null;
+    onScrollCompleted: () => void;
+}
+/**
+ * Hook for panel navigation state management
+ *
+ * @subscribes panel:toggle - Toggle a panel open/closed
+ * @subscribes panel:open - Open a panel, optionally scrolling to an annotation
+ * @subscribes panel:close - Close the active panel
+ * @returns Panel navigation state
+ */
+declare function usePanelNavigation(): PanelNavigationState;
+
+/**
+ * useGenerationFlow - Document generation flow hook
+ *
+ * Manages document generation state:
+ * - Generation progress tracking
+ * - Generation modal state
+ * - Reference search modal state
+ * - Generation completion/error handling
+ *
+ * Follows react-rxjs-guide.md Layer 2 pattern: Hook bridge that
+ * subscribes to events and pushes values into React state.
+ */
+
+interface GenerationFlowState {
+    isGenerating: boolean;
+    generationProgress: GenerationProgress | null;
+    generationModalOpen: boolean;
+    generationReferenceId: string | null;
+    generationDefaultTitle: string;
+    onGenerateDocument: (referenceId: string, options: {
+        title: string;
+        prompt?: string;
+        language?: string;
+        temperature?: number;
+        maxTokens?: number;
+        context?: GenerationContext;
+    }) => void;
+    onCloseGenerationModal: () => void;
+}
+/**
+ * Hook for document generation flow
+ *
+ * @param locale - Current locale for language defaults
+ * @param resourceId - Resource ID for generation
+ * @param showSuccess - Success toast callback
+ * @param showError - Error toast callback
+ * @param cacheManager - Cache manager for invalidation
+ * @param clearNewAnnotationId - Clear animation callback
+ * @emits generation:start - Start document generation (consumed internally by this hook)
+ * @emits generation:progress - SSE progress chunk from generation stream
+ * @emits generation:complete - Generation completed successfully
+ * @emits generation:failed - Error during generation
+ * @subscribes generation:start - Triggers SSE call to generateResourceFromAnnotation
+ * @subscribes job:cancel-requested - Cancels in-flight generation stream
+ * @subscribes reference:create-manual - Navigates to compose page for new document reference
+ * @subscribes generation:modal-open - Open the generation config modal; triggers context:retrieval-requested
+ * @subscribes generation:complete - Generation completed successfully
+ * @subscribes generation:failed - Error during generation
+ * @returns Generation flow state
+ */
+declare function useGenerationFlow(locale: string, resourceId: string, showSuccess: (message: string) => void, showError: (message: string) => void, cacheManager: any, clearNewAnnotationId: (annotationId: AnnotationUri) => void): GenerationFlowState;
+
+/**
+ * useContextRetrievalFlow - Context retrieval capability hook
+ *
+ * Retrieval capability: given a reference annotation, fetch the surrounding
+ * text context (before/selected/after) from the source document so it can
+ * be used as grounding material for generation.
+ *
+ * This hook is the single owner of retrieval state. It is triggered by
+ * context:retrieval-requested on the event bus, making the capability
+ * accessible to both human UI flows and agents.
+ *
+ * @subscribes context:retrieval-requested - Fetch LLM context for an annotation
+ * @emits context:retrieval-complete - Context successfully fetched
+ * @emits context:retrieval-failed - Context fetch failed
+ * @returns Retrieval state (context, loading, error, which annotation)
+ */
+
+interface ContextRetrievalFlowConfig {
+    client: SemiontApiClient;
+    resourceUri: ResourceUri;
+}
+interface ContextRetrievalFlowState {
+    retrievalContext: GenerationContext | null;
+    retrievalLoading: boolean;
+    retrievalError: Error | null;
+    /** The annotationUri for which context was most recently retrieved */
+    retrievalAnnotationUri: string | null;
 }
-declare function ResourceViewerPage(props: ResourceViewerPageProps): react_jsx_runtime.JSX.Element;
+declare function useContextRetrievalFlow(emitter: Emitter<EventMap>, config: ContextRetrievalFlowConfig): ContextRetrievalFlowState;
 
-export { ANNOTATORS, AUTH_EVENTS, AVAILABLE_LOCALES, AdminDevOpsPage, type AdminDevOpsPageProps, AdminSecurityPage, type AdminSecurityPageProps, type AdminUser, type AdminUserStats, AdminUsersPage, type AdminUsersPageProps, AnnotateToolbar, AnnotateView, type Annotation$n as Annotation, type AnnotationConfig, type AnnotationCreationHandler, type AnnotationHandlers, AnnotationHistory, type AnnotationManager, AnnotationOverlay, AnnotationProvider, type AnnotationProviderProps, AnnotationUIProvider, type AnnotationUIProviderProps, type AnnotationUIState, type AnnotationsCollection, type Annotator, ApiClientManager, ApiClientProvider, type ApiClientProviderProps, AssessmentEntry, AssessmentPanel, AsyncErrorBoundary, AuthErrorDisplay, type AuthErrorDisplayProps, type AuthEventDetail, type AuthEventType, type AvailableLocale, type BorderRadiusToken, BrowseView, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, type CacheManager, CacheProvider, type CacheProviderProps, type ClickAction, CodeMirrorRenderer, CollaborationPanel, CollapsibleResourceNavigation, type CollapsibleResourceNavigationProps, type ColorToken, CommentEntry, CommentsPanel, ComposeLoadingState, type ComposeLoadingStateProps, type CreateAnnotationParams, type CreateConfig, type DeleteAnnotationParams, DetectSection, type DetectionConfig, type DetectionProgress, DetectionProgressWidget, type DevOpsFeature, type DrawingMode, EntityTagsPage, type EntityTagsPageProps, EntityTypeBadges, ErrorBoundary, Footer, type GenerationOptions, type GenerationProgress, HighlightEntry, HighlightPanel, HistoryEvent, ImageURLSchema, ImageViewer, JsonLdPanel, JsonLdView, type KeyboardShortcut, KeyboardShortcutsHelpModal, LeftSidebar, type LinkComponentProps, LiveRegionProvider, MakeMeaningEventBusProvider, type MakeMeaningEventBusProviderProps, type Motivation$b as Motivation, type NavigationItem, NavigationMenu, type NavigationMenuHelper, type NavigationProps, type OAuthProvider, type OAuthUser, OAuthUserSchema, type OpenResource, OpenResourcesManager, OpenResourcesProvider, PageLayout, PanelHeader, PopupContainer, PopupHeader, type PreparedAnnotation, ProposeEntitiesModal, QUERY_KEYS, RecentDocumentsPage, type RecentDocumentsPageProps, ReferenceEntry, ReferenceResolutionWidget, ReferencesPanel, ResizeHandle, type ResolvedTheme, ResourceAnnotationsProvider, ResourceCard, type ResourceCardProps, ResourceComposePage, type ResourceComposePageProps, ResourceDiscoveryPage, type ResourceDiscoveryPageProps, ResourceErrorState, type ResourceErrorStateProps, ResourceInfoPanel, ResourceLoadingState, ResourceSearchModal, type ResourceSearchModalProps, ResourceTagsInline, ResourceViewer, ResourceViewerPage, type ResourceViewerPageProps, type RouteBuilder, type SaveResourceParams, SearchModal, type SearchModalProps, SelectedTextDisplay, type SelectionData, type SelectionMotivation, type SelectorType, SemiontBranding, SemiontFavicon, type SemiontResource$3 as SemiontResource, SessionExpiryBanner, SessionManager, SessionProvider, SessionTimer, SettingsPanel, type ShadowToken, type ShapeType, SignInForm, type SignInFormProps, SignUpForm, type SignUpFormProps, SimpleNavigation, type SimpleNavigationItem, type SimpleNavigationProps, SkipLinks, SortableResourceTab, type SortableResourceTabProps, type SpacingToken, StatisticsPanel, StatusDisplay, type StreamStatus, SvgDrawingCanvas, TagEntry, TagSchemasPage, type TagSchemasPageProps, TaggingPanel, type TextSegment, type TextSelection, type Theme, ToastContainer, type ToastMessage, ToastProvider, type ToastType, Toolbar, type ToolbarPanelType, type TransitionToken, TranslationManager, TranslationProvider, type TranslationProviderProps, type TypographyToken, type UICreateAnnotationParams, UnifiedAnnotationsPanel, UnifiedHeader, UserMenuSkeleton, WelcomePage, type WelcomePageProps, buttonStyles, createCancelDetectionHandler, createDetectionHandler, cssVariables, dispatch401Error, dispatch403Error, dispatchAuthEvent, faviconPaths, generateCSSVariables, getResourceIcon, getSelectedShapeForSelectorType, getSelectorType, getShortcutDisplay, getSupportedShapes, isShapeSupported, jsonLightHighlightStyle, jsonLightTheme, onAuthEvent, rehypeRenderAnnotations, remarkAnnotations, sanitizeImageURL, saveSelectedShapeForSelectorType, supportsDetection, tokens, useAdmin, useAnnotationManager, useAnnotationPanel, useAnnotationUI, useAnnotations, useApiClient, useAuthApi, useCacheManager, useDebounce, useDebouncedCallback, useDetectionProgress, useDocumentAnnouncements, useDoubleKeyPress, useDropdown, useEntityTypes, useFormAnnouncements, useFormValidation, useFormattedTime, useGenerationProgress, useHealth, useIsTyping, useKeyboardShortcuts, useLanguageChangeAnnouncements, useLineNumbers, useLiveRegion, useLoadingState, useLocalStorage, useMakeMeaningEvents, useOpenResources, usePanelWidth, usePreloadTranslations, useResourceAnnotations, useResourceEvents, useResourceLoadingAnnouncements, useResources, useRovingTabIndex, useSearchAnnouncements, useSessionContext, useSessionExpiry, useTheme, useToast, useToolbar, useTranslations, validationRules };
+export { ANNOTATORS, AUTH_EVENTS, AVAILABLE_LOCALES, AdminDevOpsPage, type AdminDevOpsPageProps, AdminSecurityPage, type AdminSecurityPageProps, type AdminUser, type AdminUserStats, AdminUsersPage, type AdminUsersPageProps, AnnotateToolbar, AnnotateView, type Annotation$k as Annotation, type AnnotationConfig, type AnnotationCreationHandler, type AnnotationHandlers, AnnotationHistory, type AnnotationManager, AnnotationOverlay, AnnotationProvider, type AnnotationProviderProps, type AnnotationUIState, type AnnotationsCollection, type Annotator, ApiClientProvider, type ApiClientProviderProps, AssessmentEntry, AssessmentPanel, AsyncErrorBoundary, AuthErrorDisplay, type AuthErrorDisplayProps, type AuthEventDetail, type AuthEventType, AuthTokenProvider, type AuthTokenProviderProps, type AvailableLocale, type BorderRadiusToken, BrowseView, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, type CacheManager, CacheProvider, type CacheProviderProps, type ClickAction, CodeMirrorRenderer, CollaborationPanel, CollapsibleResourceNavigation, type CollapsibleResourceNavigationProps, type ColorToken, CommentEntry, CommentsPanel, ComposeLoadingState, type ComposeLoadingStateProps, type ContextRetrievalFlowConfig, type ContextRetrievalFlowState, type CreateAnnotationParams, type CreateConfig, type DeleteAnnotationParams, DetectSection, type DetectionConfig, type DetectionFlowState, DetectionProgress, DetectionProgressWidget, type DevOpsFeature, type DrawingMode, EntityTagsPage, type EntityTagsPageProps, EntityTypeBadges, ErrorBoundary, EventBus, EventMap, Footer, type GenerationFlowState, type GenerationOptions, GenerationProgress, HighlightEntry, HighlightPanel, HistoryEvent, ImageURLSchema, ImageViewer, JsonLdPanel, JsonLdView, type KeyboardShortcut, KeyboardShortcutsHelpModal, LeftSidebar, type LinkComponentProps, LiveRegionProvider, type Motivation$8 as Motivation, type NavigationItem, NavigationMenu, type NavigationMenuHelper, type NavigationProps, type OAuthProvider, type OAuthUser, OAuthUserSchema, ObservableLink, type ObservableLinkProps, type OpenResource, OpenResourcesManager, OpenResourcesProvider, PageLayout, PanelHeader, type PanelNavigationState, PopupContainer, PopupHeader, type PreparedAnnotation, ProposeEntitiesModal, QUERY_KEYS, RecentDocumentsPage, type RecentDocumentsPageProps, ReferenceEntry, ReferenceResolutionWidget, ReferencesPanel, ResizeHandle, type ResolutionFlowConfig, type ResolutionFlowState, type ResolvedTheme, ResourceAnnotationsProvider, ResourceCard, type ResourceCardProps, ResourceComposePage, type ResourceComposePageProps, ResourceDiscoveryPage, type ResourceDiscoveryPageProps, ResourceErrorState, type ResourceErrorStateProps, ResourceInfoPanel, ResourceLoadingState, ResourceSearchModal, type ResourceSearchModalProps, ResourceTagsInline, ResourceViewer, ResourceViewerPage, type ResourceViewerPageProps, type RouteBuilder, type SaveResourceParams, SearchModal, type SearchModalProps, SelectedTextDisplay, type SelectionMotivation, type SelectorType, SemiontBranding, SemiontFavicon, type SemiontResource$4 as SemiontResource, SessionExpiryBanner, SessionManager, SessionProvider, SessionTimer, SettingsPanel, type ShadowToken, type ShapeType, SignInForm, type SignInFormProps, SignUpForm, type SignUpFormProps, SimpleNavigation, type SimpleNavigationItem, type SimpleNavigationProps, SkipLinks, SortableResourceTab, type SortableResourceTabProps, type SpacingToken, StatisticsPanel, StatusDisplay, type StreamStatus, SvgDrawingCanvas, TagEntry, TagSchemasPage, type TagSchemasPageProps, TaggingPanel, type TextSegment, type TextSelection, type Theme, ThemeProvider, ToastContainer, type ToastMessage, ToastProvider, type ToastType, Toolbar, type ToolbarPanelType, type TransitionToken, TranslationManager, TranslationProvider, type TranslationProviderProps, type TypographyToken, type UICreateAnnotationParams, UnifiedAnnotationsPanel, UnifiedHeader, type UseResourceContentResult, UserMenuSkeleton, WelcomePage, type WelcomePageProps, buttonStyles, createCancelDetectionHandler, createDetectionHandler, cssVariables, dispatch401Error, dispatch403Error, dispatchAuthEvent, faviconPaths, formatTime, generateCSSVariables, getResourceIcon, getSelectedShapeForSelectorType, getSelectorType, getShortcutDisplay, getSupportedShapes, isShapeSupported, jsonLightHighlightStyle, jsonLightTheme, onAuthEvent, rehypeRenderAnnotations, remarkAnnotations, sanitizeImageURL, saveSelectedShapeForSelectorType, supportsDetection, tokens, useAdmin, useAnnotationManager, useAnnotations, useApiClient, useAuthApi, useAuthToken, useCacheManager, useContextRetrievalFlow, useDebounce, useDebouncedCallback, useDetectionFlow, useDocumentAnnouncements, useDoubleKeyPress, useDropdown, useEntityTypes, useEventSubscription, useEventSubscriptions, useFormAnnouncements, useGenerationFlow, useHealth, useIsTyping, useKeyboardShortcuts, useLanguageChangeAnnouncements, useLineNumbers, useLiveRegion, useLoadingState, useLocalStorage, useObservableExternalNavigation, useObservableRouter, useOpenResources, usePanelNavigation, usePanelWidth, usePreloadTranslations, useResolutionFlow, useResourceAnnotations, useResourceContent, useResourceEvents, useResourceLoadingAnnouncements, useResources, useRovingTabIndex, useSearchAnnouncements, useSessionContext, useSessionExpiry, useTheme, useToast, useTranslations };