@semiont/react-ui 0.5.22 → 0.5.24

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

@@ -20,13 +20,14 @@ import { JsonLdPanel } from '@semiont/react-ui';
 import { Toolbar } from '@semiont/react-ui';
 import { useResourceLoadingAnnouncements } from '@semiont/react-ui';
 import { ResourceViewer } from '@semiont/react-ui';
+import type { BrowseMediaRenderers, AnnotateMediaRenderers } from '@semiont/react-ui';
 import { useObservable } from '@semiont/react-ui';
 import { useResourceContent } from '../../../hooks/useResourceContent';
 import { useMediaToken } from '../../../hooks/useMediaToken';
 import { useToast } from '../../../components/Toast';
 import { useOutcomeToasts } from '../../../hooks/useOutcomeToasts';
 import { useTheme } from '../../../contexts/ThemeContext';
-import { useLineNumbers } from '../../../hooks/useLineNumbers';
+import { useLineNumbers } from '../../../contexts/LineNumbersContext';
 import { useHoverDelay } from '../../../hooks/useHoverDelay';
 import { useEventSubscriptions } from '../../../contexts/useEventSubscription';
 import { useObservableExternalNavigation } from '../../../hooks/useObservableBrowse';
@@ -35,7 +36,7 @@ import { getSelectorType } from '../../../lib/media-shapes';
 import { useResourceAnnotations } from '../../../contexts/ResourceAnnotationsContext';
 import { useSemiont } from '../../../session/SemiontProvider';
 import { createResourceViewerPageStateUnit } from '../state/resource-viewer-page-state-unit';
-import { useStateUnit } from '../../../hooks/useStateUnit';
+import { useSessionStateUnit } from '../../../hooks/useSessionStateUnit';
 import { useShellStateUnit } from '../../../hooks/useShellStateUnit';
 import { useTranslations } from '../../../contexts/TranslationContext';
 import { ReferenceWizardModal } from '../../../components/modals/ReferenceWizardModal';
