@semiont/react-ui 0.2.35-build.99 → 0.2.35

package/src/features/resource-viewer/__tests__/ToastNotifications.test.tsx

@@ -4,7 +4,7 @@
  * This test verifies the fix for the issue identified in commit 9690806abc910bad490e684d6ef71d874a90579c.
  *
  * SOLUTION IMPLEMENTED:
- * - Pattern B: Both useAnnotationFlow and useGenerationFlow call useToast internally
+ * - Pattern B: Both useMarkFlow and useYieldFlow call useToast internally
  * - Toast notifications are shown from within the hooks (self-contained)
  *
  * EXPECTED BEHAVIOR (after fix):
@@ -20,8 +20,8 @@ import { EventBusProvider, resetEventBusForTesting, useEventBus } from '../../..
 import { ApiClientProvider } from '../../../contexts/ApiClientContext';
 import { AuthTokenProvider } from '../../../contexts/AuthTokenContext';
 import { resourceUri } from '@semiont/core';
-import { useAnnotationFlow } from '../../../hooks/useAnnotationFlow';
-import { useGenerationFlow } from '../../../hooks/useGenerationFlow';
+import { useMarkFlow } from '../../../hooks/useMarkFlow';
+import { useYieldFlow } from '../../../hooks/useYieldFlow';
 
 // Mock the toast hook to track calls
 const mockShowSuccess = vi.fn();
