@semiont/react-ui 0.5.26 → 0.5.28

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

@@ -6,10 +6,12 @@
  */
 
 import React, { useState, useEffect, useCallback } from 'react';
-import type { components, ResourceDescriptor, ResourceId, GatheredContext, EventMap } from '@semiont/core';
+import { useResourceViewedReport } from '../hooks/useResourceViewedReport';
+import type { components, ResourceDescriptor, ResourceId, EventMap } from '@semiont/core';
 import type { ConnectionState } from '@semiont/core';
 import { annotationId } from '@semiont/core';
-import { getLanguage, getPrimaryRepresentation, getPrimaryMediaType, capabilitiesOf } from '@semiont/core';
+import type { ComposeParams } from '../../../components/modals/ComposeStep';
+import { getLanguage, getPrimaryRepresentation, getPrimaryMediaType, capabilitiesOf, extensionForMediaType } from '@semiont/core';
 import { ANNOTATORS } from '@semiont/react-ui';
 import { ErrorBoundary } from '@semiont/react-ui';
 import { AnnotationHistory } from '@semiont/react-ui';
@@ -24,9 +26,11 @@ import type { BrowseMediaRenderers, AnnotateMediaRenderers } from '@semiont/reac
 import { useObservable } from '@semiont/react-ui';
 import { useResourceContent } from '../../../hooks/useResourceContent';
 import { useMediaToken } from '../../../hooks/useMediaToken';
+import { useCollaborators } from '../../../hooks/useCollaborators';
 import { mediaUrl } from '../../../lib/media-url';
 import { useToast } from '../../../components/Toast';
 import { useOutcomeToasts } from '../../../hooks/useOutcomeToasts';
+import { useGenerationArrival } from '../../../hooks/useGenerationArrival';
 import { useTheme } from '../../../contexts/ThemeContext';
 import { useLineNumbers } from '../../../contexts/LineNumbersContext';
 import { useHoverDelay } from '../../../hooks/useHoverDelay';
@@ -42,7 +46,6 @@ import { useShellStateUnit } from '../../../hooks/useShellStateUnit';
 import { useTranslations } from '../../../contexts/TranslationContext';
 import { ReferenceWizardModal } from '../../../components/modals/ReferenceWizardModal';
 import { ResourceGenerateModal } from '../../../components/modals/ResourceGenerateModal';
-import { AssistProgress } from '../../../components/AssistProgress';
 import type { GenerationConfig } from '../../../components/modals/ConfigureGenerationStep';
 
 type SemiontResource = ResourceDescriptor;