@@ -92,6 +93,14 @@ export interface ResourceViewerPageProps {
    * Name of the active knowledge base (for display in panels)
    */
   knowledgeBaseName?: string | undefined;
+
+  /**
+   * Media-renderer overrides, forwarded to `ResourceViewer`. Present at this
+   * tier too so a host embedding the whole page — not just the viewer — can
+   * still swap a renderer. See .plans/ANNOTATE-RENDERER-REGISTRY.md (D5)
+   */
+  browseRenderers?: BrowseMediaRenderers;
+  annotateRenderers?: AnnotateMediaRenderers;
 }
 
 /**
@@ -107,8 +116,6 @@ export interface ResourceViewerPageProps {
  * @subscribes yield:clone - Clone the current resource
  * @subscribes beckon:sparkle - Trigger sparkle animation
  * @subscribes mark:added - Annotation was created (sparkle)
- * @subscribes settings:theme-changed - UI theme changed
- * @subscribes settings:line-numbers-toggled - Line numbers display toggled
  * @subscribes browse:reference-navigate - Navigate to a referenced document
  * @subscribes browse:entity-type-clicked - Navigate filtered by entity type
  *
@@ -126,6 +133,8 @@ export function ResourceViewerPage({
   refetchDocument,
   streamStatus,
   knowledgeBaseName,
+  browseRenderers,
+  annotateRenderers,
 }: ResourceViewerPageProps) {
   // Translations
   const tw = useTranslations('ReferenceWizard');
@@ -148,8 +157,8 @@ export function ResourceViewerPage({
 
   // UI state hooks
   const { showError, showSuccess } = useToast();
-  const { theme, setTheme } = useTheme();
-  const { showLineNumbers, toggleLineNumbers } = useLineNumbers();
+  const { theme } = useTheme();
+  const { showLineNumbers } = useLineNumbers();
   const { hoverDelayMs } = useHoverDelay();
   const { triggerSparkleAnimation, clearNewAnnotationId, newAnnotationIds } = useResourceAnnotations();
 
@@ -185,27 +194,40 @@ export function ResourceViewerPage({
 
   // Composite state unit — owns all flow VMs, wizard state, annotations, entity types
   const browseStateUnit = useShellStateUnit();
-  const stateUnit = useStateUnit(() => createResourceViewerPageStateUnit(semiont!, rUri, locale, browseStateUnit));
-
-  const annotations = useObservable(stateUnit.annotations$) ?? [];
-  const groups = useObservable(stateUnit.annotationGroups$);
-  const allEntityTypes = useObservable(stateUnit.entityTypes$) ?? [];
-  const referencedByRaw = useObservable(stateUnit.referencedBy$);
-  const referencedBy = referencedByRaw ?? [];
-  const referencedByLoading = referencedByRaw === undefined;
-  const hoveredAnnotationId = useObservable(stateUnit.beckon.hoveredAnnotationId$) ?? null;
-  const pendingAnnotation = useObservable(stateUnit.mark.pendingAnnotation$) ?? null;
-  const assistingMotivation = useObservable(stateUnit.mark.assistingMotivation$) ?? null;
-  const progress = useObservable(stateUnit.mark.progress$) ?? null;
-  const activePanel = useObservable(stateUnit.browse.activePanel$) ?? null;
-  const scrollToAnnotationId = useObservable(stateUnit.browse.scrollToAnnotationId$) ?? null;
-  const panelInitialTab = useObservable(stateUnit.browse.panelInitialTab$) ?? null;
-  const onScrollCompleted = stateUnit.browse.onScrollCompleted;
-  const generationProgress = useObservable(stateUnit.yield.progress$) ?? null;
-  const gatherContext = useObservable(stateUnit.gather.context$) ?? null;
-  const gatherLoading = useObservable(stateUnit.gather.loading$) ?? false;
-  const gatherError = useObservable(stateUnit.gather.error$) ?? null;
-  const wizardState = useObservable(stateUnit.wizard$);
+  // Session-typed + session-keyed (SESSION-TYPED-FACTORIES.md): no `!`, no
+  // construction without a session, dispose-first rebuild on session swap.
+  const stateUnit = useSessionStateUnit(
+    session ?? undefined,
+    (s) => createResourceViewerPageStateUnit(s, rUri, locale, browseStateUnit),
+  );
+
+  const annotations = useObservable(stateUnit?.annotations.value$) ?? [];
+  const annotationsError = useObservable(stateUnit?.annotations.error$) ?? null;
+  const groups = useObservable(stateUnit?.annotationGroups$);
+  const allEntityTypes = useObservable(stateUnit?.entityTypes.value$) ?? [];
+  const entityTypesError = useObservable(stateUnit?.entityTypes.error$) ?? null;
+  // Three states, not two: a terminally failed list has no value EITHER, so
+  // deriving "loading" from `undefined` leaves a dead request spinning for
+  // ever. See .plans/PANEL-FAILURE-STATES.md
+  const referencedBy = useObservable(stateUnit?.referencedBy.value$) ?? [];
+  const referencedByLoading = useObservable(stateUnit?.referencedBy.loading$) ?? true;
+  const referencedByError = useObservable(stateUnit?.referencedBy.error$) ?? null;
+  const events = useObservable(stateUnit?.events.value$) ?? [];
+  const eventsLoading = useObservable(stateUnit?.events.loading$) ?? true;
+  const eventsError = useObservable(stateUnit?.events.error$) ?? null;
+  const hoveredAnnotationId = useObservable(stateUnit?.beckon.hoveredAnnotationId$) ?? null;
+  const pendingAnnotation = useObservable(stateUnit?.mark.pendingAnnotation$) ?? null;
+  const assistingMotivation = useObservable(stateUnit?.mark.assistingMotivation$) ?? null;
+  const progress = useObservable(stateUnit?.mark.progress$) ?? null;
+  const activePanel = useObservable(stateUnit?.browse.activePanel$) ?? null;
+  const scrollToAnnotationId = useObservable(stateUnit?.browse.scrollToAnnotationId$) ?? null;
+  const panelInitialTab = useObservable(stateUnit?.browse.panelInitialTab$) ?? null;
+  const onScrollCompleted = stateUnit?.browse.onScrollCompleted;
+  const generationProgress = useObservable(stateUnit?.yield.progress$) ?? null;
+  const gatherContext = useObservable(stateUnit?.gather.context$) ?? null;
+  const gatherLoading = useObservable(stateUnit?.gather.loading$) ?? false;
+  const gatherError = useObservable(stateUnit?.gather.error$) ?? null;
+  const wizardState = useObservable(stateUnit?.wizard$);
   const wizardOpen = wizardState?.open ?? false;
   const wizardAnnotationId = wizardState?.annotationId ?? null;
   const wizardResourceId = wizardState?.resourceId ?? null;
@@ -214,12 +236,12 @@ export function ResourceViewerPage({
   const [generateOpen, setGenerateOpen] = useState(false);
 
   const handleWizardClose = useCallback(() => {
-    stateUnit.closeWizard();
+    stateUnit?.closeWizard();
   }, [stateUnit]);
 
   const handleWizardGenerateSubmit = useCallback((referenceId: string, config: GenerationConfig) => {
     clearNewAnnotationId(annotationId(referenceId));
-    stateUnit.yield.generate(referenceId, {
+    stateUnit?.yield.generate(referenceId, {
       title: config.title,
       storageUri: config.storagePath,
       prompt: config.prompt,
@@ -239,7 +261,7 @@ export function ResourceViewerPage({
   // 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.
   const handleResourceGenerateSubmit = useCallback((_resourceId: string, config: GenerationConfig) => {
-    stateUnit.yield.generateFromResource({
+    stateUnit?.yield.generateFromResource({
       title: config.title,
       storageUri: config.storagePath,
       ...(config.prompt ? { prompt: config.prompt } : {}),
@@ -286,14 +308,15 @@ export function ResourceViewerPage({
     });
   }, [browser]);
 
-  // Add resource to open tabs when it loads
+  // 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
+  // state owned by the browser — a global last-viewed id sends that redirect
+  // into the previously active KB's resource after a switch.
   useEffect(() => {
     if (resource && rUri) {
       const mediaType = getPrimaryMediaType(resource);
       browser.addOpenResource(rUri, resource.name, mediaType || undefined, resource.storageUri);
-      if (typeof localStorage !== 'undefined') {
-        localStorage.setItem('lastViewedDocumentId', rUri);
-      }
+      browser.setLastViewedResource(rUri);
     }
   }, [resource, rUri, browser]);
 
@@ -355,8 +378,6 @@ export function ResourceViewerPage({
     triggerSparkleAnimation(stored.payload.annotation.id);
   }, [triggerSparkleAnimation]);
 
-  const handleSettingsThemeChanged = useCallback(({ theme }: { theme: any }) => setTheme(theme), [setTheme]);
-
   const handleReferenceNavigate = useCallback(({ resourceId }: { resourceId: string }) => {
     if (routes.resourceDetail) {
       const path = routes.resourceDetail(resourceId);
@@ -386,8 +407,6 @@ export function ResourceViewerPage({
     'yield:clone': handleResourceClone,
     'beckon:sparkle': handleAnnotationSparkle,
     'mark:added': handleAnnotationAdded,
-    'settings:theme-changed': handleSettingsThemeChanged,
-    'settings:line-numbers-toggled': toggleLineNumbers,
     'browse:reference-navigate': handleReferenceNavigate,
     'browse:entity-type-clicked': handleEntityTypeClicked,
   });
@@ -503,6 +522,8 @@ export function ResourceViewerPage({
                   showLineNumbers={showLineNumbers}
                   hoverDelayMs={hoverDelayMs}
                   hoveredAnnotationId={hoveredAnnotationId}
+                  {...(browseRenderers && { browseRenderers })}
+                  {...(annotateRenderers && { annotateRenderers })}
                 />
               )}
             </ErrorBoundary>
@@ -515,7 +536,6 @@ export function ResourceViewerPage({
           <ToolbarPanels
             activePanel={activePanel}
             theme={theme}
-            showLineNumbers={showLineNumbers}
             width={
               activePanel === 'jsonld' ? 'w-[600px]' :
               activePanel === 'annotations' ? 'w-[400px]' :
@@ -543,9 +563,14 @@ export function ResourceViewerPage({
                 progress={progress}
                 pendingAnnotation={pendingAnnotation}
                 allEntityTypes={allEntityTypes}
+                annotationsError={annotationsError}
+                onRetryAnnotations={stateUnit?.annotations.retry}
+                entityTypesError={entityTypesError}
                 generatingReferenceId={generationProgress?.annotationId ?? null}
                 referencedBy={referencedBy}
                 referencedByLoading={referencedByLoading}
+                referencedByError={referencedByError}
+                onRetryReferencedBy={stateUnit?.referencedBy.retry}
                 resourceId={rUri}
                 locale={locale}
                 sourceLanguage={getLanguage(resource)}
@@ -562,7 +587,11 @@ export function ResourceViewerPage({
             {/* History Panel */}
             {activePanel === 'history' && (
               <AnnotationHistory
-                rUri={rUri}
+                events={events}
+                eventsLoading={eventsLoading}
+                eventsError={eventsError}
+                onRetryEvents={stateUnit?.events.retry}
+                annotations={annotations}
                 hoveredAnnotationId={hoveredAnnotationId}
                 onEventHover={handleEventHover}
                 onEventClick={handleEventClick}
@@ -676,6 +705,7 @@ export function ResourceViewerPage({
         resourceId={rUri}
         defaultTitle=""
         locale={locale}
+        entityTypeOptions={allEntityTypes}
         onGenerateSubmit={handleResourceGenerateSubmit}
         translations={{
           gatherTitle: tg('gatherTitle'),

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

@@ -1,10 +1,12 @@
 import { describe, it, expect, vi } from 'vitest';
-import { BehaviorSubject, firstValueFrom } from 'rxjs';
+import { asStates } from '../../../../__tests__/test-client';
+import { sessionOf } from '../../../../__tests__/test-client';
+import { BehaviorSubject, Subject, firstValueFrom } from 'rxjs';
 import { filter } from 'rxjs/operators';
 import { resourceId as makeResourceId } from '@semiont/core';
 import type { SemiontClient } from '@semiont/sdk';
 import { createResourceLoaderStateUnit } from '../resource-loader-state-unit';
-import { assertStateUnitAxioms } from '@semiont/core/testing';
+import { assertStateUnitAxioms } from '@semiont/core/testing/axioms';
 
 const RID = makeResourceId('res-1');
 
@@ -13,15 +15,47 @@ function mockClient(resource$?: BehaviorSubject<unknown>): SemiontClient {
   const invalidate = vi.fn();
   return {
     browse: {
-      resource: () => subject.asObservable(),
+      resource: () => asStates(subject.asObservable()),
       invalidateResourceDetail: invalidate,
     },
   } as unknown as SemiontClient;
 }
 
+/**
+ * A client whose `browse.resource()` mirrors the cache's B15 contract: each
+ * `observe()` call hands back a FRESH observable (the failure marker is
+ * cleared and a new attempt chain starts), and a terminal failure arrives as
+ * an RxJS error notification on that key.
+ */
+function failingClient() {
+  const attempts: Array<Subject<unknown>> = [];
+  const invalidate = vi.fn();
+  const client = {
+    browse: {
+      resource: () => {
+        const s = new Subject<unknown>();
+        attempts.push(s);
+        return s.asObservable();
+      },
+      invalidateResourceDetail: invalidate,
+    },
+  } as unknown as SemiontClient;
+  return {
+    client,
+    invalidate,
+    /** Fail the most recent attempt the way B15 does. */
+    failLatest: (message: string) =>
+      attempts[attempts.length - 1]!.next({ status: 'failed', error: new Error(message) }),
+    /** Resolve the most recent attempt with a value. */
+    resolveLatest: (value: unknown) =>
+      attempts[attempts.length - 1]!.next({ status: 'ready', value }),
+    attemptCount: () => attempts.length,
+  };
+}
+
 describe('createResourceLoaderStateUnit', () => {
   it('exposes resource from browse namespace', async () => {
-    const stateUnit = createResourceLoaderStateUnit(mockClient(), RID);
+    const stateUnit = createResourceLoaderStateUnit(sessionOf(mockClient()), RID);
     const resource = await firstValueFrom(stateUnit.resource$.pipe(filter((r) => r !== undefined)));
     expect((resource as { name: string }).name).toBe('Test');
     stateUnit.dispose();
@@ -29,7 +63,7 @@ describe('createResourceLoaderStateUnit', () => {
 
   it('reports loading when resource is undefined', async () => {
     const subject = new BehaviorSubject<unknown>(undefined);
-    const stateUnit = createResourceLoaderStateUnit(mockClient(subject), RID);
+    const stateUnit = createResourceLoaderStateUnit(sessionOf(mockClient(subject)), RID);
     expect(await firstValueFrom(stateUnit.isLoading$)).toBe(true);
 
     subject.next({ '@id': 'res-1' });
@@ -39,18 +73,87 @@ describe('createResourceLoaderStateUnit', () => {
 
   it('invalidate calls browse.invalidateResourceDetail', () => {
     const client = mockClient();
-    const stateUnit = createResourceLoaderStateUnit(client, RID);
+    const stateUnit = createResourceLoaderStateUnit(sessionOf(client), RID);
     stateUnit.invalidate();
     expect(client.browse.invalidateResourceDetail).toHaveBeenCalledWith(RID);
     stateUnit.dispose();
   });
 });
 
+describe('createResourceLoaderStateUnit — terminal failure (B15)', () => {
+  // "Loading" cannot be defined as "no value yet": a key that fails with
+  // nothing cached has no value EITHER, so a two-state model reports a dead
+  // request as an eternal spinner and drops the reason on the floor. The
+  // failure must be a state of its own.
+  // See .plans/bugs/resource-page-frozen-on-disposed-client-after-kb-switch.md (D4)
+
+  it('surfaces a terminal failure on error$ instead of leaving it undelivered', async () => {
+    const h = failingClient();
+    const stateUnit = createResourceLoaderStateUnit(sessionOf(h.client), RID);
+    const seen: Array<Error | null> = [];
+    stateUnit.error$.subscribe((e) => seen.push(e));
+
+    expect(seen).toEqual([null]);
+    h.failLatest('Resource not found');
+
+    expect(seen.length).toBe(2);
+    expect(seen[1]?.message).toBe('Resource not found');
+    stateUnit.dispose();
+  });
+
+  it('stops reporting loading once the request has terminally failed', async () => {
+    const h = failingClient();
+    const stateUnit = createResourceLoaderStateUnit(sessionOf(h.client), RID);
+    const loading: boolean[] = [];
+    stateUnit.isLoading$.subscribe((l) => loading.push(l));
+
+    expect(loading[loading.length - 1]).toBe(true);
+    h.failLatest('Resource not found');
+
+    // The defect: without a failure state this stays true forever, and the
+    // page sits on "Loading resource..." with no way out.
+    expect(loading[loading.length - 1]).toBe(false);
+    stateUnit.dispose();
+  });
+
+  it('an error notification does not tear the unit down — invalidate starts a fresh attempt that can succeed', async () => {
+    const h = failingClient();
+    const stateUnit = createResourceLoaderStateUnit(sessionOf(h.client), RID);
+    h.failLatest('Resource not found');
+    expect(await firstValueFrom(stateUnit.error$)).not.toBeNull();
+
+    stateUnit.invalidate();
+    expect(h.invalidate).toHaveBeenCalledWith(RID);
+    // B15: a fresh observe() clears the marker and restarts the chain, so the
+    // unit must be listening to a NEW attempt, not the errored one.
+    expect(h.attemptCount()).toBeGreaterThan(1);
+    expect(await firstValueFrom(stateUnit.error$)).toBeNull();
+
+    h.resolveLatest({ '@id': 'res-1', name: 'Recovered' });
+    const resource = await firstValueFrom(stateUnit.resource$.pipe(filter((r) => r !== undefined)));
+    expect((resource as { name: string }).name).toBe('Recovered');
+    expect(await firstValueFrom(stateUnit.isLoading$)).toBe(false);
+    stateUnit.dispose();
+  });
+
+  it('a value arriving after a failure clears the error', async () => {
+    const h = failingClient();
+    const stateUnit = createResourceLoaderStateUnit(sessionOf(h.client), RID);
+    h.failLatest('transient');
+    stateUnit.invalidate();
+    h.resolveLatest({ '@id': 'res-1', name: 'Test' });
+
+    expect(await firstValueFrom(stateUnit.error$)).toBeNull();
+    stateUnit.dispose();
+  });
+});
+
 describe('ResourceLoaderStateUnit — StateUnit axioms', () => {
   it('satisfies the StateUnit axioms', () => {
-    // No owned surfaces: resource$/isLoading$ are derived from client.browse; dispose is a no-op.
+    // Owns resource$/error$ and a live subscription to client.browse, so
+    // dispose completes them and detaches; invalidate is inert afterwards.
     assertStateUnitAxioms({
-      setup: () => createResourceLoaderStateUnit(mockClient(), RID),
+      setup: () => createResourceLoaderStateUnit(sessionOf(mockClient()), RID),
       invocations: (u) => [() => u.invalidate()],
     });
   });