@@ -51,13 +51,13 @@ describe('Toast Notifications - Verifies Toast Integration', () => {
    */
   function TestComponentWithDetection() {
     eventBusInstance = useEventBus();
-    useAnnotationFlow(rUri);
+    useMarkFlow(rUri);
     return <div data-testid="test">Test</div>;
   }
 
   function TestComponentWithGeneration() {
     eventBusInstance = useEventBus();
-    useGenerationFlow('en', 'test-resource', vi.fn());
+    useYieldFlow('en', 'test-resource', vi.fn());
     return <div data-testid="test">Test</div>;
   }
 
@@ -86,7 +86,7 @@ describe('Toast Notifications - Verifies Toast Integration', () => {
   }
 
   describe('Detection Events Trigger Toasts', () => {
-    it('annotate:assist-finished shows success toast', async () => {
+    it('mark:assist-finished shows success toast', async () => {
       renderDetectionTest();
 
       // Clear any potential mount-related calls
@@ -95,7 +95,7 @@ describe('Toast Notifications - Verifies Toast Integration', () => {
 
       // Emit detection finished event (what SSE would emit)
       act(() => {
-        eventBusInstance.get('annotate:assist-finished').next({
+        eventBusInstance.get('mark:assist-finished').next({
           motivation: 'linking' as any
         });
       });
@@ -106,7 +106,7 @@ describe('Toast Notifications - Verifies Toast Integration', () => {
       });
     });
 
-    it('annotate:assist-failed shows error toast', async () => {
+    it('mark:assist-failed shows error toast', async () => {
       renderDetectionTest();
 
       await new Promise(resolve => setTimeout(resolve, 100));
@@ -114,7 +114,7 @@ describe('Toast Notifications - Verifies Toast Integration', () => {
 
       // Emit detection failed event
       act(() => {
-        eventBusInstance.get('annotate:assist-failed').next({
+        eventBusInstance.get('mark:assist-failed').next({
           type: 'job.failed' as const,
           resourceId: 'test' as any,
           userId: 'user' as any,
@@ -137,7 +137,7 @@ describe('Toast Notifications - Verifies Toast Integration', () => {
   });
 
   describe('Generation Events Trigger Toasts', () => {
-    it('generate:finished shows success toast', async () => {
+    it('yield:finished shows success toast', async () => {
       renderGenerationTest();
 
       await new Promise(resolve => setTimeout(resolve, 100));
@@ -145,7 +145,7 @@ describe('Toast Notifications - Verifies Toast Integration', () => {
 
       // Emit generation finished event
       act(() => {
-        eventBusInstance.get('generate:finished').next({
+        eventBusInstance.get('yield:finished').next({
           status: 'complete',
           message: 'Document generated successfully',
           percentage: 100,
@@ -159,7 +159,7 @@ describe('Toast Notifications - Verifies Toast Integration', () => {
       });
     });
 
-    it('generate:failed shows error toast', async () => {
+    it('yield:failed shows error toast', async () => {
       renderGenerationTest();
 
       await new Promise(resolve => setTimeout(resolve, 100));
@@ -167,7 +167,7 @@ describe('Toast Notifications - Verifies Toast Integration', () => {
 
       // Emit generation failed event
       act(() => {
-        eventBusInstance.get('generate:failed').next({
+        eventBusInstance.get('yield:failed').next({
           error: new Error('Failed to generate document'),
         });
       });

package/src/features/resource-viewer/__tests__/{GenerationFlowIntegration.test.tsx → YieldFlowIntegration.test.tsx}

@@ -4,8 +4,8 @@
  * Tests the COMPLETE generation flow with real component composition:
  * - EventBusProvider (REAL)
  * - ApiClientProvider (REAL, with MOCKED client)
- * - useGenerationFlow (REAL, with inlined progress state)
- * - useResolutionFlow (REAL)
+ * - useYieldFlow (REAL, with inlined progress state)
+ * - useBindFlow (REAL)
  * - useEventSubscriptions (REAL)
  *
  * This test focuses on ARCHITECTURE and EVENT WIRING:
@@ -21,11 +21,11 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { render, screen, waitFor } from '@testing-library/react';
 import { act } from 'react';
-import { useGenerationFlow } from '../../../hooks/useGenerationFlow';
+import { useYieldFlow } from '../../../hooks/useYieldFlow';
 import { EventBusProvider, useEventBus, resetEventBusForTesting } from '../../../contexts/EventBusContext';
 import { ApiClientProvider } from '../../../contexts/ApiClientContext';
 import { AuthTokenProvider } from '../../../contexts/AuthTokenContext';
-import { useResolutionFlow } from '../../../hooks/useResolutionFlow';
+import { useBindFlow } from '../../../hooks/useBindFlow';
 import { SSEClient } from '@semiont/api-client';
 import type { ResourceUri, AnnotationUri } from '@semiont/core';
 import { resourceUri, annotationUri } from '@semiont/core';
@@ -64,7 +64,7 @@ describe('Generation Flow - Feature Integration', () => {
     mockStream = createMockGenerationStream();
 
     // Spy on SSEClient prototype method
-    generateResourceSpy = vi.spyOn(SSEClient.prototype, 'generateResourceFromAnnotation').mockReturnValue(mockStream as any);
+    generateResourceSpy = vi.spyOn(SSEClient.prototype, 'yieldResourceFromAnnotation').mockReturnValue(mockStream as any);
 
     // Mock callbacks
     mockShowSuccess = vi.fn();
@@ -76,11 +76,11 @@ describe('Generation Flow - Feature Integration', () => {
     vi.restoreAllMocks();
   });
 
-  it('should open modal when generate:modal-open event is emitted', async () => {
+  it('should open modal when yield:modal-open event is emitted', async () => {
     const testResourceUri = resourceUri('http://localhost:4000/resources/test-resource');
     const testAnnotationUri = annotationUri('http://localhost:4000/resources/test-resource/annotations/test-annotation');
 
-    const { emitModalOpen } = renderGenerationFlow(
+    const { emitModalOpen } = renderYieldFlow(
       testResourceUri
     );
 
@@ -97,11 +97,11 @@ describe('Generation Flow - Feature Integration', () => {
     });
   });
 
-  it('should call generateResourceFromAnnotation exactly ONCE when generation starts', async () => {
+  it('should call yieldResourceFromAnnotation exactly ONCE when generation starts', async () => {
     const testResourceUri = resourceUri('http://localhost:4000/resources/test-resource');
     const testAnnotationUri = annotationUri('http://localhost:4000/resources/test-resource/annotations/test-annotation');
 
-    const { emitGenerationStart, getEventBus } = renderGenerationFlow(
+    const { emitGenerationStart, getEventBus } = renderYieldFlow(
       testResourceUri
     );
 
@@ -144,11 +144,11 @@ describe('Generation Flow - Feature Integration', () => {
     );
   });
 
-  it('should propagate SSE progress events to useGenerationProgress state', async () => {
+  it('should propagate SSE progress events to useYieldProgress state', async () => {
     const testResourceUri = resourceUri('http://localhost:4000/resources/test-resource');
     const testAnnotationUri = annotationUri('http://localhost:4000/resources/test-resource/annotations/test-annotation');
 
-    const { emitGenerationStart, getEventBus } = renderGenerationFlow(
+    const { emitGenerationStart, getEventBus } = renderYieldFlow(
       testResourceUri
     );
 
@@ -167,7 +167,7 @@ describe('Generation Flow - Feature Integration', () => {
 
     // Simulate SSE progress callback being invoked
     act(() => {
-      getEventBus().get('generate:progress').next({
+      getEventBus().get('yield:progress').next({
         status: 'generating',
         message: 'Generating content...',
         percentage: 25,
@@ -185,7 +185,7 @@ describe('Generation Flow - Feature Integration', () => {
     const testResourceUri = resourceUri('http://localhost:4000/resources/test-resource');
     const testAnnotationUri = annotationUri('http://localhost:4000/resources/test-resource/annotations/test-annotation');
 
-    const { emitGenerationStart, getEventBus } = renderGenerationFlow(
+    const { emitGenerationStart, getEventBus } = renderYieldFlow(
       testResourceUri
     );
 
@@ -203,7 +203,7 @@ describe('Generation Flow - Feature Integration', () => {
 
     // First progress update
     act(() => {
-      getEventBus().get('generate:progress').next({
+      getEventBus().get('yield:progress').next({
         status: 'started',
         message: 'Starting generation...',
         percentage: 0,
@@ -216,7 +216,7 @@ describe('Generation Flow - Feature Integration', () => {
 
     // Second progress update
     act(() => {
-      getEventBus().get('generate:progress').next({
+      getEventBus().get('yield:progress').next({
         status: 'generating',
         message: 'Creating document structure...',
         percentage: 50,
@@ -229,7 +229,7 @@ describe('Generation Flow - Feature Integration', () => {
 
     // Final progress update via onComplete
     act(() => {
-      getEventBus().get('generate:finished').next({
+      getEventBus().get('yield:finished').next({
         status: 'complete',
         referenceId: testAnnotationUri,
         message: 'Document created successfully',
@@ -248,7 +248,7 @@ describe('Generation Flow - Feature Integration', () => {
     const testResourceUri = resourceUri('http://localhost:4000/resources/test-resource');
     const testAnnotationUri = annotationUri('http://localhost:4000/resources/test-resource/annotations/test-annotation');
 
-    const { emitGenerationStart, getEventBus } = renderGenerationFlow(
+    const { emitGenerationStart, getEventBus } = renderYieldFlow(
       testResourceUri
     );
 
@@ -266,7 +266,7 @@ describe('Generation Flow - Feature Integration', () => {
 
     // Simulate completion with final chunk
     act(() => {
-      getEventBus().get('generate:progress').next({
+      getEventBus().get('yield:progress').next({
         status: 'complete',
         message: 'Complete',
         resourceName: 'Generated Document',
@@ -275,7 +275,7 @@ describe('Generation Flow - Feature Integration', () => {
 
     // Emit completion event
     act(() => {
-      getEventBus().get('generate:finished').next({
+      getEventBus().get('yield:finished').next({
         status: 'complete',
         referenceId: testAnnotationUri,
         resourceName: 'Generated Document',
@@ -291,7 +291,7 @@ describe('Generation Flow - Feature Integration', () => {
     const testResourceUri = resourceUri('http://localhost:4000/resources/test-resource');
     const testAnnotationUri = annotationUri('http://localhost:4000/resources/test-resource/annotations/test-annotation');
 
-    const { emitGenerationStart, getEventBus } = renderGenerationFlow(
+    const { emitGenerationStart, getEventBus } = renderYieldFlow(
       testResourceUri
     );
 
@@ -305,7 +305,7 @@ describe('Generation Flow - Feature Integration', () => {
 
     // Add some progress
     act(() => {
-      getEventBus().get('generate:progress').next({
+      getEventBus().get('yield:progress').next({
         status: 'generating',
         message: 'Generating...',
       });
@@ -317,7 +317,7 @@ describe('Generation Flow - Feature Integration', () => {
 
     // Emit failure
     act(() => {
-      getEventBus().get('generate:failed').next({ error: new Error('Network error') });
+      getEventBus().get('yield:failed').next({ error: new Error('Network error') });
     });
 
     // Verify: progress cleared and not generating
@@ -331,13 +331,13 @@ describe('Generation Flow - Feature Integration', () => {
     const testResourceUri = resourceUri('http://localhost:4000/resources/test-resource');
     const testAnnotationUri = annotationUri('http://localhost:4000/resources/test-resource/annotations/test-annotation');
 
-    const { emitGenerationStart, getEventBus } = renderGenerationFlow(
+    const { emitGenerationStart, getEventBus } = renderYieldFlow(
       testResourceUri
     );
 
     // Add an additional event listener (simulating multiple subscribers)
     const additionalListener = vi.fn();
-    const subscription = getEventBus().get('generate:request').subscribe(additionalListener);
+    const subscription = getEventBus().get('yield:request').subscribe(additionalListener);
 
     // Trigger generation
     act(() => {
@@ -365,7 +365,7 @@ describe('Generation Flow - Feature Integration', () => {
     const testResourceUri = resourceUri('http://localhost:4000/resources/test-resource');
     const testAnnotationUri = annotationUri('http://localhost:4000/resources/test-resource/annotations/test-annotation');
 
-    const { emitGenerationStart, getEventBus } = renderGenerationFlow(
+    const { emitGenerationStart, getEventBus } = renderYieldFlow(
       testResourceUri
     );
 
@@ -383,7 +383,7 @@ describe('Generation Flow - Feature Integration', () => {
 
     // Simulate onComplete with final chunk
     act(() => {
-      getEventBus().get('generate:finished').next({
+      getEventBus().get('yield:finished').next({
         status: 'complete',
         referenceId: testAnnotationUri,
         message: 'Document created: My Document',
@@ -401,10 +401,10 @@ describe('Generation Flow - Feature Integration', () => {
 });
 
 /**
- * Helper: Render useGenerationFlow hook with real component composition
+ * Helper: Render useYieldFlow hook with real component composition
  * Returns methods to interact with the rendered component
  */
-function renderGenerationFlow(
+function renderYieldFlow(
   testResourceUri: ResourceUri
 ) {
   let eventBusInstance: Emitter<EventMap>;
@@ -414,19 +414,19 @@ function renderGenerationFlow(
     eventBusInstance = useEventBus();
 
     // Set up resolution flow (resolve:update-body, resolve:link)
-    useResolutionFlow(testResourceUri);
+    useBindFlow(testResourceUri);
 
     return null;
   }
 
   // Test harness component that uses the hook
-  function GenerationFlowTestHarness() {
+  function YieldFlowTestHarness() {
     const {
       generationProgress,
       generationModalOpen,
       generationReferenceId,
       generationDefaultTitle,
-    } = useGenerationFlow(
+    } = useYieldFlow(
       'en',
       testResourceUri.split('/resources/')[1] || 'test-resource',
       vi.fn()
@@ -452,7 +452,7 @@ function renderGenerationFlow(
       <AuthTokenProvider token={null}>
         <ApiClientProvider baseUrl="http://localhost:4000">
           <EventBusCapture />
-          <GenerationFlowTestHarness />
+          <YieldFlowTestHarness />
         </ApiClientProvider>
       </AuthTokenProvider>
     </EventBusProvider>
@@ -464,7 +464,7 @@ function renderGenerationFlow(
       resourceUri: ResourceUri,
       defaultTitle: string
     ) => {
-      eventBusInstance.get('generate:modal-open').next({
+      eventBusInstance.get('yield:modal-open').next({
         annotationUri,
         resourceUri,
         defaultTitle,
@@ -482,7 +482,7 @@ function renderGenerationFlow(
         context: any;
       }
     ) => {
-      eventBusInstance.get('generate:request').next({
+      eventBusInstance.get('yield:request').next({
         annotationUri,
         resourceUri,
         options,

package/src/features/resource-viewer/__tests__/annotation-progress-flow.test.tsx

@@ -1,12 +1,12 @@
 /**
  * Layer 3 Integration Test: Detection Progress Flow UI/UX
  *
- * Tests the complete data flow from UI → EventBus → useResolutionFlow → SSE (mocked)
+ * Tests the complete data flow from UI → EventBus → useBindFlow → SSE (mocked)
  *
  * This test uses COMPOSITION instead of mocking:
- * - Real React components composed together (useAnnotationFlow + HighlightPanel + AssistSection)
+ * - Real React components composed together (useMarkFlow + HighlightPanel + AssistSection)
  * - Real EventBus (mitt) passed via context
- * - Real useResolutionFlow hook with mock API client passed as prop
+ * - Real useBindFlow hook with mock API client passed as prop
  * - Mock SSE stream (simulated API responses) provided via composition
  *
  * This test focuses on USER EXPERIENCE:
@@ -19,7 +19,7 @@
  * - That test verifies SYSTEM ARCHITECTURE (event wiring, API call count)
  * - This test verifies USER EXPERIENCE (button clicks, UI feedback)
  *
- * UPDATED: Now tests useAnnotationFlow hook instead of DetectionFlowContainer
+ * UPDATED: Now tests useMarkFlow hook instead of DetectionFlowContainer
  */
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
@@ -27,7 +27,7 @@ import { render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { act } from 'react';
 import { HighlightPanel } from '../../../components/resource/panels/HighlightPanel';
-import { useAnnotationFlow } from '../../../hooks/useAnnotationFlow';
+import { useMarkFlow } from '../../../hooks/useMarkFlow';
 import { EventBusProvider, resetEventBusForTesting } from '../../../contexts/EventBusContext';
 import { ApiClientProvider } from '../../../contexts/ApiClientContext';
 import { AuthTokenProvider } from '../../../contexts/AuthTokenContext';
@@ -79,18 +79,18 @@ class MockSSEStream {
 
   // Test helper methods that emit to EventBus
   emitProgress(chunk: any) {
-    this.eventBus.get('annotate:progress').next(chunk);
+    this.eventBus.get('mark:progress').next(chunk);
   }
 
   emitComplete(finalChunk?: any, motivation: string = 'highlighting') {
     if (finalChunk) {
-      this.eventBus.get('annotate:progress').next(finalChunk);
+      this.eventBus.get('mark:progress').next(finalChunk);
     }
-    this.eventBus.get('annotate:assist-finished').next({ motivation });
+    this.eventBus.get('mark:assist-finished').next({ motivation });
   }
 
   emitError(error: Error) {
-    this.eventBus.get('annotate:assist-failed').next({
+    this.eventBus.get('mark:assist-failed').next({
       type: 'job.failed' as const,
       resourceId: 'test' as any,
       userId: 'user' as any,
@@ -114,7 +114,7 @@ function DetectionFlowTestHarness({
   rUri: string;
   annotations: Annotation[];
 }) {
-  const { assistingMotivation, progress } = useAnnotationFlow(rUri as any);
+  const { assistingMotivation, progress } = useMarkFlow(rUri as any);
 
   return (
     <HighlightPanel
@@ -305,7 +305,7 @@ describe('Detection Progress Flow Integration (Layer 3)', () => {
     });
   });
 
-  it('should clear progress on annotate:assist-failed', async () => {
+  it('should clear progress on mark:assist-failed', async () => {
     const user = userEvent.setup();
 
     renderDetectionFlow();

package/src/features/resource-viewer/components/ResourceViewerPage.tsx

@@ -37,12 +37,12 @@ import { useEventBus } from '../../../contexts/EventBusContext';
 import { useEventSubscriptions } from '../../../contexts/useEventSubscription';
 import { useResourceAnnotations } from '../../../contexts/ResourceAnnotationsContext';
 import { useApiClient } from '../../../contexts/ApiClientContext';
-import { useResolutionFlow } from '../../../hooks/useResolutionFlow';
-import { useAnnotationFlow } from '../../../hooks/useAnnotationFlow';
-import { useAttentionFlow } from '../../../hooks/useAttentionFlow';
-import { usePanelNavigation } from '../../../hooks/usePanelNavigation';
-import { useGenerationFlow } from '../../../hooks/useGenerationFlow';
-import { useContextCorrelationFlow } from '../../../hooks/useContextCorrelationFlow';
+import { useBindFlow } from '../../../hooks/useBindFlow';
+import { useMarkFlow } from '../../../hooks/useMarkFlow';
+import { useBeckonFlow } from '../../../hooks/useBeckonFlow';
+import { usePanelBrowse } from '../../../hooks/usePanelBrowse';
+import { useYieldFlow } from '../../../hooks/useYieldFlow';
+import { useContextGatherFlow } from '../../../hooks/useContextGatherFlow';
 
 type SemiontResource = components['schemas']['ResourceDescriptor'];
 type Annotation = components['schemas']['Annotation'];
@@ -91,18 +91,18 @@ export interface ResourceViewerPageProps {
  *
  * Uses hooks directly (NO containers, NO render props, NO ResourceViewerPageContent wrapper)
  *
- * @emits navigation:router-push - Navigate to a resource or filtered view
- * @emits attend:sparkle - Trigger sparkle animation on an annotation
- * @emits resolve:update-body - Update annotation body content
- * @subscribes resource:archive - Archive the current resource
- * @subscribes resource:unarchive - Unarchive the current resource
- * @subscribes generate:clone - Clone the current resource
- * @subscribes attend:sparkle - Trigger sparkle animation
- * @subscribes annotate:added - Annotation was created
- * @subscribes annotate:removed - Annotation was deleted
- * @subscribes annotate:create-failed - Annotation creation failed
- * @subscribes annotate:delete-failed - Annotation deletion failed
- * @subscribes annotate:body-updated - Annotation body was updated
+ * @emits browse:router-push - Navigate to a resource or filtered view
+ * @emits beckon:sparkle - Trigger sparkle animation on an annotation
+ * @emits bind:update-body - Update annotation body content
+ * @subscribes mark:archive - Archive the current resource
+ * @subscribes mark:unarchive - Unarchive the current resource
+ * @subscribes yield:clone - Clone the current resource
+ * @subscribes beckon:sparkle - Trigger sparkle animation
+ * @subscribes mark:added - Annotation was created
+ * @subscribes mark:removed - Annotation was deleted
+ * @subscribes mark:create-failed - Annotation creation failed
+ * @subscribes mark:delete-failed - Annotation deletion failed
+ * @subscribes mark:body-updated - Annotation body was updated
  * @subscribes annotate:body-update-failed - Annotation body update failed
  * @subscribes settings:theme-changed - UI theme changed
  * @subscribes settings:line-numbers-toggled - Line numbers display toggled
@@ -110,8 +110,8 @@ export interface ResourceViewerPageProps {
  * @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
+ * @subscribes browse:reference-navigate - Navigate to a referenced document
+ * @subscribes browse:entity-type-clicked - Navigate filtered by entity type
  */
 export function ResourceViewerPage({
   resource,
@@ -157,10 +157,10 @@ export function ResourceViewerPage({
   const allEntityTypes = (entityTypesData as { entityTypes: string[] } | undefined)?.entityTypes || [];
 
   // Flow state hooks (NO CONTAINERS)
-  const { hoveredAnnotationId } = useAttentionFlow();
-  const { assistingMotivation, progress, pendingAnnotation } = useAnnotationFlow(rUri);
-  const { activePanel, scrollToAnnotationId, panelInitialTab, onScrollCompleted } = usePanelNavigation();
-  const { searchModalOpen, pendingReferenceId, onCloseSearchModal } = useResolutionFlow(rUri);
+  const { hoveredAnnotationId } = useBeckonFlow();
+  const { assistingMotivation, progress, pendingAnnotation } = useMarkFlow(rUri);
+  const { activePanel, scrollToAnnotationId, panelInitialTab, onScrollCompleted } = usePanelBrowse();
+  const { searchModalOpen, pendingReferenceId, onCloseSearchModal } = useBindFlow(rUri);
   const {
     generationProgress,
     generationModalOpen,
@@ -168,8 +168,8 @@ export function ResourceViewerPage({
     generationDefaultTitle,
     onGenerateDocument,
     onCloseGenerationModal,
-  } = useGenerationFlow(locale, rUri.split('/').pop() || '', clearNewAnnotationId);
-  const { correlationContext, correlationLoading, correlationError } = useContextCorrelationFlow(eventBus, { client, resourceUri: rUri });
+  } = useYieldFlow(locale, rUri.split('/').pop() || '', clearNewAnnotationId);
+  const { gatherContext, gatherLoading, gatherError } = useContextGatherFlow(eventBus, { client, resourceUri: rUri });
 
   // Debounced invalidation for real-time events
   const debouncedInvalidateAnnotations = useDebouncedCallback(
@@ -305,7 +305,7 @@ export function ResourceViewerPage({
     try {
       const result = await generateCloneTokenMutation.mutateAsync(rUri);
       const token = result.token;
-      eventBus.get('navigation:router-push').next({ path: `/know/compose?mode=clone&token=${token}`, reason: 'clone' });
+      eventBus.get('browse:router-push').next({ path: `/know/compose?mode=clone&token=${token}`, reason: 'clone' });
     } catch (err) {
       console.error('Failed to generate clone token:', err);
       showError('Failed to generate clone link');
@@ -331,56 +331,56 @@ export function ResourceViewerPage({
   const handleSettingsThemeChanged = useCallback(({ theme }: { theme: any }) => setTheme(theme), [setTheme]);
 
   const handleDetectionComplete = useCallback(() => {
-    // Toast notification is handled by useAnnotationFlow
+    // Toast notification is handled by useMarkFlow
     queryClient.invalidateQueries({ queryKey: QUERY_KEYS.resources.annotations(rUri) });
     queryClient.invalidateQueries({ queryKey: QUERY_KEYS.resources.events(rUri) });
   }, [queryClient, rUri]);
   const handleDetectionFailed = useCallback(() => {
-    // Error notification is handled by useAnnotationFlow
+    // Error notification is handled by useMarkFlow
     queryClient.invalidateQueries({ queryKey: QUERY_KEYS.resources.annotations(rUri) });
     queryClient.invalidateQueries({ queryKey: QUERY_KEYS.resources.events(rUri) });
   }, [queryClient, rUri]);
   const handleGenerationComplete = useCallback(() => {
-    // Toast notification is handled by useGenerationFlow
+    // Toast notification is handled by useYieldFlow
   }, []);
   const handleGenerationFailed = useCallback(() => {
-    // Error notification is handled by useGenerationFlow
+    // Error notification is handled by useYieldFlow
   }, []);
 
   const handleReferenceNavigate = useCallback(({ documentId }: { documentId: string }) => {
     if (routes.resource) {
       const path = routes.resource.replace('[resourceId]', encodeURIComponent(documentId));
-      eventBus.get('navigation:router-push').next({ path, reason: 'reference-link' });
+      eventBus.get('browse:router-push').next({ path, reason: 'reference-link' });
     }
   }, [routes.resource]); // eventBus is stable singleton - never in deps
 
   const handleEntityTypeClicked = useCallback(({ entityType }: { entityType: string }) => {
     if (routes.know) {
       const path = `${routes.know}?entityType=${encodeURIComponent(entityType)}`;
-      eventBus.get('navigation:router-push').next({ path, reason: 'entity-type-filter' });
+      eventBus.get('browse:router-push').next({ path, reason: 'entity-type-filter' });
     }
   }, [routes.know]); // eventBus is stable singleton - never in deps
 
   // Event bus subscriptions (combined into single useEventSubscriptions call to prevent hook ordering issues)
   useEventSubscriptions({
-    'resource:archive': handleResourceArchive,
-    'resource:unarchive': handleResourceUnarchive,
-    'generate:clone': handleResourceClone,
-    'attend:sparkle': handleAnnotationSparkle,
-    'annotate:added': handleAnnotationAdded,
-    'annotate:removed': debouncedInvalidateAnnotations,
-    'annotate:create-failed': handleAnnotationCreateFailed,
-    'annotate:delete-failed': handleAnnotationDeleteFailed,
-    'annotate:body-updated': handleAnnotateBodyUpdated,
-    'resolve:body-update-failed': handleAnnotateBodyUpdateFailed,
+    'mark:archive': handleResourceArchive,
+    'mark:unarchive': handleResourceUnarchive,
+    'yield:clone': handleResourceClone,
+    'beckon:sparkle': handleAnnotationSparkle,
+    'mark:added': handleAnnotationAdded,
+    'mark:removed': debouncedInvalidateAnnotations,
+    'mark:create-failed': handleAnnotationCreateFailed,
+    'mark:delete-failed': handleAnnotationDeleteFailed,
+    'mark:body-updated': handleAnnotateBodyUpdated,
+    'bind:body-update-failed': handleAnnotateBodyUpdateFailed,
     'settings:theme-changed': handleSettingsThemeChanged,
     'settings:line-numbers-toggled': toggleLineNumbers,
-    'annotate:assist-finished': handleDetectionComplete,
-    'annotate:assist-failed': handleDetectionFailed,
-    'generate:finished': handleGenerationComplete,
-    'generate:failed': handleGenerationFailed,
-    'navigation:reference-navigate': handleReferenceNavigate,
-    'navigation:entity-type-clicked': handleEntityTypeClicked,
+    'mark:assist-finished': handleDetectionComplete,
+    'mark:assist-failed': handleDetectionFailed,
+    'yield:finished': handleGenerationComplete,
+    'yield:failed': handleGenerationFailed,
+    'browse:reference-navigate': handleReferenceNavigate,
+    'browse:entity-type-clicked': handleEntityTypeClicked,
   });
 
   // Resource loading announcements
@@ -443,7 +443,7 @@ export function ResourceViewerPage({
   // Handlers for AnnotationHistory (legacy event-based interaction)
   const handleEventHover = useCallback((annotationId: string | null) => {
     if (annotationId) {
-      eventBus.get('attend:sparkle').next({ annotationId });
+      eventBus.get('beckon:sparkle').next({ annotationId });
     }
   }, []); // eventBus is stable singleton - never in deps
 
@@ -611,7 +611,7 @@ export function ResourceViewerPage({
               const resourceIdSegment = rUri.split('/').pop() || '';
               const nestedUri = `${window.location.origin}/resources/${resourceIdSegment}/annotations/${annotationIdShort}`;
 
-              eventBus.get('resolve:update-body').next({
+              eventBus.get('bind:update-body').next({
                 annotationUri: resourceAnnotationUri(nestedUri),
                 resourceId: resourceIdSegment,
                 operations: [{
@@ -624,7 +624,7 @@ export function ResourceViewerPage({
                 }],
               });
               showSuccess('Reference linked successfully');
-              // Cache invalidation now handled by annotate:body-updated event
+              // Cache invalidation now handled by mark:body-updated event
               onCloseSearchModal();
             } catch (error) {
               console.error('Failed to link reference:', error);
@@ -644,9 +644,9 @@ export function ResourceViewerPage({
           }
         }}
         defaultTitle={generationDefaultTitle}
-        context={correlationContext}
-        contextLoading={correlationLoading}
-        contextError={correlationError}
+        context={gatherContext}
+        contextLoading={gatherLoading}
+        contextError={gatherError}
       />
     </div>
   );