@semiont/react-ui 0.5.21 → 0.5.23

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

@@ -1,5 +1,7 @@
 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';
@@ -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()],
     });
   });

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

@@ -1,11 +1,12 @@
 import { describe, it, expect, vi, afterEach } from 'vitest';
+import { asStates } from '../../../../__tests__/test-client';
 import { BehaviorSubject, Observable, firstValueFrom } from 'rxjs';
 import { filter } from 'rxjs/operators';
 import { annotationId, resourceId as makeResourceId } from '@semiont/core';
 import type { ShellStateUnit } from '../../../../state/shell-state-unit';
-import { createResourceViewerPageStateUnit } from '../resource-viewer-page-state-unit';
+import { createResourceViewerPageStateUnit, type ResourceViewerPageStateUnit } from '../resource-viewer-page-state-unit';
 import { assertStateUnitAxioms, disposeProbe } from '@semiont/core/testing';
-import { makeTestClient, type TestClient } from '../../../../__tests__/test-client';
+import { makeTestSession, type TestSession } from '../../../../__tests__/test-client';
 
 const RID = makeResourceId('res-1');
 
@@ -28,18 +29,18 @@ function clientWithNamespaces(overrides: {
   referencedBy$?: BehaviorSubject<unknown[] | undefined>;
   resourceRepresentation?: ReturnType<typeof vi.fn>;
   mediaToken?: ReturnType<typeof vi.fn>;
-} = {}): TestClient {
+} = {}): TestSession {
   const annotations$ = overrides.annotations$ ?? new BehaviorSubject<unknown[] | undefined>([]);
   const entityTypes$ = overrides.entityTypes$ ?? new BehaviorSubject<string[] | undefined>(['Person']);
   const events$ = overrides.events$ ?? new BehaviorSubject<unknown[] | undefined>([]);
   const referencedBy$ = overrides.referencedBy$ ?? new BehaviorSubject<unknown[] | undefined>([]);
 
-  return makeTestClient({
+  return makeTestSession({
     browse: {
-      annotations: () => annotations$.asObservable(),
-      entityTypes: () => entityTypes$.asObservable(),
-      events: () => events$.asObservable(),
-      referencedBy: () => referencedBy$.asObservable(),
+      annotations: () => asStates(annotations$.asObservable()),
+      entityTypes: () => asStates(entityTypes$.asObservable()),
+      events: () => asStates(events$.asObservable()),
+      referencedBy: () => asStates(referencedBy$.asObservable()),
       resourceRepresentation: overrides.resourceRepresentation ?? vi.fn().mockResolvedValue({
         data: new TextEncoder().encode('hello').buffer,
         contentType: 'text/plain',
@@ -61,13 +62,13 @@ function clientWithNamespaces(overrides: {
 }
 
 describe('createResourceViewerPageStateUnit', () => {
-  let tc: TestClient;
+  let tc: TestSession;
 
   afterEach(() => { tc?.bus.destroy(); });
 
   it('exposes flow VMs', () => {
     tc = clientWithNamespaces();
-    const stateUnit = createResourceViewerPageStateUnit(tc.client, RID, 'en', mockBrowse());
+    const stateUnit = createResourceViewerPageStateUnit(tc.session, RID, 'en', mockBrowse());
 
     expect(stateUnit.beckon).toBeDefined();
     expect(stateUnit.mark).toBeDefined();
@@ -83,9 +84,9 @@ describe('createResourceViewerPageStateUnit', () => {
       { id: 'a1', motivation: 'highlighting' },
     ]);
     tc = clientWithNamespaces({ annotations$ });
-    const stateUnit = createResourceViewerPageStateUnit(tc.client, RID, 'en', mockBrowse());
+    const stateUnit = createResourceViewerPageStateUnit(tc.session, RID, 'en', mockBrowse());
 
-    const anns = await firstValueFrom(stateUnit.annotations$);
+    const anns = await firstValueFrom(stateUnit.annotations.value$);
     expect(anns).toHaveLength(1);
 
     stateUnit.dispose();
@@ -97,7 +98,7 @@ describe('createResourceViewerPageStateUnit', () => {
       { id: 'a2', motivation: 'commenting', body: [{ type: 'TextualBody', value: 'note' }], target: { selector: { type: 'TextQuoteSelector', exact: 'y' } } },
     ]);
     tc = clientWithNamespaces({ annotations$ });
-    const stateUnit = createResourceViewerPageStateUnit(tc.client, RID, 'en', mockBrowse());
+    const stateUnit = createResourceViewerPageStateUnit(tc.session, RID, 'en', mockBrowse());
 
     const groups = await firstValueFrom(stateUnit.annotationGroups$);
     expect(groups.highlights.length + groups.comments.length).toBeGreaterThanOrEqual(1);
@@ -107,9 +108,9 @@ describe('createResourceViewerPageStateUnit', () => {
 
   it('exposes entity types', async () => {
     tc = clientWithNamespaces();
-    const stateUnit = createResourceViewerPageStateUnit(tc.client, RID, 'en', mockBrowse());
+    const stateUnit = createResourceViewerPageStateUnit(tc.session, RID, 'en', mockBrowse());
 
-    const types = await firstValueFrom(stateUnit.entityTypes$);
+    const types = await firstValueFrom(stateUnit.entityTypes.value$);
     expect(types).toEqual(['Person']);
 
     stateUnit.dispose();
@@ -118,9 +119,9 @@ describe('createResourceViewerPageStateUnit', () => {
   it('exposes events from browse namespace', async () => {
     const events$ = new BehaviorSubject<unknown[] | undefined>([{ id: 'e1', type: 'mark:added' }]);
     tc = clientWithNamespaces({ events$ });
-    const stateUnit = createResourceViewerPageStateUnit(tc.client, RID, 'en', mockBrowse());
+    const stateUnit = createResourceViewerPageStateUnit(tc.session, RID, 'en', mockBrowse());
 
-    const events = await firstValueFrom(stateUnit.events$);
+    const events = await firstValueFrom(stateUnit.events.value$);
     expect(events).toEqual([{ id: 'e1', type: 'mark:added' }]);
 
     stateUnit.dispose();
@@ -129,9 +130,9 @@ describe('createResourceViewerPageStateUnit', () => {
   it('exposes referencedBy from browse namespace', async () => {
     const referencedBy$ = new BehaviorSubject<unknown[] | undefined>([{ resourceId: 'r2' }]);
     tc = clientWithNamespaces({ referencedBy$ });
-    const stateUnit = createResourceViewerPageStateUnit(tc.client, RID, 'en', mockBrowse());
+    const stateUnit = createResourceViewerPageStateUnit(tc.session, RID, 'en', mockBrowse());
 
-    const refs = await firstValueFrom(stateUnit.referencedBy$);
+    const refs = await firstValueFrom(stateUnit.referencedBy.value$);
     expect(refs).toEqual([{ resourceId: 'r2' }]);
 
     stateUnit.dispose();
@@ -141,7 +142,7 @@ describe('createResourceViewerPageStateUnit', () => {
     const mediaToken = vi.fn().mockResolvedValue({ token: 'tok-456' });
     tc = clientWithNamespaces({ mediaToken });
     const stateUnit = createResourceViewerPageStateUnit(
-      tc.client, RID, 'en', mockBrowse(),
+      tc.session, RID, 'en', mockBrowse(),
       { mediaType: 'image/png' },
     );
 
@@ -159,7 +160,7 @@ describe('createResourceViewerPageStateUnit', () => {
     const resourceRepresentation = vi.fn();
     tc = clientWithNamespaces({ mediaToken, resourceRepresentation });
     const stateUnit = createResourceViewerPageStateUnit(
-      tc.client, RID, 'en', mockBrowse(),
+      tc.session, RID, 'en', mockBrowse(),
       { mediaType: 'application/zip' },
     );
 
@@ -178,7 +179,7 @@ describe('createResourceViewerPageStateUnit', () => {
     });
     tc = clientWithNamespaces({ mediaToken, resourceRepresentation });
     const stateUnit = createResourceViewerPageStateUnit(
-      tc.client, RID, 'en', mockBrowse(),
+      tc.session, RID, 'en', mockBrowse(),
       { mediaType: 'text/x-custom' },
     );
 
@@ -190,7 +191,7 @@ describe('createResourceViewerPageStateUnit', () => {
 
   it('wizard initializes closed', async () => {
     tc = clientWithNamespaces();
-    const stateUnit = createResourceViewerPageStateUnit(tc.client, RID, 'en', mockBrowse());
+    const stateUnit = createResourceViewerPageStateUnit(tc.session, RID, 'en', mockBrowse());
 
     const wizard = await firstValueFrom(stateUnit.wizard$);
     expect(wizard.open).toBe(false);
@@ -200,7 +201,7 @@ describe('createResourceViewerPageStateUnit', () => {
 
   it('bind:initiate opens wizard and fires gather:requested', async () => {
     tc = clientWithNamespaces();
-    const stateUnit = createResourceViewerPageStateUnit(tc.client, RID, 'en', mockBrowse());
+    const stateUnit = createResourceViewerPageStateUnit(tc.session, RID, 'en', mockBrowse());
     const gatherEvents: unknown[] = [];
     tc.bus.get('gather:requested').subscribe((e) => gatherEvents.push(e));
 
@@ -220,7 +221,7 @@ describe('createResourceViewerPageStateUnit', () => {
 
   it('closeWizard resets wizard state', async () => {
     tc = clientWithNamespaces();
-    const stateUnit = createResourceViewerPageStateUnit(tc.client, RID, 'en', mockBrowse());
+    const stateUnit = createResourceViewerPageStateUnit(tc.session, RID, 'en', mockBrowse());
 
     tc.bus.get('bind:initiate').next({
       annotationId: annotationId('ann-1'),
@@ -239,6 +240,145 @@ describe('createResourceViewerPageStateUnit', () => {
   });
 });
 
+describe('createResourceViewerPageStateUnit — list failure states', () => {
+  // A cache-backed list has three outcomes, not two. `browse.*()` delivers a
+  // terminal failure as an RxJS error (B15) once the B14 retry is exhausted
+  // with nothing stored — and a key that failed has no value either, so a
+  // (value | not-yet) model reports a dead request as an eternal spinner.
+  // Two panels do exactly that today: ReferencesPanel via
+  // `referencedByLoading = raw === undefined`, and AnnotationHistory via
+  // `loading = eventsData === undefined`.
+  // See .plans/PANEL-FAILURE-STATES.md
+
+  /**
+   * One case per cache-backed list. Each builds its OWN correctly-typed
+   * subject and returns the list off the unit, so the shared assertions below
+   * need no indexing by name and no cast.
+   */
+  /** The slice of `ListState<T>` these shared assertions read. */
+  interface ListProbe {
+    value$: Observable<unknown>;
+    loading$: Observable<boolean>;
+    error$: Observable<Error | null>;
+  }
+
+  const LIST_CASES: ReadonlyArray<{
+    name: string;
+    start: () => {
+      subject: { next: (s: never) => void };
+      tc: TestSession;
+      unit: ResourceViewerPageStateUnit;
+      list: ListProbe;
+    };
+  }> = [
+    {
+      name: 'annotations',
+      start: () => {
+        const subject = new BehaviorSubject<unknown[] | undefined>(undefined);
+        const tc = clientWithNamespaces({ annotations$: subject });
+        const unit = createResourceViewerPageStateUnit(tc.session, RID, 'en', mockBrowse());
+        return { subject, tc, unit, list: unit.annotations };
+      },
+    },
+    {
+      name: 'entityTypes',
+      start: () => {
+        const subject = new BehaviorSubject<string[] | undefined>(undefined);
+        const tc = clientWithNamespaces({ entityTypes$: subject });
+        const unit = createResourceViewerPageStateUnit(tc.session, RID, 'en', mockBrowse());
+        return { subject, tc, unit, list: unit.entityTypes };
+      },
+    },
+    {
+      name: 'events',
+      start: () => {
+        const subject = new BehaviorSubject<unknown[] | undefined>(undefined);
+        const tc = clientWithNamespaces({ events$: subject });
+        const unit = createResourceViewerPageStateUnit(tc.session, RID, 'en', mockBrowse());
+        return { subject, tc, unit, list: unit.events };
+      },
+    },
+    {
+      name: 'referencedBy',
+      start: () => {
+        const subject = new BehaviorSubject<unknown[] | undefined>(undefined);
+        const tc = clientWithNamespaces({ referencedBy$: subject });
+        const unit = createResourceViewerPageStateUnit(tc.session, RID, 'en', mockBrowse());
+        return { subject, tc, unit, list: unit.referencedBy };
+      },
+    },
+  ];
+
+  it.each(LIST_CASES)('$name: stops reporting loading and surfaces the reason on terminal failure', async ({ start }) => {
+    const { subject, tc, unit, list } = start();
+
+    expect(await firstValueFrom(list.loading$)).toBe(true);
+    expect(await firstValueFrom(list.error$)).toBeNull();
+
+    subject.next({ status: 'failed', error: new Error('Resource not found') } as never);
+
+    expect(await firstValueFrom(list.loading$)).toBe(false);
+    expect((await firstValueFrom(list.error$))?.message).toBe('Resource not found');
+
+    unit.dispose();
+    tc.bus.destroy();
+  });
+
+  it.each(LIST_CASES)('$name: keeps an empty value alongside the failure, so callers still render a list', async ({ start }) => {
+    const { subject, tc, unit, list } = start();
+
+    subject.next({ status: 'failed', error: new Error('boom') } as never);
+
+    expect(await firstValueFrom(list.value$)).toEqual([]);
+    unit.dispose();
+    tc.bus.destroy();
+  });
+
+  it('retry() clears the error, re-enters loading, and re-subscribes so a fresh attempt can succeed', async () => {
+    // D1/D3: failure is an EMISSION and recovery is a fresh SUBSCRIPTION —
+    // retry() re-attaches, and the new subscription's chain delivers.
+    const attempts: Array<BehaviorSubject<unknown>> = [];
+    const tc = makeTestSession({
+      browse: {
+        annotations: () => new BehaviorSubject<unknown>({ status: 'ready', value: [] }).asObservable(),
+        entityTypes: () => new BehaviorSubject<unknown>({ status: 'ready', value: [] }).asObservable(),
+        events: () => new BehaviorSubject<unknown>({ status: 'ready', value: [] }).asObservable(),
+        referencedBy: () => {
+          const s = new BehaviorSubject<unknown>({ status: 'pending' });
+          attempts.push(s);
+          return s.asObservable();
+        },
+        resourceRepresentation: vi.fn().mockResolvedValue({
+          data: new TextEncoder().encode('hello').buffer,
+          contentType: 'text/plain',
+        }),
+      },
+      auth: { mediaToken: vi.fn().mockResolvedValue({ token: 'tok' }) },
+      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(() => {})) },
+      bind: { body: vi.fn().mockResolvedValue(undefined) },
+    });
+    const unit = createResourceViewerPageStateUnit(tc.session, RID, 'en', mockBrowse());
+
+    attempts[0]!.next({ status: 'failed', error: new Error('nope') });
+    expect(await firstValueFrom(unit.referencedBy.error$)).not.toBeNull();
+
+    unit.referencedBy.retry();
+    expect(attempts.length).toBeGreaterThan(1);
+    expect(await firstValueFrom(unit.referencedBy.error$)).toBeNull();
+    expect(await firstValueFrom(unit.referencedBy.loading$)).toBe(true);
+
+    attempts[attempts.length - 1]!.next({ status: 'ready', value: [{ id: 'ref-1' }] });
+    expect(await firstValueFrom(unit.referencedBy.loading$)).toBe(false);
+    expect(await firstValueFrom(unit.referencedBy.value$)).toHaveLength(1);
+
+    unit.dispose();
+    tc.bus.destroy();
+  });
+});
+
 describe('ResourceViewerPageStateUnit — StateUnit axioms', () => {
   it('satisfies the StateUnit axioms (A7-passed: browse survives; A7-owned: children disposed)', () => {
     const RID = makeResourceId('res-ax');
@@ -247,7 +387,7 @@ describe('ResourceViewerPageStateUnit — StateUnit axioms', () => {
         const browse = disposeProbe();
         const tc = clientWithNamespaces();
         return {
-          unit: createResourceViewerPageStateUnit(tc.client, RID, 'en', browse as unknown as ShellStateUnit),
+          unit: createResourceViewerPageStateUnit(tc.session, RID, 'en', browse as unknown as ShellStateUnit),
           passedIn: [browse],
           teardown: () => tc.bus.destroy(),
         };

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

@@ -1,26 +1,91 @@
-import { type Observable, map } from 'rxjs';
+import { readyValue } from '@semiont/sdk';
+import {
+  BehaviorSubject,
+  combineLatest,
+  distinctUntilChanged,
+  map,
+  type Observable,
+  type Subscription,
+} from 'rxjs';
 import type { ResourceDescriptor, ResourceId } from '@semiont/core';
 import type { StateUnit } from '@semiont/core';
-import type { SemiontClient } from '@semiont/sdk';
+import type { SemiontSession } from '@semiont/sdk';
 
 export interface ResourceLoaderStateUnit extends StateUnit {
   resource$: Observable<ResourceDescriptor | undefined>;
   isLoading$: Observable<boolean>;
+  /** Terminal load failure (B15), or null. Cleared by any value or `invalidate()`. */
+  error$: Observable<Error | null>;
   invalidate(): void;
 }
 
+/**
+ * Load one resource, in three states: loading, loaded, failed.
+ *
+ * The third state is not optional. `browse.resource()` delivers a terminal
+ * failure as an RxJS *error* notification (B15) when the B14 retry is
+ * exhausted with nothing cached — and a key that failed has no value either,
+ * so a (value | no value) model reports a dead request as an eternal spinner
+ * and drops the reason entirely. This unit catches the notification here so
+ * that (a) consumers can render the failure and retry it, and (b) it never
+ * escapes to RxJS as an unhandled rethrow.
+ * See .plans/bugs/resource-page-frozen-on-disposed-client-after-kb-switch.md (D4)
+ */
 export function createResourceLoaderStateUnit(
-  client: SemiontClient,
+  session: SemiontSession,
   resourceId: ResourceId,
 ): ResourceLoaderStateUnit {
-  const raw$ = client.browse.resource(resourceId);
-  const resource$ = raw$;
-  const isLoading$: Observable<boolean> = raw$.pipe(map((r) => r === undefined));
+  const { client } = session;
+  const resource$ = new BehaviorSubject<ResourceDescriptor | undefined>(undefined);
+  const error$ = new BehaviorSubject<Error | null>(null);
+
+  let subscription: Subscription | null = null;
+  let disposed = false;
+
+  /**
+   * (Re)subscribe to this key. An errored observable is terminated, so
+   * recovery needs a fresh subscription — which is also what re-arms the
+   * cache: `observe()` clears the B15 failure marker and starts a new
+   * attempt chain for a key it is asked about again.
+   */
+  const attach = (): void => {
+    if (disposed) return;
+    subscription?.unsubscribe();
+    subscription = client.browse.resource(resourceId).subscribe((st) => {
+      if (st.status === 'failed') {
+        // D1: failure is an emission — the subscription stays alive.
+        error$.next(st.error);
+        return;
+      }
+      if (st.status === 'ready' && error$.getValue() !== null) error$.next(null);
+      resource$.next(readyValue(st));
+    });
+  };
+  attach();
+
+  const isLoading$ = combineLatest([resource$, error$]).pipe(
+    map(([resource, error]) => resource === undefined && error === null),
+    distinctUntilChanged(),
+  );
 
   return {
-    resource$,
+    // X1: owned subjects are published read-only.
+    resource$: resource$.asObservable(),
     isLoading$,
-    invalidate: () => client.browse.invalidateResourceDetail(resourceId),
-    dispose: () => {},
+    error$: error$.asObservable(),
+    invalidate: () => {
+      if (disposed) return;
+      error$.next(null);
+      client.browse.invalidateResourceDetail(resourceId);
+      attach();
+    },
+    dispose: () => {
+      if (disposed) return;
+      disposed = true;
+      subscription?.unsubscribe();
+      subscription = null;
+      resource$.complete();
+      error$.complete();
+    },
   };
 }

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

@@ -3,12 +3,13 @@ import type { ResourceId, components } from '@semiont/core';
 import { createDisposer } from '@semiont/sdk';
 import type { StateUnit } from '@semiont/core';
 import type { ShellStateUnit } from '../../../state/shell-state-unit';
+import { trackList, type ListState } from '../../../state/list-state';
 import { createBeckonStateUnit, type BeckonStateUnit } from '@semiont/sdk';
 import { createMarkStateUnit, type MarkStateUnit } from '@semiont/sdk';
 import { createGatherStateUnit, type GatherStateUnit } from '@semiont/sdk';
 import { createMatchStateUnit } from '@semiont/sdk';
 import { createYieldStateUnit, type YieldStateUnit } from '@semiont/sdk';
-import type { SemiontClient } from '@semiont/sdk';
+import type { SemiontSession } from '@semiont/sdk';
 import { decodeWithCharset, textExtractionOf } from '@semiont/core';
 import { groupAnnotations } from '../../../lib/annotation-groups';
 import type { ReferencedByEntry } from '@semiont/sdk';
@@ -43,11 +44,12 @@ export interface ResourceViewerPageStateUnit extends StateUnit {
   gather: GatherStateUnit;
   yield: YieldStateUnit;
 
-  annotations$: Observable<Annotation[]>;
+  annotations: ListState<Annotation[]>;
+  entityTypes: ListState<string[]>;
+  events: ListState<StoredEventResponse[]>;
+  referencedBy: ListState<ReferencedByEntry[]>;
+  /** Derived from `annotations.value$`; failure/loading live on `annotations`. */
   annotationGroups$: Observable<AnnotationGroups>;
-  entityTypes$: Observable<string[]>;
-  events$: Observable<StoredEventResponse[]>;
-  referencedBy$: Observable<ReferencedByEntry[]>;
   content$: Observable<string>;
   contentLoading$: Observable<boolean>;
   mediaToken$: Observable<string | null>;
@@ -56,13 +58,18 @@ export interface ResourceViewerPageStateUnit extends StateUnit {
   closeWizard(): void;
 }
 
+// Session-typed (SESSION-TYPED-FACTORIES.md D1): the parameter is the
+// lifetime this unit must not outlive. The internal flow units below keep
+// the narrower client — their lifetime is THIS unit's disposer, which is now
+// session-bound; that is layering, not a loophole.
 export function createResourceViewerPageStateUnit(
-  client: SemiontClient,
+  session: SemiontSession,
   resourceId: ResourceId,
   locale: string,
   browse: ShellStateUnit,
   options?: { mediaType?: string },
 ): ResourceViewerPageStateUnit {
+  const { client } = session;
   const disposer = createDisposer();
 
   const beckon = createBeckonStateUnit(client);
@@ -81,23 +88,17 @@ export function createResourceViewerPageStateUnit(
   disposer.add(matchStateUnit);
   disposer.add(yieldStateUnit);
 
-  const annotations$: Observable<Annotation[]> = client.browse.annotations(resourceId).pipe(
-    map((a) => a ?? []),
-  );
+  const annotations = trackList<Annotation[]>(() => client.browse.annotations(resourceId), []);
+  const entityTypes = trackList<string[]>(() => client.browse.entityTypes(), []);
+  const events = trackList<StoredEventResponse[]>(() => client.browse.events(resourceId), []);
+  const referencedBy = trackList<ReferencedByEntry[]>(() => client.browse.referencedBy(resourceId), []);
+  disposer.add(annotations.dispose);
+  disposer.add(entityTypes.dispose);
+  disposer.add(events.dispose);
+  disposer.add(referencedBy.dispose);
 
-  const annotationGroups$: Observable<AnnotationGroups> = annotations$.pipe(map(groupAnnotations));
-
-  const entityTypes$: Observable<string[]> = client.browse.entityTypes().pipe(
-    map((e) => e ?? []),
-  );
-
-  const events$: Observable<StoredEventResponse[]> = client.browse.events(resourceId).pipe(
-    map((e) => e ?? []),
-  );
-
-  const referencedBy$: Observable<ReferencedByEntry[]> = client.browse.referencedBy(resourceId).pipe(
-    map((r) => r ?? []),
-  );
+  const annotationGroups$: Observable<AnnotationGroups> =
+    annotations.state.value$.pipe(map(groupAnnotations));
 
   const content$ = new BehaviorSubject<string>('');
   const contentLoading$ = new BehaviorSubject<boolean>(false);
@@ -157,11 +158,11 @@ export function createResourceViewerPageStateUnit(
     mark,
     gather,
     yield: yieldStateUnit,
-    annotations$,
+    annotations: annotations.state,
+    entityTypes: entityTypes.state,
+    events: events.state,
+    referencedBy: referencedBy.state,
     annotationGroups$,
-    entityTypes$,
-    events$,
-    referencedBy$,
     content$: content$.asObservable(),
     contentLoading$: contentLoading$.asObservable(),
     mediaToken$: mediaToken$.asObservable(),