@semiont/react-ui 0.5.21 → 0.5.23

package/src/features/admin-users/state/__tests__/admin-users-state-unit.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect, vi } from 'vitest';
+import { sessionOf } from '../../../../__tests__/test-client';
 import { firstValueFrom } from 'rxjs';
 import { filter } from 'rxjs/operators';
 import type { SemiontClient } from '@semiont/sdk';
@@ -28,7 +29,7 @@ describe('createAdminUsersStateUnit', () => {
   it('fetches users and stats on creation', async () => {
     const listUsers = vi.fn().mockResolvedValue({ users: [{ id: 'u1' }] });
     const getUserStats = vi.fn().mockResolvedValue({ stats: { total: 1 } });
-    const stateUnit = createAdminUsersStateUnit(mockClient({ listUsers, getUserStats }), mockBrowse());
+    const stateUnit = createAdminUsersStateUnit(sessionOf(mockClient({ listUsers, getUserStats })), mockBrowse());
 
     const users = await firstValueFrom(stateUnit.users$.pipe(filter((u) => u.length > 0)));
     expect(users).toEqual([{ id: 'u1' }]);
@@ -40,7 +41,7 @@ describe('createAdminUsersStateUnit', () => {
   });
 
   it('starts with loading true, resolves to false', async () => {
-    const stateUnit = createAdminUsersStateUnit(mockClient(), mockBrowse());
+    const stateUnit = createAdminUsersStateUnit(sessionOf(mockClient()), mockBrowse());
 
     await firstValueFrom(stateUnit.usersLoading$.pipe(filter((l) => !l)));
     await firstValueFrom(stateUnit.statsLoading$.pipe(filter((l) => !l)));
@@ -51,7 +52,7 @@ describe('createAdminUsersStateUnit', () => {
   it('sets loading false on fetch error', async () => {
     const listUsers = vi.fn().mockRejectedValue(new Error('fail'));
     const getUserStats = vi.fn().mockRejectedValue(new Error('fail'));
-    const stateUnit = createAdminUsersStateUnit(mockClient({ listUsers, getUserStats }), mockBrowse());
+    const stateUnit = createAdminUsersStateUnit(sessionOf(mockClient({ listUsers, getUserStats })), mockBrowse());
 
     await firstValueFrom(stateUnit.usersLoading$.pipe(filter((l) => !l)));
     await firstValueFrom(stateUnit.statsLoading$.pipe(filter((l) => !l)));
@@ -63,7 +64,7 @@ describe('createAdminUsersStateUnit', () => {
     const listUsers = vi.fn().mockResolvedValue({ users: [] });
     const getUserStats = vi.fn().mockResolvedValue({ stats: null });
     const updateUser = vi.fn().mockResolvedValue(undefined);
-    const stateUnit = createAdminUsersStateUnit(mockClient({ listUsers, getUserStats, updateUser }), mockBrowse());
+    const stateUnit = createAdminUsersStateUnit(sessionOf(mockClient({ listUsers, getUserStats, updateUser })), mockBrowse());
 
     await firstValueFrom(stateUnit.usersLoading$.pipe(filter((l) => !l)));
     listUsers.mockClear();
@@ -85,7 +86,7 @@ describe('AdminUsersStateUnit — StateUnit axioms', () => {
     assertStateUnitAxioms({
       setup: () => {
         const browse = disposeProbe();
-        return { unit: createAdminUsersStateUnit(mockClient(), browse as unknown as ShellStateUnit), passedIn: [browse] };
+        return { unit: createAdminUsersStateUnit(sessionOf(mockClient()), browse as unknown as ShellStateUnit), passedIn: [browse] };
       },
       surfaces: (u) => [u.users$, u.stats$, u.usersLoading$, u.statsLoading$],
     });

package/src/features/admin-users/state/admin-users-state-unit.ts

@@ -3,7 +3,7 @@ import { userDID } from '@semiont/core';
 import { createDisposer } from '@semiont/sdk';
 import type { StateUnit } from '@semiont/core';
 import type { ShellStateUnit } from '../../../state/shell-state-unit';
-import type { SemiontClient } from '@semiont/sdk';
+import type { SemiontSession } from '@semiont/sdk';
 
 export interface AdminUsersStateUnit extends StateUnit {
   browse: ShellStateUnit;
@@ -15,9 +15,10 @@ export interface AdminUsersStateUnit extends StateUnit {
 }
 
 export function createAdminUsersStateUnit(
-  client: SemiontClient,
+  session: SemiontSession,
   browse: ShellStateUnit,
 ): AdminUsersStateUnit {
+  const { client } = session;
   const disposer = createDisposer();
   // `browse` (ShellStateUnit) is a *passed-in* dependency owned by the caller
   // (`useShellStateUnit`), not this unit — do NOT add it to the disposer (it's the

package/src/features/auth-welcome/state/__tests__/welcome-state-unit.test.ts

@@ -1,26 +1,37 @@
-import { describe, it, expect, vi } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { firstValueFrom } from 'rxjs';
 import { filter } from 'rxjs/operators';
-import type { SemiontClient } from '@semiont/sdk';
+import type { SemiontSession } from '@semiont/sdk';
+import { AuthNamespace } from '@semiont/sdk';
+import { createTestSession, stubBackend } from '@semiont/sdk/testing';
 import { createWelcomeStateUnit } from '../welcome-state-unit';
 import { assertStateUnitAxioms } from '@semiont/core/testing';
 
-function mockClient(overrides: {
-  getMe?: ReturnType<typeof vi.fn>;
-  acceptTerms?: ReturnType<typeof vi.fn>;
-} = {}): SemiontClient {
-  return {
-    auth: {
-      me: overrides.getMe ?? vi.fn().mockResolvedValue({ termsAcceptedAt: undefined }),
-      acceptTerms: overrides.acceptTerms ?? vi.fn().mockResolvedValue(undefined),
-    },
-  } as unknown as SemiontClient;
+// Real session over the scriptable transport (SESSION-TYPED-FACTORIES pilot);
+// auth behavior scripted by prototype spies, the AuthShell precedent — the
+// previous `as unknown as SemiontClient` hand-mock was the M1 disease.
+let getMe: ReturnType<typeof vi.spyOn>;
+let acceptTermsSpy: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  getMe = vi.spyOn(AuthNamespace.prototype, 'me');
+  getMe.mockResolvedValue({ termsAcceptedAt: undefined } as never);
+  acceptTermsSpy = vi.spyOn(AuthNamespace.prototype, 'acceptTerms');
+  acceptTermsSpy.mockResolvedValue(undefined as never);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function makeSession(): SemiontSession {
+  return createTestSession({ backend: stubBackend() }).session;
 }
 
 describe('createWelcomeStateUnit', () => {
   it('fetches user data on creation', async () => {
-    const getMe = vi.fn().mockResolvedValue({ termsAcceptedAt: '2026-01-01' });
-    const stateUnit = createWelcomeStateUnit(mockClient({ getMe }));
+    getMe.mockResolvedValue({ termsAcceptedAt: '2026-01-01' } as never);
+    const stateUnit = createWelcomeStateUnit(makeSession());
 
     const data = await firstValueFrom(stateUnit.userData$.pipe(filter((d) => d !== null)));
     expect(data).toEqual({ termsAcceptedAt: '2026-01-01' });
@@ -29,8 +40,8 @@ describe('createWelcomeStateUnit', () => {
   });
 
   it('initializes with null userData and not processing', async () => {
-    const getMe = vi.fn().mockReturnValue(new Promise(() => {}));
-    const stateUnit = createWelcomeStateUnit(mockClient({ getMe }));
+    getMe.mockReturnValue(new Promise(() => {}) as never);
+    const stateUnit = createWelcomeStateUnit(makeSession());
 
     const data = await firstValueFrom(stateUnit.userData$);
     const processing = await firstValueFrom(stateUnit.isProcessing$);
@@ -41,14 +52,13 @@ describe('createWelcomeStateUnit', () => {
   });
 
   it('acceptTerms sets isProcessing and updates userData', async () => {
-    const acceptTerms = vi.fn().mockResolvedValue(undefined);
-    const stateUnit = createWelcomeStateUnit(mockClient({ acceptTerms }));
+    const stateUnit = createWelcomeStateUnit(makeSession());
 
     await firstValueFrom(stateUnit.userData$.pipe(filter((d) => d !== null)));
 
     await stateUnit.acceptTerms();
 
-    expect(acceptTerms).toHaveBeenCalledOnce();
+    expect(acceptTermsSpy).toHaveBeenCalledOnce();
 
     const data = await firstValueFrom(stateUnit.userData$);
     expect(data?.termsAcceptedAt).toBeDefined();
@@ -60,8 +70,8 @@ describe('createWelcomeStateUnit', () => {
   });
 
   it('acceptTerms resets isProcessing on error', async () => {
-    const acceptTerms = vi.fn().mockRejectedValue(new Error('fail'));
-    const stateUnit = createWelcomeStateUnit(mockClient({ acceptTerms }));
+    acceptTermsSpy.mockRejectedValue(new Error('fail') as never);
+    const stateUnit = createWelcomeStateUnit(makeSession());
 
     await firstValueFrom(stateUnit.userData$.pipe(filter((d) => d !== null)));
 
@@ -74,8 +84,8 @@ describe('createWelcomeStateUnit', () => {
   });
 
   it('handles getMe failure gracefully', async () => {
-    const getMe = vi.fn().mockRejectedValue(new Error('unauthorized'));
-    const stateUnit = createWelcomeStateUnit(mockClient({ getMe }));
+    getMe.mockRejectedValue(new Error('unauthorized') as never);
+    const stateUnit = createWelcomeStateUnit(makeSession());
 
     await vi.waitFor(() => expect(getMe).toHaveBeenCalled());
 
@@ -89,7 +99,7 @@ describe('createWelcomeStateUnit', () => {
 describe('WelcomeStateUnit — StateUnit axioms', () => {
   it('satisfies the StateUnit axioms', () => {
     assertStateUnitAxioms({
-      setup: () => createWelcomeStateUnit(mockClient()),
+      setup: () => createWelcomeStateUnit(makeSession()),
       surfaces: (u) => [u.userData$, u.isProcessing$],
       invocations: (u) => [() => u.acceptTerms()],
     });

package/src/features/auth-welcome/state/welcome-state-unit.ts

@@ -1,7 +1,7 @@
 import { BehaviorSubject, type Observable } from 'rxjs';
 import { createDisposer } from '@semiont/sdk';
 import type { StateUnit } from '@semiont/core';
-import type { SemiontClient } from '@semiont/sdk';
+import type { SemiontSession } from '@semiont/sdk';
 
 export interface WelcomeStateUnit extends StateUnit {
   userData$: Observable<{ termsAcceptedAt?: string } | null>;
@@ -9,9 +9,14 @@ export interface WelcomeStateUnit extends StateUnit {
   acceptTerms(): Promise<void>;
 }
 
+// Session-typed (SESSION-TYPED-FACTORIES.md D1): the parameter is the
+// lifetime this unit must not outlive. This page crashed in production when
+// the unit was constructed with `undefined` during session activation —
+// `useSessionStateUnit` + this signature make that unrepresentable.
 export function createWelcomeStateUnit(
-  client: SemiontClient,
+  session: SemiontSession,
 ): WelcomeStateUnit {
+  const { client } = session;
   const disposer = createDisposer();
 
   const userData$ = new BehaviorSubject<{ termsAcceptedAt?: string } | null>(null);

package/src/features/moderate-entity-tags/state/__tests__/entity-tags-state-unit.test.ts

@@ -1,4 +1,6 @@
 import { describe, it, expect, vi } from 'vitest';
+import { asStates } from '../../../../__tests__/test-client';
+import { sessionOf } from '../../../../__tests__/test-client';
 import { BehaviorSubject, firstValueFrom } from 'rxjs';
 import { filter } from 'rxjs/operators';
 import type { SemiontClient } from '@semiont/sdk';
@@ -17,7 +19,7 @@ function mockClient(overrides: {
   const entityTypes$ = overrides.entityTypes$ ?? new BehaviorSubject<string[] | undefined>(['Person', 'Place']);
   return {
     browse: {
-      entityTypes: () => entityTypes$.asObservable(),
+      entityTypes: () => asStates(entityTypes$.asObservable()),
     },
     frame: {
       addEntityType: overrides.addEntityType ?? vi.fn().mockResolvedValue(undefined),
@@ -27,9 +29,9 @@ function mockClient(overrides: {
 
 describe('createEntityTagsStateUnit', () => {
   it('exposes entity types from browse namespace', async () => {
-    const stateUnit = createEntityTagsStateUnit(mockClient(), mockBrowse());
+    const stateUnit = createEntityTagsStateUnit(sessionOf(mockClient()), mockBrowse());
 
-    const types = await firstValueFrom(stateUnit.entityTypes$);
+    const types = await firstValueFrom(stateUnit.entityTypes.value$);
     expect(types).toEqual(['Person', 'Place']);
 
     stateUnit.dispose();
@@ -37,20 +39,20 @@ describe('createEntityTagsStateUnit', () => {
 
   it('reports loading when entity types are undefined', async () => {
     const entityTypes$ = new BehaviorSubject<string[] | undefined>(undefined);
-    const stateUnit = createEntityTagsStateUnit(mockClient({ entityTypes$ }), mockBrowse());
+    const stateUnit = createEntityTagsStateUnit(sessionOf(mockClient({ entityTypes$ })), mockBrowse());
 
-    const loading = await firstValueFrom(stateUnit.isLoading$);
+    const loading = await firstValueFrom(stateUnit.entityTypes.loading$);
     expect(loading).toBe(true);
 
     entityTypes$.next(['Tag']);
-    const loaded = await firstValueFrom(stateUnit.isLoading$.pipe(filter((l) => !l)));
+    const loaded = await firstValueFrom(stateUnit.entityTypes.loading$.pipe(filter((l) => !l)));
     expect(loaded).toBe(false);
 
     stateUnit.dispose();
   });
 
   it('setNewTag updates newTag$', async () => {
-    const stateUnit = createEntityTagsStateUnit(mockClient(), mockBrowse());
+    const stateUnit = createEntityTagsStateUnit(sessionOf(mockClient()), mockBrowse());
 
     stateUnit.setNewTag('Organization');
     const tag = await firstValueFrom(stateUnit.newTag$);
@@ -61,7 +63,7 @@ describe('createEntityTagsStateUnit', () => {
 
   it('addTag calls client and clears newTag$', async () => {
     const addEntityType = vi.fn().mockResolvedValue(undefined);
-    const stateUnit = createEntityTagsStateUnit(mockClient({ addEntityType }), mockBrowse());
+    const stateUnit = createEntityTagsStateUnit(sessionOf(mockClient({ addEntityType })), mockBrowse());
 
     stateUnit.setNewTag('Event');
     await stateUnit.addTag();
@@ -75,7 +77,7 @@ describe('createEntityTagsStateUnit', () => {
 
   it('addTag ignores empty/whitespace input', async () => {
     const addEntityType = vi.fn();
-    const stateUnit = createEntityTagsStateUnit(mockClient({ addEntityType }), mockBrowse());
+    const stateUnit = createEntityTagsStateUnit(sessionOf(mockClient({ addEntityType })), mockBrowse());
 
     stateUnit.setNewTag('   ');
     await stateUnit.addTag();
@@ -87,7 +89,7 @@ describe('createEntityTagsStateUnit', () => {
 
   it('addTag sets error on failure', async () => {
     const addEntityType = vi.fn().mockRejectedValue(new Error('duplicate'));
-    const stateUnit = createEntityTagsStateUnit(mockClient({ addEntityType }), mockBrowse());
+    const stateUnit = createEntityTagsStateUnit(sessionOf(mockClient({ addEntityType })), mockBrowse());
 
     stateUnit.setNewTag('Person');
     await stateUnit.addTag();
@@ -107,10 +109,33 @@ describe('EntityTagsStateUnit — StateUnit axioms', () => {
     assertStateUnitAxioms({
       setup: () => {
         const browse = disposeProbe();
-        return { unit: createEntityTagsStateUnit(mockClient(), browse as unknown as ShellStateUnit), passedIn: [browse] };
+        return { unit: createEntityTagsStateUnit(sessionOf(mockClient()), browse as unknown as ShellStateUnit), passedIn: [browse] };
       },
       surfaces: (u) => [u.newTag$, u.error$, u.isAdding$],
       invocations: (u) => [() => u.setNewTag(''), () => u.addTag()],
     });
   });
 });
+
+describe('createEntityTagsStateUnit — terminal load failure', () => {
+  // `isLoading$` was `raw$.pipe(map(e => e === undefined))` and
+  // moderate/entity-tags/page.tsx returns a full-page loading screen off it,
+  // so a failed load froze the route. The existing `error$` is the ADD-tag
+  // error and is deliberately left alone.
+  // See .plans/PANEL-FAILURE-STATES.md
+
+  it('stops loading and surfaces the load failure, distinct from the add-tag error', async () => {
+    const entityTypes$ = new BehaviorSubject<string[] | undefined>(undefined);
+    const unit = createEntityTagsStateUnit(sessionOf(mockClient({ entityTypes$ })), mockBrowse());
+
+    expect(await firstValueFrom(unit.entityTypes.loading$)).toBe(true);
+    entityTypes$.next({ status: 'failed', error: new Error('Resource not found') } as never);
+
+    expect(await firstValueFrom(unit.entityTypes.loading$)).toBe(false);
+    expect(await firstValueFrom(unit.entityTypes.error$)).not.toBeNull();
+    // The add-tag error channel is untouched by a load failure.
+    expect(await firstValueFrom(unit.error$)).toBe('');
+
+    unit.dispose();
+  });
+});

package/src/features/moderate-entity-tags/state/entity-tags-state-unit.ts

@@ -1,13 +1,13 @@
-import { BehaviorSubject, type Observable, map } from 'rxjs';
+import { BehaviorSubject, type Observable } from 'rxjs';
 import { createDisposer } from '@semiont/sdk';
 import type { StateUnit } from '@semiont/core';
 import type { ShellStateUnit } from '../../../state/shell-state-unit';
-import type { SemiontClient } from '@semiont/sdk';
+import { trackList, type ListState } from '../../../state/list-state';
+import type { SemiontSession } from '@semiont/sdk';
 
 export interface EntityTagsStateUnit extends StateUnit {
   browse: ShellStateUnit;
-  entityTypes$: Observable<string[]>;
-  isLoading$: Observable<boolean>;
+  entityTypes: ListState<string[]>;
   newTag$: Observable<string>;
   error$: Observable<string>;
   isAdding$: Observable<boolean>;
@@ -16,9 +16,10 @@ export interface EntityTagsStateUnit extends StateUnit {
 }
 
 export function createEntityTagsStateUnit(
-  client: SemiontClient,
+  session: SemiontSession,
   browse: ShellStateUnit,
 ): EntityTagsStateUnit {
+  const { client } = session;
   const disposer = createDisposer();
   // `browse` (ShellStateUnit) is a *passed-in* dependency owned by the caller
   // (`useShellStateUnit`), not this unit — do NOT add it to the disposer (it's the
@@ -28,9 +29,8 @@ export function createEntityTagsStateUnit(
   const error$ = new BehaviorSubject<string>('');
   const isAdding$ = new BehaviorSubject<boolean>(false);
 
-  const raw$ = client.browse.entityTypes();
-  const entityTypes$: Observable<string[]> = raw$.pipe(map((e) => e ?? []));
-  const isLoading$: Observable<boolean> = raw$.pipe(map((e) => e === undefined));
+  const entityTypes = trackList<string[]>(() => client.browse.entityTypes(), []);
+  disposer.add(entityTypes.dispose);
 
   const addTag = async (): Promise<void> => {
     const tag = newTag$.getValue().trim();
@@ -49,8 +49,7 @@ export function createEntityTagsStateUnit(
 
   return {
     browse,
-    entityTypes$,
-    isLoading$,
+    entityTypes: entityTypes.state,
     newTag$: newTag$.asObservable(),
     error$: error$.asObservable(),
     isAdding$: isAdding$.asObservable(),

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

@@ -1,4 +1,6 @@
 import { describe, it, expect, vi } from 'vitest';
+import { asStates } from '../../../../__tests__/test-client';
+import { sessionOf } from '../../../../__tests__/test-client';
 import { BehaviorSubject, Observable, firstValueFrom } from 'rxjs';
 import { filter } from 'rxjs/operators';
 import type { SemiontClient } from '@semiont/sdk';
@@ -32,7 +34,7 @@ function mockClient(overrides: {
   const entityTypes$ = overrides.entityTypes$ ?? new BehaviorSubject<string[] | undefined>(['Person']);
   return {
     browse: {
-      entityTypes: () => entityTypes$.asObservable(),
+      entityTypes: () => asStates(entityTypes$.asObservable()),
     },
     yield: {
       fromToken: overrides.fromToken ?? vi.fn().mockResolvedValue({ '@id': 'src-1', representations: [{ mediaType: 'text/plain' }] }),
@@ -51,7 +53,7 @@ function mockClient(overrides: {
 
 describe('createComposePageStateUnit', () => {
   it('defaults to "new" mode', async () => {
-    const stateUnit = createComposePageStateUnit(mockClient(), mockBrowse(), {});
+    const stateUnit = createComposePageStateUnit(sessionOf(mockClient()), mockBrowse(), {});
 
     const mode = await firstValueFrom(stateUnit.mode$);
     expect(mode).toBe('new');
@@ -63,7 +65,7 @@ describe('createComposePageStateUnit', () => {
   });
 
   it('detects reference mode from params', async () => {
-    const stateUnit = createComposePageStateUnit(mockClient(), mockBrowse(), {
+    const stateUnit = createComposePageStateUnit(sessionOf(mockClient()), mockBrowse(), {
       annotationUri: 'ann-1',
       sourceDocumentId: 'doc-1',
       name: 'Reference Doc',
@@ -82,7 +84,7 @@ describe('createComposePageStateUnit', () => {
 
   it('parses storedContext in reference mode', async () => {
     const context = { annotation: { id: 'ann-1' }, sourceContext: 'text' };
-    const stateUnit = createComposePageStateUnit(mockClient(), mockBrowse(), {
+    const stateUnit = createComposePageStateUnit(sessionOf(mockClient()), mockBrowse(), {
       annotationUri: 'ann-1',
       sourceDocumentId: 'doc-1',
       name: 'Ref',
@@ -96,7 +98,7 @@ describe('createComposePageStateUnit', () => {
   });
 
   it('ignores malformed storedContext', async () => {
-    const stateUnit = createComposePageStateUnit(mockClient(), mockBrowse(), {
+    const stateUnit = createComposePageStateUnit(sessionOf(mockClient()), mockBrowse(), {
       annotationUri: 'ann-1',
       sourceDocumentId: 'doc-1',
       name: 'Ref',
@@ -113,9 +115,9 @@ describe('createComposePageStateUnit', () => {
   });
 
   it('exposes entity types', async () => {
-    const stateUnit = createComposePageStateUnit(mockClient(), mockBrowse(), {});
+    const stateUnit = createComposePageStateUnit(sessionOf(mockClient()), mockBrowse(), {});
 
-    const types = await firstValueFrom(stateUnit.entityTypes$);
+    const types = await firstValueFrom(stateUnit.entityTypes.value$);
     expect(types).toEqual(['Person']);
 
     stateUnit.dispose();
@@ -123,7 +125,7 @@ describe('createComposePageStateUnit', () => {
 
   it('save in new mode calls yield.resource', async () => {
     const resource = mockUpload('new-3');
-    const stateUnit = createComposePageStateUnit(mockClient({ resource }), mockBrowse(), {});
+    const stateUnit = createComposePageStateUnit(sessionOf(mockClient({ resource })), mockBrowse(), {});
 
     const id = await stateUnit.save({
       mode: 'new',
@@ -143,7 +145,7 @@ describe('createComposePageStateUnit', () => {
   it('save in reference mode calls yield.resource then bind.body', async () => {
     const resource = mockUpload('new-4');
     const body = vi.fn().mockResolvedValue(undefined);
-    const stateUnit = createComposePageStateUnit(mockClient({ resource, body }), mockBrowse(), {
+    const stateUnit = createComposePageStateUnit(sessionOf(mockClient({ resource, body })), mockBrowse(), {
       annotationUri: 'ann-1',
       sourceDocumentId: 'doc-1',
       name: 'Ref',
@@ -167,7 +169,7 @@ describe('createComposePageStateUnit', () => {
 
   it('save in clone mode calls yield.createFromToken', async () => {
     const createFromToken = vi.fn().mockResolvedValue({ resourceId: 'cloned-1' });
-    const stateUnit = createComposePageStateUnit(mockClient({ createFromToken }), mockBrowse(), {
+    const stateUnit = createComposePageStateUnit(sessionOf(mockClient({ createFromToken })), mockBrowse(), {
       mode: 'clone',
       token: 'tok-abc',
     });
@@ -192,9 +194,28 @@ describe('ComposePageStateUnit — StateUnit axioms', () => {
     assertStateUnitAxioms({
       setup: () => {
         const browse = disposeProbe();
-        return { unit: createComposePageStateUnit(mockClient(), browse as unknown as ShellStateUnit, {}), passedIn: [browse] };
+        return { unit: createComposePageStateUnit(sessionOf(mockClient()), browse as unknown as ShellStateUnit, {}), passedIn: [browse] };
       },
       surfaces: (u) => [u.mode$, u.loading$, u.cloneData$, u.referenceData$, u.gatheredContext$, u.uploadProgress$],
     });
   });
 });
+
+describe('createComposePageStateUnit — entity types load failure', () => {
+  // Lower severity than the two hangs: compose defaults to an empty picker,
+  // which misrepresents a failed load as "this KB has no entity types".
+  // See .plans/PANEL-FAILURE-STATES.md
+
+  it('surfaces the failure rather than presenting an empty picker as fact', async () => {
+    const entityTypes$ = new BehaviorSubject<string[] | undefined>(undefined);
+    const stateUnit = createComposePageStateUnit(sessionOf(mockClient({ entityTypes$ })), mockBrowse(), {});
+
+    entityTypes$.next({ status: 'failed', error: new Error('boom') } as never);
+
+    expect(await firstValueFrom(stateUnit.entityTypes.loading$)).toBe(false);
+    expect(await firstValueFrom(stateUnit.entityTypes.error$)).not.toBeNull();
+    expect(await firstValueFrom(stateUnit.entityTypes.value$)).toEqual([]);
+
+    stateUnit.dispose();
+  });
+});

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

@@ -1,10 +1,11 @@
-import { BehaviorSubject, type Observable, map } from 'rxjs';
+import { BehaviorSubject, type Observable } from 'rxjs';
 import type { GatheredContext, AnnotationId, AccessToken, ResourceDescriptor, ResourceId } from '@semiont/core';
 import { resourceId as makeResourceId, annotationId as makeAnnotationId } from '@semiont/core';
 import { createDisposer } from '@semiont/sdk';
 import type { StateUnit } from '@semiont/core';
 import type { ShellStateUnit } from '../../../state/shell-state-unit';
-import type { SemiontClient } from '@semiont/sdk';
+import { trackList, type ListState } from '../../../state/list-state';
+import type { SemiontSession } from '@semiont/sdk';
 import { decodeWithCharset, extensionForMediaType } from '@semiont/core';
 import type { UploadProgress } from '@semiont/sdk';
 
@@ -54,7 +55,7 @@ export interface ComposePageStateUnit extends StateUnit {
   cloneData$: Observable<CloneData | null>;
   referenceData$: Observable<ReferenceData | null>;
   gatheredContext$: Observable<GatheredContext | null>;
-  entityTypes$: Observable<string[]>;
+  entityTypes: ListState<string[]>;
   /**
    * Live upload-progress for the in-flight `save(...)` call. Emits the
    * full `UploadProgress` lifecycle (started → finished) while a save is
@@ -66,11 +67,12 @@ export interface ComposePageStateUnit extends StateUnit {
 }
 
 export function createComposePageStateUnit(
-  client: SemiontClient,
+  session: SemiontSession,
   browse: ShellStateUnit,
   params: ComposeParams,
   auth?: AccessToken,
 ): ComposePageStateUnit {
+  const { client } = session;
   const disposer = createDisposer();
   // `browse` (ShellStateUnit) is a *passed-in* dependency owned by the caller
   // (`useShellStateUnit`), not this unit — do NOT add it to the disposer (it's the
@@ -87,9 +89,8 @@ export function createComposePageStateUnit(
   const gatheredContext$ = new BehaviorSubject<GatheredContext | null>(null);
   const uploadProgress$ = new BehaviorSubject<UploadProgress | null>(null);
 
-  const entityTypes$: Observable<string[]> = client.browse.entityTypes().pipe(
-    map((e) => e ?? []),
-  );
+  const entityTypes = trackList<string[]>(() => client.browse.entityTypes(), []);
+  disposer.add(entityTypes.dispose);
 
   // Initialize based on mode
   if (isReferenceMode) {
@@ -192,7 +193,7 @@ export function createComposePageStateUnit(
     cloneData$: cloneData$.asObservable(),
     referenceData$: referenceData$.asObservable(),
     gatheredContext$: gatheredContext$.asObservable(),
-    entityTypes$,
+    entityTypes: entityTypes.state,
     uploadProgress$: uploadProgress$.asObservable(),
     save,
     dispose: () => {

package/src/features/resource-discovery/__tests__/ResourceDiscoveryPage.test.tsx

@@ -56,7 +56,9 @@ const createMockProps = (overrides?: Partial<ResourceDiscoveryPageProps>): Resou
     composeFirstResource: 'Compose First Resource',
     archived: 'Archived',
     created: 'Created:',
-    loadingKnowledgeBase: 'Loading knowledge base...',
+    recentFailed: 'Could not load resources.',
+  retry: 'Try again',
+  loadingKnowledgeBase: 'Loading knowledge base...',
   },
   ToolbarPanels: ({ children }: any) => <div data-testid="toolbar-panels">{children}</div>,
   ...overrides,

package/src/features/resource-discovery/components/ResourceDiscoveryPage.tsx

@@ -20,6 +20,13 @@ export interface ResourceDiscoveryPageProps {
   searchDocuments: ResourceDescriptor[];
   entityTypes: string[];
   isLoadingRecent: boolean;
+  /**
+   * The recent-resources load failed terminally (B15). Without it, "loading"
+   * derived from an absent value never resolves and this route freezes.
+   * See .plans/PANEL-FAILURE-STATES.md
+   */
+  recentError?: Error | null;
+  onRetryRecent?: () => void;
   isSearching: boolean;
 
   // Controlled search state
@@ -58,6 +65,8 @@ export interface ResourceDiscoveryPageProps {
     archived: string;
     created: string;
     loadingKnowledgeBase: string;
+    recentFailed: string;
+    retry: string;
   };
 
   // Component dependencies
@@ -69,6 +78,8 @@ export function ResourceDiscoveryPage({
   searchDocuments,
   entityTypes,
   isLoadingRecent,
+  recentError = null,
+  onRetryRecent,
   isSearching,
   searchQuery,
   onSearchQueryChange,
@@ -116,6 +127,20 @@ export function ResourceDiscoveryPage({
     }
   }, []);
 
+  // A terminally failed load is not still loading — check it first.
+  if (recentError) {
+    return (
+      <div className="semiont-page__loading">
+        <p className="semiont-page__loading-text">{t.recentFailed}</p>
+        {onRetryRecent && (
+          <button type="button" onClick={onRetryRecent} className="semiont-button" data-variant="secondary">
+            {t.retry}
+          </button>
+        )}
+      </div>
+    );
+  }
+
   // Loading state
   if (isLoadingRecent) {
     return (