@semiont/react-ui 0.5.21 → 0.5.23

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import * as _semiont_react_ui from '@semiont/react-ui';
+import { BrowseMediaRenderers as BrowseMediaRenderers$1, AnnotateMediaRenderers as AnnotateMediaRenderers$1 } from '@semiont/react-ui';
 import { Annotation, ResourceId, Selector, components, ResourceDescriptor, ValidationResult, StateUnit, GatheredContext, EventMap, DiscoveredKB, AnnotationId, AnchorStrategy, AnchorConfidence, StoredEventLike, ConnectionState, BackendDownload, ProgressEvent, AccessToken } from '@semiont/core';
 export { Annotation } from '@semiont/core';
 import * as React$1 from 'react';
@@ -6,7 +7,7 @@ import React__default, { ComponentType, ReactNode, KeyboardEvent as KeyboardEven
 import * as _codemirror_state from '@codemirror/state';
 import { HighlightStyle } from '@codemirror/language';
 import { WidgetType } from '@codemirror/view';
-import { SemiontClient, SemiontSession, DiscoveryTransport, DiscoveryState, SemiontBrowser, SessionStorage, SessionFactory, OpenResource, TagSchema, UploadProgress, BeckonStateUnit, MarkStateUnit, GatherStateUnit, YieldStateUnit, ReferencedByEntry } from '@semiont/sdk';
+import { SemiontSession, SemiontClient, DiscoveryTransport, DiscoveryState, SemiontBrowser, SessionStorage, SessionFactory, OpenResource, TagSchema, UploadProgress, BeckonStateUnit, MarkStateUnit, GatherStateUnit, YieldStateUnit, ReferencedByEntry } from '@semiont/sdk';
 export { BeckonStateUnit, GatherStateUnit, GenerateDocumentOptions, HOVER_DELAY_MS, HoverHandlers, MarkStateUnit, MatchStateUnit, PendingAnnotation, SearchPipeline, SearchPipelineOptions, SearchState, TagSchema, YieldStateUnit, createBeckonStateUnit, createGatherStateUnit, createHoverHandlers, createMarkStateUnit, createMatchStateUnit, createSearchPipeline, createYieldStateUnit } from '@semiont/sdk';
 import { Observable } from 'rxjs';
 
@@ -765,6 +766,37 @@ declare function sanitizeImageURL(url: string): string | null;
 
 declare function useStateUnit<T extends StateUnit>(factory: () => T): T;
 
+/**
+ * Construct a state unit whose lifetime is bound to a live `SemiontSession`
+ * (.plans/SESSION-TYPED-FACTORIES.md — the session gate as API shape).
+ *
+ * Contract, in the order the KB-switch bug family demands it:
+ * - one construction per live session, however often the component rerenders;
+ * - on session swap, the OLD unit's `dispose()` runs strictly BEFORE the new
+ *   factory — a unit must never coexist with its successor, or it keeps
+ *   serving a disposed client's inert (B16) caches;
+ * - no session → no construction, and the `T | undefined` return makes the
+ *   caller handle it — the null-check lives at exactly this one layer, not
+ *   inside `!`-asserted factories (the auth/welcome production crash);
+ * - unmount disposes.
+ *
+ * Keying is by session OBJECT identity, which coincides with `session.id`:
+ * successive sessions are distinct objects with distinct ids by construction
+ * (`SemiontSession`'s instance counter exists for exactly this).
+ *
+ * The unit is created inside the effect, not during render — render stays
+ * pure (StrictMode-safe: its probe mount cleanly disposes the probe unit),
+ * and React's cleanup-before-next-effect ordering is what GUARANTEES
+ * dispose-before-create on swap. Consequence: the unit is `undefined` on the
+ * very first render frame; session-gated pages already render a loading
+ * state for exactly that frame.
+ *
+ * The factory is read through a ref so the effect keys ONLY on the session —
+ * an inline-closure factory (the universal call-site idiom) must not retrigger
+ * construction on every render.
+ */
+declare function useSessionStateUnit<T extends StateUnit>(session: SemiontSession | undefined, factory: (session: SemiontSession) => T): T | undefined;
+
 /**
  * Creates a debounced version of a callback function
  *
@@ -1810,6 +1842,49 @@ declare function PermissionDeniedModal(): React$1.JSX.Element;
  */
 declare function SessionExpiredModal(): React$1.JSX.Element;
 
+/**
+ * Common props for an ANNOTATING media renderer. The read-only sibling is
+ * `MediaRendererProps` in `browse-renderers.tsx`; this one additionally
+ * carries the active tool, because annotating is an interaction, not a paint.
+ *
+ * `content` is decoded text for the text renderer, or a media URL for the
+ * image / PDF renderers. `annotations` is the FLAT list — a renderer derives
+ * whatever shape it needs (the text one segments it), so a custom renderer is
+ * never handed a projection only one implementation can use.
+ * See .plans/ANNOTATE-RENDERER-REGISTRY.md (D1)
+ */
+interface AnnotateMediaRendererProps {
+    content: string;
+    mimeType: string;
+    resourceUri: string;
+    annotations: Annotation[];
+    /** Session for interaction routing — the canvases emit via `session.client`. */
+    session: SemiontSession | null;
+    /** Active drawing tool, or null when nothing is selected (read-only paint). */
+    drawingMode: ShapeType | null;
+    selectedMotivation: SelectionMotivation | null;
+    hoveredAnnotationId?: string | null;
+    hoverDelayMs?: number;
+    newAnnotationIds?: Set<string>;
+    scrollToAnnotationId?: string | null;
+    showLineNumbers?: boolean;
+    enableWidgets?: boolean;
+    getTargetResourceName?: (resourceId: string) => string | undefined;
+    generatingReferenceId?: string | null;
+}
+/** Annotating media dispatch, keyed by the registry render mode. */
+type AnnotateMediaRenderers = Partial<Record<string, ComponentType<AnnotateMediaRendererProps>>>;
+declare function TextAnnotateRenderer({ content, annotations, session, newAnnotationIds, hoveredAnnotationId, scrollToAnnotationId, showLineNumbers, hoverDelayMs, enableWidgets, getTargetResourceName, generatingReferenceId, }: AnnotateMediaRendererProps): React$1.JSX.Element;
+declare function ImageAnnotateRenderer({ content, resourceUri, annotations, session, drawingMode, selectedMotivation, hoveredAnnotationId, hoverDelayMs, }: AnnotateMediaRendererProps): React$1.JSX.Element | null;
+declare function PdfAnnotateRenderer({ content, resourceUri, annotations, session, drawingMode, selectedMotivation, hoveredAnnotationId, hoverDelayMs, }: AnnotateMediaRendererProps): React$1.JSX.Element | null;
+/**
+ * Default annotating media renderers. `AnnotateView` merges a caller's
+ * `renderers` override on top of these, so a host can swap one renderer (its
+ * own PDF viewer, say) or add a mode without forking the view — the same seam
+ * `defaultBrowseRenderers` gives the read-only path.
+ */
+declare const defaultAnnotateRenderers: Record<'text' | 'image' | 'pdf', ComponentType<AnnotateMediaRendererProps>>;
+
 interface Props$8 {
     content: string;
     mimeType?: string;
@@ -1833,6 +1908,8 @@ interface Props$8 {
     onModeChange?: (mode: boolean) => void;
     /** Render the built-in bar (default). false → no bar; selection capture and drawing stay live. */
     showToolbar?: boolean;
+    /** Override the annotating media renderers (render mode → renderer); merged over the defaults. */
+    renderers?: AnnotateMediaRenderers;
 }
 /**
  * View component for annotating resources with text selection and drawing
@@ -1840,17 +1917,30 @@ interface Props$8 {
  * @emits mark:requested - User requested to create annotation. Payload: { selector: Selector | Selector[], motivation: SelectionMotivation }
  * @subscribes beckon:hover - Annotation hovered. Payload: { annotationId: string | null }
  */
-declare function AnnotateView({ content, mimeType, resourceUri, annotations, uiState, onUIStateChange, enableWidgets, getTargetResourceName, generatingReferenceId, showLineNumbers, hoverDelayMs, annotateMode, session, newAnnotationIds, onModeChange, showToolbar, }: Props$8): React$1.JSX.Element;
+declare function AnnotateView({ content, mimeType, resourceUri, annotations, uiState, onUIStateChange, enableWidgets, getTargetResourceName, generatingReferenceId, showLineNumbers, hoverDelayMs, annotateMode, session, newAnnotationIds, onModeChange, showToolbar, renderers, }: Props$8): React$1.JSX.Element;
 
 interface Props$7 {
-    rUri: ResourceId;
+    /**
+     * The resource's stored events, and how their load is going. Supplied by the
+     * owner (which already holds them on its state unit) rather than fetched
+     * here: a self-fetching panel can only model (value | not-yet), so a
+     * terminal failure (B15) is indistinguishable from a request still in
+     * flight and the panel says "Loading..." for ever.
+     * See .plans/PANEL-FAILURE-STATES.md
+     */
+    events: StoredEventLike[];
+    eventsLoading?: boolean;
+    eventsError?: Error | null;
+    onRetryEvents?: () => void;
+    /** Annotations for the same resource — used to resolve event → annotation. */
+    annotations?: Annotation[];
     hoveredAnnotationId?: string | null;
     onEventHover?: (annotationId: string | null) => void;
     onEventClick?: (annotationId: string | null) => void;
     Link: React__default.ComponentType<LinkComponentProps>;
     routes: RouteBuilder;
 }
-declare function AnnotationHistory({ rUri, hoveredAnnotationId, onEventHover, onEventClick, Link, routes }: Props$7): React__default.JSX.Element | null;
+declare function AnnotationHistory({ events: eventsData, eventsLoading, eventsError, onRetryEvents, annotations, hoveredAnnotationId, onEventHover, onEventClick, Link, routes, }: Props$7): React__default.JSX.Element | null;
 
 /**
  * Common props for a read-only ("browse") media renderer. `content` is decoded
@@ -1955,19 +2045,21 @@ declare function HistoryEvent({ event, annotations, allEvents, isRelated, t, Lin
 /**
  * ResourceViewer - Display and interact with resource content and annotations
  *
- * This component uses event-driven architecture for real-time updates:
- * - Subscribes to make-meaning events (mark:added, mark:removed, mark:body-updated)
- * - Automatically invalidates cache when annotations change
- * - No manual refetch needed - events handle cache invalidation
+ * Real-time updates arrive through the sdk, not through this component:
+ * the client's BrowseNamespace invalidates the right resource's annotation
+ * list on mark:added/mark:removed (payload-keyed) and patches
+ * mark:body-updated in place, so the live queries feeding `annotations`
+ * refresh on their own. The viewer subscribes only to `browse:click`
+ * (annotation-click routing).
  *
  * Bring-your-own-session: the `session` (SemiontSession) and the host's
  * navigation / panel callbacks come in as props — no SemiontProvider required.
- * Every event it subscribes to is session-scoped (mark:*, browse:click) and
- * reaches it via `session.subscribe`. Translations fall back to built-in English
- * when no TranslationProvider is mounted; caching flows through `session.client.browse.*`.
+ * Every event it subscribes to is session-scoped and reaches it via
+ * `session.subscribe`. Translations fall back to built-in English when no
+ * TranslationProvider is mounted; caching flows through `session.client.browse.*`.
  *
  * Event flow:
- *   make-meaning → EventLog → SSE → EventBus → ResourceViewer → Cache invalidation
+ *   make-meaning → EventLog → SSE → EventBus → sdk cache invalidation → live queries
  */
 interface Props$4 {
     resource: ResourceDescriptor & {
@@ -2019,18 +2111,31 @@ interface Props$4 {
      * this makes that opt-out a contract instead of a CSS override.
      */
     showToolbar?: boolean;
+    /**
+     * Override the read-only / annotating media renderers respectively; each is
+     * merged over its defaults by the view below.
+     *
+     * Two flat props rather than one nested object: the registries are
+     * separately typed (`MediaRendererProps` vs `AnnotateMediaRendererProps`)
+     * and nesting them would imply an interchangeability that does not exist.
+     *
+     * Forwarding them is what makes the registries reachable at all for a host
+     * that imports `ResourceViewer` — the documented entry point. Before this,
+     * reaching `BrowseView`'s `renderers` meant dropping to `BrowseView`
+     * directly and reimplementing the browse/annotate switching this component
+     * exists to provide. See .plans/ANNOTATE-RENDERER-REGISTRY.md (D5)
+     */
+    browseRenderers?: BrowseMediaRenderers;
+    annotateRenderers?: AnnotateMediaRenderers;
 }
 /**
  * Deletion calls `session.client.mark.delete(...)` directly (no bus emit);
  * panel opening invokes the host's `onOpenPanel` callback — the host owns
  * the panel and any `panel:open` emission.
  *
- * @subscribes mark:added - New annotation was added. Payload: { annotation: Annotation }
- * @subscribes mark:removed - Annotation was removed. Payload: { annotationId: string }
- * @subscribes mark:body-updated - Annotation was updated. Payload: { annotation: Annotation }
  * @subscribes browse:click - User clicked on annotation. Payload: { annotationId: string, motivation, anchorRect? }
  */
-declare function ResourceViewer({ resource, annotations, session, onOpenResource, onOpenPanel, onLinkClick, onReferenceHover, inline, newAnnotationIds, generatingReferenceId, showLineNumbers, hoverDelayMs, hoveredAnnotationId: hoveredAnnotationIdProp, annotateMode: annotateModeProp, onAnnotateModeChange, clickAction: clickActionProp, onClickActionChange, selectionMotivation: selectionMotivationProp, onSelectionMotivationChange, shape: shapeProp, onShapeChange, showToolbar, }: Props$4): React__default.JSX.Element;
+declare function ResourceViewer({ resource, annotations, session, onOpenResource, onOpenPanel, onLinkClick, onReferenceHover, inline, newAnnotationIds, generatingReferenceId, showLineNumbers, hoverDelayMs, hoveredAnnotationId: hoveredAnnotationIdProp, annotateMode: annotateModeProp, onAnnotateModeChange, clickAction: clickActionProp, onClickActionChange, selectionMotivation: selectionMotivationProp, onSelectionMotivationChange, shape: shapeProp, onShapeChange, showToolbar, browseRenderers, annotateRenderers, }: Props$4): React__default.JSX.Element;
 
 interface AssessmentEntryProps {
     /** Session for interaction routing (browse.click etc.); the panel threads it. */
@@ -2266,9 +2371,25 @@ interface Props$1 {
     Link: React__default.ComponentType<LinkComponentProps>;
     routes: RouteBuilder;
     allEntityTypes: string[];
+    /**
+     * The entity-type list failed to load. Without it the picker's empty branch
+     * asserts "no entity types available" — a claim about the knowledge base
+     * that a failed load cannot support.
+     * See .plans/PANEL-FAILURE-STATES.md
+     */
+    entityTypesError?: Error | null;
     generatingReferenceId?: string | null;
     referencedBy?: ReferencedBy[];
     referencedByLoading?: boolean;
+    /**
+     * The incoming-references load failed terminally (B15). Distinct from
+     * `referencedByLoading` — without it a dead request is indistinguishable
+     * from one still in flight, and the panel says "Loading..." forever.
+     * See .plans/PANEL-FAILURE-STATES.md
+     */
+    referencedByError?: Error | null;
+    /** Retry the failed incoming-references load. */
+    onRetryReferencedBy?: () => void;
     pendingAnnotation: PendingAnnotation$2 | null;
     scrollToAnnotationId?: string | null;
     onScrollCompleted?: () => void;
@@ -2286,7 +2407,7 @@ interface Props$1 {
  * @emits mark:cancel-pending - Cancel pending reference annotation. Payload: undefined
  * @subscribes browse:click - Annotation clicked. Payload: { annotationId: string }
  */
-declare function ReferencesPanel({ session, onOpenResource, resourceId, annotations, isAssisting, progress, annotateMode, Link, routes, allEntityTypes, generatingReferenceId, referencedBy, referencedByLoading, pendingAnnotation, scrollToAnnotationId, onScrollCompleted, hoveredAnnotationId, locale, sourceLanguage, }: Props$1): React__default.JSX.Element;
+declare function ReferencesPanel({ session, onOpenResource, resourceId, annotations, isAssisting, progress, annotateMode, Link, routes, allEntityTypes, entityTypesError, generatingReferenceId, referencedBy, referencedByLoading, referencedByError, onRetryReferencedBy, pendingAnnotation, scrollToAnnotationId, onScrollCompleted, hoveredAnnotationId, locale, sourceLanguage, }: Props$1): React__default.JSX.Element;
 
 type Agent = components['schemas']['Agent'];
 interface Props {
@@ -2396,6 +2517,14 @@ interface UnifiedAnnotationsPanelProps {
     /** Host-owned navigation: called with the resolved resource id when a reference entry opens. */
     onOpenResource?: (resourceId: string) => void;
     annotations: Annotation[];
+    /**
+     * The annotations load failed terminally (B15). Every tab here derives from
+     * the one `annotations` array, so without this the panel presents an empty
+     * array as fact — "no highlights" for a resource that may be full of them.
+     * See .plans/PANEL-FAILURE-STATES.md
+     */
+    annotationsError?: Error | null;
+    onRetryAnnotations?: () => void;
     annotators: Record<string, Annotator>;
     annotateMode?: boolean;
     assistingMotivation?: Motivation | null;
@@ -2405,6 +2534,9 @@ interface UnifiedAnnotationsPanelProps {
     generatingReferenceId?: string | null;
     referencedBy?: any[];
     referencedByLoading?: boolean;
+    entityTypesError?: Error | null;
+    referencedByError?: Error | null;
+    onRetryReferencedBy?: () => void;
     resourceId: string;
     initialTab?: TabKey;
     initialTabGeneration?: number;
@@ -2751,6 +2883,11 @@ interface ResourceGenerateModalProps {
     defaultTitle: string;
     locale: string;
     gatherDefaults?: Partial<ResourceGatherConfig>;
+    /**
+     * Entity types offered in the exclusion picker. Owner-supplied so the
+     * modal cannot present a failed load as an empty vocabulary.
+     */
+    entityTypeOptions?: string[];
     /**
      * Emit the chosen generation config. The parent runs the job
      * (`client.yield.fromResource(resourceId, …).run(…)`) — mirrors how the
@@ -2764,7 +2901,7 @@ interface ResourceGenerateModalProps {
  * `gather.resource` → review the gathered `GatheredContext` → configure
  * generation → emit. Reuses the kind-aware `GatherContextStep` for the review.
  */
-declare function ResourceGenerateModal({ isOpen, onClose, resourceId, defaultTitle, locale, gatherDefaults, onGenerateSubmit, translations: t, }: ResourceGenerateModalProps): React$1.JSX.Element;
+declare function ResourceGenerateModal({ isOpen, onClose, resourceId, defaultTitle, locale, gatherDefaults, entityTypeOptions, onGenerateSubmit, translations: t, }: ResourceGenerateModalProps): React$1.JSX.Element;
 
 interface SearchModalProps$1 {
     isOpen: boolean;
@@ -3889,6 +4026,43 @@ interface TagSchemasPageProps {
 }
 declare function TagSchemasPage({ schemas, isLoading, theme, showLineNumbers, activePanel, translations: t, ToolbarPanels, Toolbar, }: TagSchemasPageProps): React__default.JSX.Element;
 
+/**
+ * A cache-backed list in its real states.
+ *
+ * `loading$` is true only until THIS subscription's first value; once a value
+ * has arrived it never re-enters — even `retry()` routes through
+ * `revalidating$` then — so a blocking spinner keyed on it structurally
+ * cannot latch over rendered rows. The one deliberate exception is BEFORE any
+ * value: `retry()` on a never-loaded list returns to the blocking state,
+ * because there is nothing to render behind a non-blocking indicator.
+ * `revalidating$` is the non-blocking sibling: the thunk's chain has moved to
+ * a cache key that is not resolved yet (the cache emits `undefined` for it)
+ * while `value$` still holds the previous key's rows. Views keep rendering the
+ * stale list; a subtle indicator is optional.
+ *
+ * Why two signals instead of routing a late `undefined` back into `loading$`:
+ * a stable cache key can never go value→undefined (`invalidate()` keeps the
+ * value per B7; `remove()` is not used on list caches), so a late `undefined`
+ * only ever means "new key, fetch in flight". Treating that as blocking
+ * turns a routine filter switch into a full-page spinner — and if the fetch
+ * is lost, into a spinner that never resolves. The failure path stays B14 →
+ * B15 → `error$`, which views check before either signal.
+ * See .plans/PANEL-FAILURE-STATES.md
+ */
+interface ListState<T> {
+    value$: Observable<T>;
+    /**
+     * True until the first value. Never re-enters after one — a `retry()`
+     * before any value (nothing to render) is the sole way back in.
+     */
+    loading$: Observable<boolean>;
+    /** True while a NEW key's fetch is pending behind a stale `value$`. */
+    revalidating$: Observable<boolean>;
+    error$: Observable<Error | null>;
+    /** Re-subscribe: B15 clears the failure marker on a fresh `observe()`. */
+    retry(): void;
+}
+
 type ComposeMode = 'new' | 'clone' | 'reference';
 interface ComposeParams {
     mode?: string | undefined;
@@ -3930,7 +4104,7 @@ 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
@@ -3940,7 +4114,7 @@ interface ComposePageStateUnit extends StateUnit {
     uploadProgress$: Observable<UploadProgress | null>;
     save(params: SaveResourceParams$1): Promise<string>;
 }
-declare function createComposePageStateUnit(client: SemiontClient, browse: ShellStateUnit, params: ComposeParams, auth?: AccessToken): ComposePageStateUnit;
+declare function createComposePageStateUnit(session: SemiontSession, browse: ShellStateUnit, params: ComposeParams, auth?: AccessToken): ComposePageStateUnit;
 
 /**
  * ResourceComposePage Component
@@ -4056,6 +4230,13 @@ 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;
     searchQuery: string;
     onSearchQueryChange: (query: string) => void;
@@ -4083,10 +4264,12 @@ interface ResourceDiscoveryPageProps {
         archived: string;
         created: string;
         loadingKnowledgeBase: string;
+        recentFailed: string;
+        retry: string;
     };
     ToolbarPanels: React__default.ComponentType<any>;
 }
-declare function ResourceDiscoveryPage({ recentDocuments, searchDocuments, entityTypes, isLoadingRecent, isSearching, searchQuery, onSearchQueryChange, selectedEntityType, onSelectedEntityTypeChange, theme, showLineNumbers, activePanel, onNavigateToResource, onNavigateToCompose, translations: t, ToolbarPanels, }: ResourceDiscoveryPageProps): React__default.JSX.Element;
+declare function ResourceDiscoveryPage({ recentDocuments, searchDocuments, entityTypes, isLoadingRecent, recentError, onRetryRecent, isSearching, searchQuery, onSearchQueryChange, selectedEntityType, onSelectedEntityTypeChange, theme, showLineNumbers, activePanel, onNavigateToResource, onNavigateToCompose, translations: t, ToolbarPanels, }: ResourceDiscoveryPageProps): React__default.JSX.Element;
 
 /**
  * ResourceCard Component
@@ -4151,6 +4334,13 @@ 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$1;
+    annotateRenderers?: AnnotateMediaRenderers$1;
 }
 /**
  * ResourceViewerPage - Main component
@@ -4174,7 +4364,7 @@ interface ResourceViewerPageProps {
  * bind:body-error, job:complete, job:fail, mark:assist-timeout) are
  * subscribed by useOutcomeToasts.
  */
-declare function ResourceViewerPage({ resource, rUri, locale, Link, routes, ToolbarPanels, refetchDocument, streamStatus, knowledgeBaseName, }: ResourceViewerPageProps): React__default.JSX.Element;
+declare function ResourceViewerPage({ resource, rUri, locale, Link, routes, ToolbarPanels, refetchDocument, streamStatus, knowledgeBaseName, browseRenderers, annotateRenderers, }: ResourceViewerPageProps): React__default.JSX.Element;
 
 interface HoverEmitterProps {
     onMouseEnter: () => void;
@@ -4186,7 +4376,7 @@ interface SessionStateUnit extends StateUnit {
     isLoggingOut$: Observable<boolean>;
     logout(): Promise<void>;
 }
-declare function createSessionStateUnit(client: SemiontClient): SessionStateUnit;
+declare function createSessionStateUnit(session: SemiontSession): SessionStateUnit;
 
 interface AnnotationGroups {
     highlights: Annotation[];
@@ -4209,27 +4399,42 @@ interface ResourceViewerPageStateUnit extends StateUnit {
     mark: MarkStateUnit;
     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>;
     wizard$: Observable<WizardState>;
     closeWizard(): void;
 }
-declare function createResourceViewerPageStateUnit(client: SemiontClient, resourceId: ResourceId, locale: string, browse: ShellStateUnit, options?: {
+declare function createResourceViewerPageStateUnit(session: SemiontSession, resourceId: ResourceId, locale: string, browse: ShellStateUnit, options?: {
     mediaType?: string;
 }): ResourceViewerPageStateUnit;
 
 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;
 }
-declare function createResourceLoaderStateUnit(client: SemiontClient, resourceId: ResourceId): ResourceLoaderStateUnit;
+/**
+ * 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)
+ */
+declare function createResourceLoaderStateUnit(session: SemiontSession, resourceId: ResourceId): ResourceLoaderStateUnit;
 
 interface AdminUsersStateUnit extends StateUnit {
     browse: ShellStateUnit;
@@ -4242,7 +4447,7 @@ interface AdminUsersStateUnit extends StateUnit {
         isActive?: boolean;
     }): Promise<void>;
 }
-declare function createAdminUsersStateUnit(client: SemiontClient, browse: ShellStateUnit): AdminUsersStateUnit;
+declare function createAdminUsersStateUnit(session: SemiontSession, browse: ShellStateUnit): AdminUsersStateUnit;
 
 interface AdminSecurityStateUnit extends StateUnit {
     browse: ShellStateUnit;
@@ -4250,7 +4455,7 @@ interface AdminSecurityStateUnit extends StateUnit {
     allowedDomains$: Observable<string[]>;
     isLoading$: Observable<boolean>;
 }
-declare function createAdminSecurityStateUnit(client: SemiontClient, browse: ShellStateUnit): AdminSecurityStateUnit;
+declare function createAdminSecurityStateUnit(session: SemiontSession, browse: ShellStateUnit): AdminSecurityStateUnit;
 
 interface WelcomeStateUnit extends StateUnit {
     userData$: Observable<{
@@ -4259,7 +4464,7 @@ interface WelcomeStateUnit extends StateUnit {
     isProcessing$: Observable<boolean>;
     acceptTerms(): Promise<void>;
 }
-declare function createWelcomeStateUnit(client: SemiontClient): WelcomeStateUnit;
+declare function createWelcomeStateUnit(session: SemiontSession): WelcomeStateUnit;
 
 interface DiscoverSearchPipeline {
     query$: Observable<string>;
@@ -4272,25 +4477,23 @@ interface DiscoverSearchPipeline {
 interface DiscoverStateUnit extends StateUnit {
     browse: ShellStateUnit;
     search: DiscoverSearchPipeline;
-    recentResources$: Observable<ResourceDescriptor[]>;
-    entityTypes$: Observable<string[]>;
-    isLoadingRecent$: Observable<boolean>;
+    recent: ListState<ResourceDescriptor[]>;
+    entityTypes: ListState<string[]>;
     selectedEntityType$: Observable<string>;
     setSelectedEntityType(value: string): void;
 }
-declare function createDiscoverStateUnit(client: SemiontClient, browse: ShellStateUnit): DiscoverStateUnit;
+declare function createDiscoverStateUnit(session: SemiontSession, browse: ShellStateUnit): DiscoverStateUnit;
 
 interface EntityTagsStateUnit extends StateUnit {
     browse: ShellStateUnit;
-    entityTypes$: Observable<string[]>;
-    isLoading$: Observable<boolean>;
+    entityTypes: ListState<string[]>;
     newTag$: Observable<string>;
     error$: Observable<string>;
     isAdding$: Observable<boolean>;
     setNewTag(value: string): void;
     addTag(): Promise<void>;
 }
-declare function createEntityTagsStateUnit(client: SemiontClient, browse: ShellStateUnit): EntityTagsStateUnit;
+declare function createEntityTagsStateUnit(session: SemiontSession, browse: ShellStateUnit): EntityTagsStateUnit;
 
 /**
  * `ShellStateUnit` is app-scoped — it owns toolbar panel state and lives on
@@ -4319,8 +4522,17 @@ declare function useShellStateUnit(): ShellStateUnit;
  *   ready yet (e.g. `semiont?.browse.events(rUri)` when the active session is
  *   still loading). In that case the hook is a no-op and returns undefined.
  * - Unsubscribes automatically on unmount or when `obs$` changes.
+ * - A source ERROR is terminal absence: the hook keeps its last value and
+ *   reports the reason. It does not surface the error as state — a hook whose
+ *   whole contract is "the current value" has nowhere to put one. Callers that
+ *   must RENDER a failure need it modelled by the thing they observe (see
+ *   `createResourceLoaderStateUnit`'s `error$`); this handler exists so the
+ *   error is not left unhandled, which RxJS rethrows asynchronously — the
+ *   `Uncaught BusRequestError` seen in the field whenever a cache key
+ *   exhausted its B14 retry with nothing stored (B15).
+ *   See .plans/bugs/resource-page-frozen-on-disposed-client-after-kb-switch.md
  */
 declare function useObservable<T>(obs$: Observable<T> | null | undefined): T | undefined;
 
-export { ANNOTATORS, AVAILABLE_LOCALES, AdminDevOpsPage, AdminExchangePage, AdminSecurityPage, AdminUsersPage, AnnotateToolbar, AnnotateView, AnnotationHistory, AnnotationOverlay, AnnotationProvider, AssessmentEntry, AssessmentPanel, AssistProgress, AssistSection, AssistShell, AsyncErrorBoundary, AuthErrorDisplay, BrowseView, Button, ButtonGroup, COMMON_PANELS, CodeMirrorRenderer, CollaborationPanel, CollapsibleResourceNavigation, CommentEntry, CommentsPanel, ComposeLoadingState, EntityTagsPage, EntityTypeBadges, ErrorBoundary, ExportCard, Footer, HighlightEntry, HighlightPanel, HistoryEvent, ImageBrowseRenderer, ImageURLSchema, ImageViewer, ImportCard, ImportProgress, JsonLdPanel, JsonLdView, KeyboardShortcutsHelpModal, LeftSidebar, LinkedDataPage, LiveRegionProvider, NavigationMenu, OAuthUserSchema, ObservableLink, PageLayout, PanelHeader, PdfBrowseRenderer, PermissionDeniedModal, PopupContainer, PopupHeader, ProtectedErrorBoundary, RESOURCE_PANELS, RecentDocumentsPage, ReferenceEntry, ReferenceResolutionWidget, ReferenceWizardModal, ReferencesPanel, ResizeHandle, ResourceAnnotationsProvider, ResourceCard, ResourceComposePage, ResourceDiscoveryPage, ResourceErrorState, ResourceGenerateModal, ResourceInfoPanel, ResourceLoadingState, ResourceSearchModal, ResourceTagsInline, ResourceViewer, ResourceViewerPage, SearchModal, SelectedTextDisplay, SemiontBranding, SemiontFavicon, SemiontProvider, SessionExpiredModal, SessionExpiryBanner, SessionTimer, SettingsPanel, SignInForm, SignUpForm, SimpleNavigation, SkipLinks, SortableResourceTab, StatisticsPanel, StatusDisplay, SvgDrawingCanvas, TagEntry, TagSchemasPage, TaggingPanel, TextBrowseRenderer, ThemeProvider, ToastContainer, ToastProvider, Toolbar, TranslationProvider, UnifiedAnnotationsPanel, UnifiedHeader, UploadProgressBar, UserMenuSkeleton, WebBrowserStorage, WelcomePage, annotatorKeyForMotivation, applyHighlights, buildSourceToRenderedMap, buildTextNodeIndex, buttonStyles, clearHighlights, createAdminSecurityStateUnit, createAdminUsersStateUnit, createComposePageStateUnit, createDiscoverStateUnit, createEntityTagsStateUnit, createExchangeStateUnit, createResourceLoaderStateUnit, createResourceViewerPageStateUnit, createSessionStateUnit, createShellStateUnit, createWelcomeStateUnit, cssVariables, defaultBrowseRenderers, faviconPaths, formatTime, generateCSSVariables, getResourceIcon, getSelectedShapeForSelectorType, getSelectorType, getShortcutDisplay, getSupportedShapes, hideWidgetPreview, isShapeSupported, jsonLightHighlightStyle, jsonLightTheme, resolveAnnotationRanges, sanitizeImageURL, saveSelectedShapeForSelectorType, setPdfWorkerSrc, showWidgetPreview, supportsDetection, toOverlayAnnotations, tokens, useAnnotationManager, useDebounce, useDebouncedCallback, useDocumentAnnouncements, useDoubleKeyPress, useDropdown, useEventSubscription, useEventSubscriptions, useFormAnnouncements, useHoverDelay, useHoverEmitter, useIsTyping, useKBDiscovery, useKeyboardShortcuts, useLanguageChangeAnnouncements, useLineNumbers, useLiveRegion, useLoadingState, useLocalStorage, useMediaToken, useObservable, useObservableExternalNavigation, useObservableRouter, usePanelWidth, usePendingCreation, usePreloadTranslations, useResourceAnnotations, useResourceContent, useResourceGather, useResourceLoader, useResourceLoadingAnnouncements, useRovingTabIndex, useSearchAnnouncements, useSemiont, useSessionEventSubscriptions, useSessionExpiry, useShellStateUnit, useStateUnit, useTheme, useToast, useToolbarPrefs, useTranslations };
-export type { AdminDevOpsPageProps, AdminExchangePageProps, AdminExchangePageTranslations, AdminSecurityPageProps, AdminSecurityStateUnit, AdminUser, AdminUserStats, AdminUsersPageProps, AdminUsersStateUnit, AnnotationConfig, AnnotationCreationHandler, AnnotationGroups, AnnotationHandlers, AnnotationManager, AnnotationProviderProps, AnnotationUIState, AnnotationsCollection, Annotator, AnnotatorKey, AssistProgressProps, AssistProgressTranslations, AssistShellProps, AuthErrorDisplayProps, AvailableLocale, BorderRadiusToken, BrowseMediaRenderers, ButtonGroupProps, ButtonProps, ClickAction, CloneData, CollapsibleResourceNavigationProps, ColorToken, ComposeLoadingStateProps, ComposeMode, ComposePageStateUnit, ComposeParams, CreateAnnotationParams, CreateConfig, DeleteAnnotationParams, DetectionConfig, DevOpsFeature, DiscoverStateUnit, DrawingMode, EntityTagsPageProps, EntityTagsStateUnit, ExchangeStateUnit, ExportCardProps, ExportCardTranslations, HoverEmitterProps, ImportCardProps, ImportCardTranslations, ImportPreview, ImportProgressProps, ImportProgressTranslations, KBDiscoveryOptions, KBDiscoveryResult, KeyboardShortcut, LinkComponentProps, LinkedDataPageProps, LinkedDataPageTranslations, MediaRendererProps, Motivation$7 as Motivation, NavigationItem, NavigationMenuHelper, NavigationProps, OAuthProvider, OAuthUser, ObservableLinkProps, OverlayAnnotation, PendingCreation, RecentDocumentsPageProps, ReferenceData, ReferenceHover, ReferenceWizardModalProps, ResolvedTheme, ResourceCardProps, ResourceComposePageProps, ResourceDiscoveryPageProps, ResourceErrorStateProps, ResourceGatherOptions, ResourceGenerateModalProps, ResourceGenerateModalTranslations, ResourceLoaderStateUnit, ResourceSearchModalProps, ResourceViewerPageProps, ResourceViewerPageStateUnit, RouteBuilder, SaveResourceParams$1 as SaveResourceParams, SearchModalProps, SelectionMotivation, SelectorType, SemiontProviderProps, SemiontResource$1 as SemiontResource, SessionStateUnit, ShadowToken, ShapeType, ShellStateUnit, ShellStateUnitOptions, SignInFormProps, SignUpFormProps, SimpleNavigationItem, SimpleNavigationProps, SortableResourceTabProps, SpacingToken, TagSchemasPageProps, TextSegment, TextSelection, Theme, ToastMessage, ToastType, ToolbarPanelType, ToolbarPart, ToolbarPrefs, TransitionToken, TranslationManager, TranslationProviderProps, TypographyToken, UICreateAnnotationParams, UploadProgressBarProps, UseMediaTokenResult, UseResourceContentResult, UseResourceGatherResult, UseResourceLoaderResult, WelcomePageProps, WelcomeStateUnit, WizardState };
+export { ANNOTATORS, AVAILABLE_LOCALES, AdminDevOpsPage, AdminExchangePage, AdminSecurityPage, AdminUsersPage, AnnotateToolbar, AnnotateView, AnnotationHistory, AnnotationOverlay, AnnotationProvider, AssessmentEntry, AssessmentPanel, AssistProgress, AssistSection, AssistShell, AsyncErrorBoundary, AuthErrorDisplay, BrowseView, Button, ButtonGroup, COMMON_PANELS, CodeMirrorRenderer, CollaborationPanel, CollapsibleResourceNavigation, CommentEntry, CommentsPanel, ComposeLoadingState, EntityTagsPage, EntityTypeBadges, ErrorBoundary, ExportCard, Footer, HighlightEntry, HighlightPanel, HistoryEvent, ImageAnnotateRenderer, ImageBrowseRenderer, ImageURLSchema, ImageViewer, ImportCard, ImportProgress, JsonLdPanel, JsonLdView, KeyboardShortcutsHelpModal, LeftSidebar, LinkedDataPage, LiveRegionProvider, NavigationMenu, OAuthUserSchema, ObservableLink, PageLayout, PanelHeader, PdfAnnotateRenderer, PdfBrowseRenderer, PermissionDeniedModal, PopupContainer, PopupHeader, ProtectedErrorBoundary, RESOURCE_PANELS, RecentDocumentsPage, ReferenceEntry, ReferenceResolutionWidget, ReferenceWizardModal, ReferencesPanel, ResizeHandle, ResourceAnnotationsProvider, ResourceCard, ResourceComposePage, ResourceDiscoveryPage, ResourceErrorState, ResourceGenerateModal, ResourceInfoPanel, ResourceLoadingState, ResourceSearchModal, ResourceTagsInline, ResourceViewer, ResourceViewerPage, SearchModal, SelectedTextDisplay, SemiontBranding, SemiontFavicon, SemiontProvider, SessionExpiredModal, SessionExpiryBanner, SessionTimer, SettingsPanel, SignInForm, SignUpForm, SimpleNavigation, SkipLinks, SortableResourceTab, StatisticsPanel, StatusDisplay, SvgDrawingCanvas, TagEntry, TagSchemasPage, TaggingPanel, TextAnnotateRenderer, TextBrowseRenderer, ThemeProvider, ToastContainer, ToastProvider, Toolbar, TranslationProvider, UnifiedAnnotationsPanel, UnifiedHeader, UploadProgressBar, UserMenuSkeleton, WebBrowserStorage, WelcomePage, annotatorKeyForMotivation, applyHighlights, buildSourceToRenderedMap, buildTextNodeIndex, buttonStyles, clearHighlights, createAdminSecurityStateUnit, createAdminUsersStateUnit, createComposePageStateUnit, createDiscoverStateUnit, createEntityTagsStateUnit, createExchangeStateUnit, createResourceLoaderStateUnit, createResourceViewerPageStateUnit, createSessionStateUnit, createShellStateUnit, createWelcomeStateUnit, cssVariables, defaultAnnotateRenderers, defaultBrowseRenderers, faviconPaths, formatTime, generateCSSVariables, getResourceIcon, getSelectedShapeForSelectorType, getSelectorType, getShortcutDisplay, getSupportedShapes, hideWidgetPreview, isShapeSupported, jsonLightHighlightStyle, jsonLightTheme, resolveAnnotationRanges, sanitizeImageURL, saveSelectedShapeForSelectorType, setPdfWorkerSrc, showWidgetPreview, supportsDetection, toOverlayAnnotations, tokens, useAnnotationManager, useDebounce, useDebouncedCallback, useDocumentAnnouncements, useDoubleKeyPress, useDropdown, useEventSubscription, useEventSubscriptions, useFormAnnouncements, useHoverDelay, useHoverEmitter, useIsTyping, useKBDiscovery, useKeyboardShortcuts, useLanguageChangeAnnouncements, useLineNumbers, useLiveRegion, useLoadingState, useLocalStorage, useMediaToken, useObservable, useObservableExternalNavigation, useObservableRouter, usePanelWidth, usePendingCreation, usePreloadTranslations, useResourceAnnotations, useResourceContent, useResourceGather, useResourceLoader, useResourceLoadingAnnouncements, useRovingTabIndex, useSearchAnnouncements, useSemiont, useSessionEventSubscriptions, useSessionExpiry, useSessionStateUnit, useShellStateUnit, useStateUnit, useTheme, useToast, useToolbarPrefs, useTranslations };
+export type { AdminDevOpsPageProps, AdminExchangePageProps, AdminExchangePageTranslations, AdminSecurityPageProps, AdminSecurityStateUnit, AdminUser, AdminUserStats, AdminUsersPageProps, AdminUsersStateUnit, AnnotateMediaRendererProps, AnnotateMediaRenderers, AnnotationConfig, AnnotationCreationHandler, AnnotationGroups, AnnotationHandlers, AnnotationManager, AnnotationProviderProps, AnnotationUIState, AnnotationsCollection, Annotator, AnnotatorKey, AssistProgressProps, AssistProgressTranslations, AssistShellProps, AuthErrorDisplayProps, AvailableLocale, BorderRadiusToken, BrowseMediaRenderers, ButtonGroupProps, ButtonProps, ClickAction, CloneData, CollapsibleResourceNavigationProps, ColorToken, ComposeLoadingStateProps, ComposeMode, ComposePageStateUnit, ComposeParams, CreateAnnotationParams, CreateConfig, DeleteAnnotationParams, DetectionConfig, DevOpsFeature, DiscoverStateUnit, DrawingMode, EntityTagsPageProps, EntityTagsStateUnit, ExchangeStateUnit, ExportCardProps, ExportCardTranslations, HoverEmitterProps, ImportCardProps, ImportCardTranslations, ImportPreview, ImportProgressProps, ImportProgressTranslations, KBDiscoveryOptions, KBDiscoveryResult, KeyboardShortcut, LinkComponentProps, LinkedDataPageProps, LinkedDataPageTranslations, MediaRendererProps, Motivation$7 as Motivation, NavigationItem, NavigationMenuHelper, NavigationProps, OAuthProvider, OAuthUser, ObservableLinkProps, OverlayAnnotation, PendingCreation, RecentDocumentsPageProps, ReferenceData, ReferenceHover, ReferenceWizardModalProps, ResolvedTheme, ResourceCardProps, ResourceComposePageProps, ResourceDiscoveryPageProps, ResourceErrorStateProps, ResourceGatherOptions, ResourceGenerateModalProps, ResourceGenerateModalTranslations, ResourceLoaderStateUnit, ResourceSearchModalProps, ResourceViewerPageProps, ResourceViewerPageStateUnit, RouteBuilder, SaveResourceParams$1 as SaveResourceParams, SearchModalProps, SelectionMotivation, SelectorType, SemiontProviderProps, SemiontResource$1 as SemiontResource, SessionStateUnit, ShadowToken, ShapeType, ShellStateUnit, ShellStateUnitOptions, SignInFormProps, SignUpFormProps, SimpleNavigationItem, SimpleNavigationProps, SortableResourceTabProps, SpacingToken, TagSchemasPageProps, TextSegment, TextSelection, Theme, ToastMessage, ToastType, ToolbarPanelType, ToolbarPart, ToolbarPrefs, TransitionToken, TranslationManager, TranslationProviderProps, TypographyToken, UICreateAnnotationParams, UploadProgressBarProps, UseMediaTokenResult, UseResourceContentResult, UseResourceGatherResult, UseResourceLoaderResult, WelcomePageProps, WelcomeStateUnit, WizardState };