@@ -117,7 +120,8 @@ export interface ResourceViewerPageProps {
  * @subscribes yield:clone - Clone the current resource
  * @subscribes beckon:sparkle - Trigger sparkle animation
  * @subscribes mark:added - Annotation was created (sparkle)
- * @subscribes browse:reference-navigate - Navigate to a referenced document
+ * @subscribes mark:body-updated - Reference resolved via a linking-add operation (sparkle, both loci)
+ * @subscribes browse:resource-open - Open a resource in the viewer (local links + the launcher's tour verbs)
  * @subscribes browse:entity-type-clicked - Navigate filtered by entity type
  *
  * Outcome-notification channels (mark:create-error, mark:delete-error,
@@ -140,13 +144,24 @@ export function ResourceViewerPage({
   // Translations
   const tw = useTranslations('ReferenceWizard');
   const tg = useTranslations('ResourceGenerate');
-  const ta = useTranslations('AssistProgress');
 
   const browser = useSemiont();
   const session = useObservable(browser.activeSession$);
   const semiont = session?.client;
   const navigateExternal = useObservableExternalNavigation();
 
+  // The KB's collaborator roster, for the Collaboration panel's software-agent
+  // rows. Subscribed unconditionally at the top level (hooks ordering) even
+  // though only one panel reads it; the underlying cache is a KB-wide
+  // singleton, so this costs one shared subscription, not one per panel open.
+  const { collaborators } = useCollaborators(semiont ?? null);
+
+  // At most one entry serves `generation` — the KB's workers.* config yields one
+  // inference config per job type — so `find` is exact, not a first-wins guess.
+  const generationAgent = collaborators.find((entry) =>
+    entry.servesJobTypes?.includes('generation'),
+  );
+
   // ResourceViewer is bring-your-own-session: feed it the active session plus
   // host-owned navigation (reference follow) and panel control (app-scoped bus).
   const handleViewerOpenResource = useCallback((id: string) => {
@@ -162,7 +177,7 @@ export function ResourceViewerPage({
   const { theme } = useTheme();
   const { showLineNumbers } = useLineNumbers();
   const { hoverDelayMs } = useHoverDelay();
-  const { triggerSparkleAnimation, clearNewAnnotationId, newAnnotationIds } = useResourceAnnotations();
+  const { triggerSparkleAnimation, clearSparkle, sparkleAnnotationIds } = useResourceAnnotations();
 
   // Render mode chooses the content path: 'text' decodes inline; 'image'
   // and 'pdf' go through the media-token (binary) path. 'none'/registry-miss
@@ -224,9 +239,28 @@ export function ResourceViewerPage({
   const panelInitialTab = useObservable(stateUnit?.browse.panelInitialTab$) ?? null;
   const onScrollCompleted = stateUnit?.browse.onScrollCompleted;
   const generationProgress = useObservable(stateUnit?.yield.progress$) ?? null;
+  const isGenerating = useObservable(stateUnit?.yield.isGenerating$) ?? false;
+  const generationOutcome = useObservable(stateUnit?.yield.outcome$) ?? null;
+
+  // GENERATION-ARRIVAL P2: a completion witnessed on this page reveals the
+  // derivation edge the worker minted — the annotations panel opens on
+  // References, scrolls to the provenance reference, and its sparkle is
+  // re-armed (the mark:added glow burned its window unseen). Never navigates
+  // (A2); a held outcome on remount stays quiet (D6, inside the hook).
+  const handleGenerationArrival = useCallback((annId: string) => {
+    browser.emit('panel:open', { panel: 'annotations', scrollToAnnotationId: annId, motivation: 'linking' });
+    triggerSparkleAnimation(annId);
+  }, [browser, triggerSparkleAnimation]);
+  useGenerationArrival(generationOutcome, annotations, handleGenerationArrival);
+
   const gatherContext = useObservable(stateUnit?.gather.context$) ?? null;
   const gatherLoading = useObservable(stateUnit?.gather.loading$) ?? false;
   const gatherError = useObservable(stateUnit?.gather.error$) ?? null;
+  // Resource-gather slots (FLOW-LIFECYCLE-CONVERGENCE D2a: separate from the
+  // annotation slots above — the two gathers can be live at once).
+  const resourceGatherContext = useObservable(stateUnit?.gather.resourceContext$) ?? null;
+  const resourceGatherLoading = useObservable(stateUnit?.gather.resourceLoading$) ?? false;
+  const resourceGatherError = useObservable(stateUnit?.gather.resourceError$) ?? null;
   const wizardState = useObservable(stateUnit?.wizard$);
   const wizardOpen = wizardState?.open ?? false;
   const wizardAnnotationId = wizardState?.annotationId ?? null;
@@ -240,8 +274,8 @@ export function ResourceViewerPage({
   }, [stateUnit]);
 
   const handleWizardGenerateSubmit = useCallback((referenceId: string, config: GenerationConfig) => {
-    clearNewAnnotationId(annotationId(referenceId));
-    stateUnit?.yield.generate(referenceId, {
+    clearSparkle(annotationId(referenceId));
+    stateUnit?.yield.generate(config.context, {
       title: config.title,
       storageUri: config.storagePath,
       prompt: config.prompt,
@@ -252,16 +286,15 @@ export function ResourceViewerPage({
       sourceLanguage: getLanguage(resource),
       temperature: config.temperature,
       maxTokens: config.maxTokens,
-      context: config.context,
     });
-  }, [stateUnit, clearNewAnnotationId, resource]);
+  }, [stateUnit, clearSparkle, resource]);
 
   // Resource-generate flow (GENERATE-FROM-BUTTON): drive the SAME yield progress$
-  // the annotation path uses so the full AnnotateReferencesProgressWidget shows —
-  // NOT a toast. `generateFromResource` is Phase 6 (the @semiont/sdk session);
-  // this is declared RED until that method lands. Do not re-impl it here.
+  // the annotation path uses so the full `AssistProgress` widget shows — NOT a
+  // toast. Both paths are one `generate(context, options)` now: the context's
+  // focus.kind (resource here, annotation above) decides the shape.
   const handleResourceGenerateSubmit = useCallback((_resourceId: string, config: GenerationConfig) => {
-    stateUnit?.yield.generateFromResource({
+    stateUnit?.yield.generate(config.context, {
       title: config.title,
       storageUri: config.storagePath,
       ...(config.prompt ? { prompt: config.prompt } : {}),
@@ -269,7 +302,6 @@ export function ResourceViewerPage({
       sourceLanguage: getLanguage(resource),
       temperature: config.temperature,
       maxTokens: config.maxTokens,
-      context: config.context,
     });
   }, [stateUnit, resource]);
 
@@ -287,26 +319,43 @@ export function ResourceViewerPage({
     }
   }, [rUri, semiont, showSuccess, showError]);
 
-  const handleWizardComposeNavigate = useCallback((
-    context: GatheredContext,
-    annId: string,
-    resId: string,
-    title: string,
-    entTypes: string[],
-  ) => {
-    // Store context in sessionStorage for the compose page
-    sessionStorage.setItem(`gather-context:${annId}`, JSON.stringify(context));
-    const params = new URLSearchParams({
-      annotationUri: annId,
-      sourceDocumentId: resId,
-      name: title,
-      entityTypes: entTypes.join(','),
-    });
-    browser.emit('nav:push', {
-      path: `/know/compose?${params.toString()}`,
-      reason: 'compose-from-wizard',
-    });
-  }, [browser]);
+  // COMPOSE-IN-MODAL P3: create-and-link, in place. The old flow stashed the
+  // context in sessionStorage and navigated to the compose page; the modal
+  // already holds the context, so the side-channel dies with the mode.
+  // Text-only by design — uploads stay on the standalone compose page.
+  const handleWizardComposeSubmit = useCallback(async (referenceId: string, params: ComposeParams) => {
+    if (!semiont) throw new Error('No active session');
+    try {
+      const format = 'text/markdown';
+      const file = new File(
+        [new Blob([params.content], { type: format })],
+        params.name + extensionForMediaType(format),
+        { type: format },
+      );
+      const newResourceId = await new Promise<ResourceId>((resolve, reject) => {
+        semiont.yield.resource({
+          name: params.name,
+          file,
+          format,
+          entityTypes: params.entityTypes,
+          language: params.language,
+          storageUri: params.storagePath,
+        }).subscribe({
+          next: (event) => { if (event.phase === 'finished') resolve(event.resourceId); },
+          error: reject,
+        });
+      });
+      await semiont.bind.body(
+        rUri,
+        annotationId(referenceId),
+        [{ op: 'add', item: { type: 'SpecificResource' as const, source: newResourceId, purpose: 'linking' as const } }],
+      );
+      showSuccess('Reference successfully linked to the new resource');
+    } catch (error) {
+      showError(`Failed to compose resource: ${error instanceof Error ? error.message : String(error)}`);
+      throw error; // ComposeStep re-enables its footer on rejection
+    }
+  }, [semiont, rUri, showSuccess, showError]);
 
   // Add resource to open tabs when it loads, and record it as this KB's
   // last-viewed for the /know landing route to resume from. Both are per-KB
@@ -378,7 +427,20 @@ export function ResourceViewerPage({
     triggerSparkleAnimation(stored.payload.annotation.id);
   }, [triggerSparkleAnimation]);
 
-  const handleReferenceNavigate = useCallback(({ resourceId }: { resourceId: string }) => {
+  // RESOLUTION-SPARKLE D2: a reference resolving — Compose, Search → Link, a
+  // Generate job landing, or a remote collaborator — is a body update whose
+  // operations add a linking SpecificResource. Exactly that sparkles; an unlink
+  // (remove) or an entity-tag body change stays dark.
+  const handleAnnotationBodyUpdated = useCallback((stored: EventMap['mark:body-updated']) => {
+    const resolves = stored.payload.operations.some(
+      (op) => op.op === 'add' && op.item.type === 'SpecificResource' && op.item.purpose === 'linking',
+    );
+    if (resolves) {
+      triggerSparkleAnimation(stored.payload.annotationId);
+    }
+  }, [triggerSparkleAnimation]);
+
+  const handleResourceOpen = useCallback(({ resourceId }: { resourceId: string }) => {
     if (routes.resourceDetail) {
       const path = routes.resourceDetail(resourceId);
       browser.emit('nav:push', { path, reason: 'reference-link' });
@@ -407,7 +469,8 @@ export function ResourceViewerPage({
     'yield:clone': handleResourceClone,
     'beckon:sparkle': handleAnnotationSparkle,
     'mark:added': handleAnnotationAdded,
-    'browse:reference-navigate': handleReferenceNavigate,
+    'mark:body-updated': handleAnnotationBodyUpdated,
+    'browse:resource-open': handleResourceOpen,
     'browse:entity-type-clicked': handleEntityTypeClicked,
   });
 
@@ -426,6 +489,11 @@ export function ResourceViewerPage({
     }
   }, [contentLoading, content, resource.name, announceResourceLoading, announceResourceLoaded]);
 
+  // Report the arrival on the wire (browse:resource-viewed) — same
+  // load-complete condition the announcement uses, so "viewed" means the
+  // content is actually on screen (GUIDED-TOUR P5, D6).
+  useResourceViewedReport(rUri, !contentLoading && !!content);
+
   // Derived state
   const documentEntityTypes = resource.entityTypes || [];
 
@@ -471,24 +539,6 @@ export function ResourceViewerPage({
               </h2>
             </div>
           </div>
-          {/* Resource-generation progress (GENERATE-FROM-BUTTON P7) — no annotationId ⇒ a resource-gen job */}
-          {generationProgress && !generationProgress.annotationId && (
-            <AssistProgress
-              progress={generationProgress}
-              dataType="generation"
-              onCancel={() => session?.client.job.cancelRequest('generation')}
-              translations={{
-                title: tg('progressTitle'),
-                cancel: tg('progressCancel'),
-                inProgress: tg('progressInProgress'),
-                complete: tg('progressComplete'),
-                failed: tg('progressFailed'),
-                paramsTitle: ta('paramsTitle'),
-                processing: (label) => ta('processing', { label }),
-                close: ta('close'),
-              }}
-            />
-          )}
           {/* Scrollable body wrapper - contains document content, header is sibling above */}
           <div className="semiont-document-viewer__scrollable-body" lang={getLanguage(resource) || undefined}>
             <ErrorBoundary
@@ -528,7 +578,7 @@ export function ResourceViewerPage({
                   onSelectionMotivationChange={toolbarPrefs.setSelectionMotivation}
                   shape={toolbarPrefs.shape}
                   onShapeChange={toolbarPrefs.setShape}
-                  newAnnotationIds={newAnnotationIds}
+                  sparkleAnnotationIds={sparkleAnnotationIds}
                   generatingReferenceId={generationProgress?.annotationId ?? null}
                   showLineNumbers={showLineNumbers}
                   hoverDelayMs={hoverDelayMs}
@@ -578,6 +628,7 @@ export function ResourceViewerPage({
                 onRetryAnnotations={stateUnit?.annotations.retry}
                 entityTypesError={entityTypesError}
                 generatingReferenceId={generationProgress?.annotationId ?? null}
+                sparkleAnnotationIds={sparkleAnnotationIds}
                 referencedBy={referencedBy}
                 referencedByLoading={referencedByLoading}
                 referencedByError={referencedByError}
@@ -588,7 +639,7 @@ export function ResourceViewerPage({
                 scrollToAnnotationId={scrollToAnnotationId}
                 hoveredAnnotationId={hoveredAnnotationId}
                 onScrollCompleted={onScrollCompleted}
-                initialTab={panelInitialTab?.tab as any}
+                initialTab={panelInitialTab?.tab}
                 initialTabGeneration={panelInitialTab?.generation}
                 Link={Link}
                 routes={routes}
@@ -628,6 +679,15 @@ export function ResourceViewerPage({
                 wasDerivedFrom={resource.wasDerivedFrom}
                 generator={resource.generator as components['schemas']['Agent'] | components['schemas']['Agent'][] | undefined}
                 onGenerate={() => setGenerateOpen(true)}
+                // The panel is generation's progress surface (GENERATE-FROM-
+                // RESOURCE D7); no annotationId ⇒ a resource-gen job — the
+                // annotation path's frame renders in the reference wizard.
+                isGenerating={isGenerating}
+                generationProgress={
+                  generationProgress && !generationProgress.annotationId ? generationProgress : null
+                }
+                generationOutcome={generationOutcome}
+                onDismissProgress={() => stateUnit?.yield.dismissProgress()}
               />
             )}
 
@@ -637,6 +697,7 @@ export function ResourceViewerPage({
                 state={streamStatus}
                 eventCount={0}
                 knowledgeBaseName={knowledgeBaseName}
+                collaborators={collaborators}
               />
             )}
 
@@ -657,32 +718,40 @@ export function ResourceViewerPage({
 
       {/* Reference Resolution Wizard */}
       <ReferenceWizardModal
+        {...(generationAgent ? { generationAgent } : {})}
         isOpen={wizardOpen}
         onClose={handleWizardClose}
         annotationId={wizardAnnotationId}
         resourceId={wizardResourceId}
         defaultTitle={wizardDefaultTitle}
         entityTypes={wizardEntityTypes}
+        resourceName={resource.name}
         locale={locale}
         context={gatherContext}
         contextLoading={gatherLoading}
         contextError={gatherError}
         onGenerateSubmit={handleWizardGenerateSubmit}
         onLinkResource={handleWizardLinkResource}
-        onComposeNavigate={handleWizardComposeNavigate}
+        onComposeSubmit={handleWizardComposeSubmit}
+        entityTypeOptions={allEntityTypes}
+        hoverDelayMs={hoverDelayMs}
         translations={{
-          gatherTitle: tw('gatherTitle'),
-          configureGenerationTitle: tw('configureGenerationTitle'),
-          configureSearchTitle: tw('configureSearchTitle'),
-          searchResultsTitle: tw('searchResultsTitle'),
+          resolveTitle: tw('resolveTitle'),
           sourceContextLabel: tw('sourceContextLabel'),
           connectionsLabel: tw('connectionsLabel'),
           citedByLabel: tw('citedByLabel'),
           userHintLabel: tw('userHintLabel'),
+          userHintEffect: tw('userHintEffect'),
           userHintPlaceholder: tw('userHintPlaceholder'),
+          graphPaneTitle: tw('graphPaneTitle'),
+          graphEmpty: tw('graphEmpty'),
+          resourceLinkLabel: tw('resourceLinkLabel'),
+          corpusPaneTitle: tw('corpusPaneTitle'),
+          corpusEmpty: tw('corpusEmpty'),
+          excludedReceipt: tw('excludedReceipt'),
+          machineRead: tw('machineRead'),
           loadingContext: tw('loadingContext'),
           failedContext: tw('failedContext'),
-          cancel: tw('cancel'),
           search: tw('search'),
           searching: tw('searching'),
           generate: tw('generate'),
@@ -694,6 +763,7 @@ export function ResourceViewerPage({
           noResults: tw('noResults'),
           resourceTitle: tw('resourceTitle'),
           resourceTitlePlaceholder: tw('resourceTitlePlaceholder'),
+          saveLocation: tw('saveLocation'),
           additionalInstructions: tw('additionalInstructions'),
           additionalInstructionsPlaceholder: tw('additionalInstructionsPlaceholder'),
           language: tw('language'),
@@ -703,42 +773,63 @@ export function ResourceViewerPage({
           creativityCreative: tw('creativityCreative'),
           maxLength: tw('maxLength'),
           maxLengthHelp: tw('maxLengthHelp'),
+          maxLengthCeiling: tw('maxLengthCeiling'),
           maxResults: tw('maxResults'),
           semanticScoring: tw('semanticScoring'),
           semanticScoringHelp: tw('semanticScoringHelp'),
+          searchFailed: tw('searchFailed'),
+          entityTypes: tw('entityTypes'),
+          contentLabel: tw('contentLabel'),
+          createAndLink: tw('createAndLink'),
+          creatingAndLinking: tw('creatingAndLinking'),
+          discardDraftPrompt: tw('discardDraftPrompt'),
+          discardDraft: tw('discardDraft'),
+          keepEditing: tw('keepEditing'),
         }}
       />
 
       {/* Resource-generate flow (GENERATE-FROM-BUTTON) */}
       <ResourceGenerateModal
+        {...(generationAgent ? { generationAgent } : {})}
         isOpen={generateOpen}
         onClose={() => setGenerateOpen(false)}
         resourceId={rUri}
-        defaultTitle=""
+        // Seed the proposed title from the source resource's name (GFR D4/A4);
+        // the field stays editable and required.
+        defaultTitle={resource.name}
         locale={locale}
         entityTypeOptions={allEntityTypes}
         onGenerateSubmit={handleResourceGenerateSubmit}
+        gatherContext={resourceGatherContext}
+        gatherLoading={resourceGatherLoading}
+        gatherError={resourceGatherError}
+        onGather={(options) => stateUnit?.gather.gatherResource(rUri, options)}
         translations={{
-          gatherTitle: tg('gatherTitle'),
-          reviewTitle: tg('reviewTitle'),
-          configureTitle: tg('configureTitle'),
-          next: tg('next'),
-          back: tg('back'),
-          cancel: tg('cancel'),
+          title: tg('title'),
           gatherIntro: tg('gatherIntro'),
           includeContent: tg('includeContent'),
           includeSummary: tg('includeSummary'),
           gatherDepth: tg('gatherDepth'),
           gatherMaxResources: tg('gatherMaxResources'),
           gatherButton: tg('gatherButton'),
-          excludeLabel: tg('excludeLabel'),
+          editGather: tg('editGather'),
+          recallLabel: tg('recallLabel'),
           loadingContext: tg('loadingContext'),
           failedContext: tg('failedContext'),
           sourceContextLabel: tg('sourceContextLabel'),
           connectionsLabel: tg('connectionsLabel'),
           citedByLabel: tg('citedByLabel'),
+          graphPaneTitle: tg('graphPaneTitle'),
+          graphEmpty: tg('graphEmpty'),
+          resourceLinkLabel: tg('resourceLinkLabel'),
+          corpusPaneTitle: tg('corpusPaneTitle'),
+          corpusEmpty: tg('corpusEmpty'),
+          excludedReceipt: tg('excludedReceipt'),
+          machineRead: tg('machineRead'),
+          score: tg('score'),
           resourceTitle: tg('resourceTitle'),
           resourceTitlePlaceholder: tg('resourceTitlePlaceholder'),
+          saveLocation: tg('saveLocation'),
           additionalInstructions: tg('additionalInstructions'),
           additionalInstructionsPlaceholder: tg('additionalInstructionsPlaceholder'),
           language: tg('language'),
@@ -748,7 +839,11 @@ export function ResourceViewerPage({
           creativityCreative: tg('creativityCreative'),
           maxLength: tg('maxLength'),
           maxLengthHelp: tg('maxLengthHelp'),
+          maxLengthCeiling: tg('maxLengthCeiling'),
           generate: tg('generate'),
+          discardDraftPrompt: tg('discardDraftPrompt'),
+          discardDraft: tg('discardDraft'),
+          keepEditing: tg('keepEditing'),
         }}
       />
     </div>

package/src/features/resource-viewer/hooks/__tests__/useResourceViewedReport.test.tsx

@@ -0,0 +1,63 @@
+/**
+ * The viewer's arrival report — GUIDED-TOUR P5 (D6).
+ *
+ * `browse:resource-viewed` is a REPORT, deliberately distinct from the
+ * imperative `browse:resource-open`: it fires when a resource has actually
+ * loaded on screen, however the user got there (followed cue, in-app link,
+ * back button, typed URL). The contract this pins: once per arrival — never
+ * on unrelated re-renders, never before the content is up, and again when
+ * the viewer moves to a different resource.
+ */
+import { renderHook } from '@testing-library/react';
+import { describe, it, expect, vi } from 'vitest';
+import type { ReactNode } from 'react';
+import { useResourceViewedReport } from '../useResourceViewedReport';
+import { createTestSemiontWrapper } from '../../../../test-utils';
+import { resourceId } from '@semiont/core';
+
+function makeWrapper() {
+  const { SemiontWrapper, client } = createTestSemiontWrapper();
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <SemiontWrapper>{children}</SemiontWrapper>
+  );
+  const viewed = vi.spyOn(client.browse, 'resourceViewed').mockImplementation(() => {});
+  return { wrapper, viewed };
+}
+
+const RID_A = resourceId('resaaa11223344556677889900aabbcc');
+const RID_B = resourceId('resbbb11223344556677889900aabbcc');
+
+describe('useResourceViewedReport', () => {
+  it('reports once when the resource finishes loading, not before and not again on re-render', () => {
+    const { wrapper, viewed } = makeWrapper();
+
+    const { rerender } = renderHook(
+      ({ rid, loaded }: { rid: ReturnType<typeof resourceId>; loaded: boolean }) => useResourceViewedReport(rid, loaded),
+      { wrapper, initialProps: { rid: RID_A, loaded: false } },
+    );
+    expect(viewed).not.toHaveBeenCalled();
+
+    rerender({ rid: RID_A, loaded: true });
+    expect(viewed).toHaveBeenCalledTimes(1);
+
+    rerender({ rid: RID_A, loaded: true });
+    rerender({ rid: RID_A, loaded: true });
+    expect(viewed).toHaveBeenCalledTimes(1);
+  });
+
+  it('reports again when the viewer arrives at a different resource', () => {
+    const { wrapper, viewed } = makeWrapper();
+
+    const { rerender } = renderHook(
+      ({ rid, loaded }: { rid: ReturnType<typeof resourceId>; loaded: boolean }) => useResourceViewedReport(rid, loaded),
+      { wrapper, initialProps: { rid: RID_A, loaded: true } },
+    );
+    expect(viewed).toHaveBeenCalledTimes(1);
+
+    rerender({ rid: RID_B, loaded: false });
+    expect(viewed).toHaveBeenCalledTimes(1);
+
+    rerender({ rid: RID_B, loaded: true });
+    expect(viewed).toHaveBeenCalledTimes(2);
+  });
+});

package/src/features/resource-viewer/hooks/useResourceViewedReport.ts

@@ -0,0 +1,33 @@
+import { useEffect, useRef } from 'react';
+import type { ResourceId } from '@semiont/core';
+import { useSemiont } from '../../../session/SemiontProvider';
+import { useObservable } from '../../../hooks/useObservable';
+
+/**
+ * Report a resource arrival on `browse:resource-viewed` — GUIDED-TOUR P5 (D6).
+ *
+ * Fires exactly once per arrival, when the resource has finished loading —
+ * however the user got here: a followed cue, an in-app link, the back button,
+ * a typed URL. That "any means" property is why this lives at the viewer's
+ * load-complete transition rather than on any navigation intent path. A
+ * re-render never re-reports; arriving at a different resource does.
+ *
+ * This is the REPORT half of the tour protocol. The imperative half is
+ * `browse:resource-open`; they must never share a channel (D6 — the driver
+ * would hear its own commands, and one viewer's click would steer another's
+ * page).
+ */
+export function useResourceViewedReport(rid: ResourceId, loaded: boolean): void {
+  const semiont = useSemiont();
+  const session = useObservable(semiont.activeSession$);
+  // Brand once at the boundary (BRAND-UPSTREAM): the caller already holds a
+  // ResourceId; this hook never re-brands.
+  const reported = useRef<ResourceId | null>(null);
+
+  useEffect(() => {
+    if (!loaded || !session) return;
+    if (reported.current === rid) return;
+    reported.current = rid;
+    session.client.browse.resourceViewed(rid);
+  }, [rid, loaded, session]);
+}

package/src/features/resource-viewer/state/__tests__/resource-viewer-page-state-unit.test.ts

@@ -56,7 +56,7 @@ function clientWithNamespaces(overrides: {
     },
     gather: { annotation: vi.fn(() => new Observable(() => {})) },
     match: { search: vi.fn(() => new Observable(() => {})) },
-    yield: { fromAnnotation: vi.fn(() => new Observable(() => {})) },
+    yield: { fromContext: vi.fn(() => new Observable(() => {})) },
     bind: { body: vi.fn().mockResolvedValue(undefined) },
   });
 }
@@ -357,7 +357,7 @@ describe('createResourceViewerPageStateUnit — list failure states', () => {
       mark: { annotation: vi.fn(), delete: vi.fn(), assist: vi.fn(() => new Observable(() => {})) },
       gather: { annotation: vi.fn(() => new Observable(() => {})) },
       match: { search: vi.fn(() => new Observable(() => {})) },
-      yield: { fromAnnotation: vi.fn(() => new Observable(() => {})) },
+      yield: { fromContext: vi.fn(() => new Observable(() => {})) },
       bind: { body: vi.fn().mockResolvedValue(undefined) },
     });
     const unit = createResourceViewerPageStateUnit(tc.session, RID, 'en', mockBrowse());

package/src/features/resource-viewer/state/resource-viewer-page-state-unit.ts

@@ -76,7 +76,7 @@ export function createResourceViewerPageStateUnit(
   const mark = createMarkStateUnit(client, resourceId);
   const gather = createGatherStateUnit(client, resourceId);
   const matchStateUnit = createMatchStateUnit(client, resourceId);
-  const yieldStateUnit = createYieldStateUnit(client, resourceId, locale);
+  const yieldStateUnit = createYieldStateUnit(client, locale);
 
   disposer.add(beckon);
   // `browse` (ShellStateUnit) is a *passed-in* dependency — owned by `useShellStateUnit`,

package/src/styles/core/buttons.css

@@ -487,8 +487,10 @@
   color: var(--semiont-color-white);
 }
 
+/* Hover lifts. The dark active state is primary-600, so hovering to 700 sank
+   it — the opposite of the sibling .semiont-panel-button:hover above. */
 [data-theme="dark"] .semiont-panel-button-active:hover {
-  background-color: var(--semiont-color-primary-700);
+  background-color: var(--semiont-color-primary-500);
 }
 
 /* ============================================