@semiont/api-client 0.4.19 → 0.4.21

package/dist/index.d.ts

@@ -1,272 +1,57 @@
-import * as _semiont_core from '@semiont/core';
-import { BaseUrl, Logger, ResourceId, AccessToken, components, UserDID, paths, AnnotationId, GraphConnection, UpdateResourceInput, Motivation, MarkProgress, BodyOperation, GatheredContext, YieldProgress as YieldProgress$1, JobId, EventBus, Email, RefreshToken, GoogleCredential, ContentFormat, SearchQuery, CloneToken, EntityType } from '@semiont/core';
+import { components, UserDID, paths, ResourceId, AnnotationId, GraphConnection, UpdateResourceInput, Motivation, BodyOperation, GatheredContext, JobId, EventBus, AccessToken, BaseUrl, Logger, EventMap, Email, RefreshToken, GoogleCredential, ContentFormat, SearchQuery, CloneToken, EntityType, Selector } from '@semiont/core';
 export { Logger, Selector, getFragmentSelector, getSvgSelector, getTextPositionSelector, validateSvgMarkup } from '@semiont/core';
-import { Observable } from 'rxjs';
+import { Observable, BehaviorSubject, Subject } from 'rxjs';
 export { BoundingBox, ContentCache, FragmentSelector, JWTTokenSchema, LOCALES, LocaleInfo, MatchQuality, Point, SvgSelector, TextPosition, TextPositionSelector, TextQuoteSelector, ValidatedAnnotation, ValidationFailure, ValidationResult, ValidationSuccess, buildContentCache, createCircleSvg, createPolygonSvg, createRectangleSvg, decodeRepresentation, decodeWithCharset, extractBoundingBox, extractCharset, extractContext, findBestTextMatch, findTextWithContext, formatLocaleDisplay, getAllLocaleCodes, getAnnotationExactText, getBodySource, getBodyType, getChecksum, getCommentText, getCreator, getDerivedFrom, getExactText, getLanguage, getLocaleEnglishName, getLocaleInfo, getLocaleNativeName, getNodeEncoding, getPrimaryMediaType, getPrimaryRepresentation, getPrimarySelector, getResourceEntityTypes, getResourceId, getStorageUri, getTargetSelector, getTargetSource, getTextQuoteSelector, hasTargetSelector, isArchived, isAssessment, isBodyResolved, isComment, isDraft, isHighlight, isReference, isResolvedReference, isStubReference, isTag, isValidEmail, normalizeCoordinates, normalizeText, parseSvgSelector, scaleSvgToNative, validateAndCorrectOffsets, validateData, verifyPosition } from './utils/index.js';
 
-/**
- * TypeScript types for SSE event payloads.
- *
- * Progress and result types for events delivered via the long-lived
- * events-stream. These match the payloads emitted by job workers on
- * the resource-scoped EventBus. Used by the MCP server for type-safe
- * event handling.
- */
-/**
- * Progress event for reference/linking detection stream
- *
- * Sent by POST /resources/:id/annotate-references
- *
- * @example
- * ```typescript
- * stream.onProgress((progress: ReferenceDetectionProgress) => {
- *   if (progress.status === 'scanning') {
- *     console.log(`Scanning for ${progress.currentEntityType}...`);
- *     console.log(`Progress: ${progress.processedEntityTypes}/${progress.totalEntityTypes}`);
- *   }
- * });
- * ```
- */
-interface ReferenceDetectionProgress {
-    /** Current status of detection operation */
-    status: 'started' | 'scanning' | 'complete' | 'error';
-    /** Resource ID being scanned */
-    resourceId: string;
-    /** Currently scanning for this entity type (only present during 'scanning') */
-    currentEntityType?: string;
-    /** Total number of entity types to scan */
-    totalEntityTypes: number;
-    /** Number of entity types processed so far */
-    processedEntityTypes: number;
-    /** Human-readable status message */
-    message?: string;
-    /** Total entities found (only present in 'complete') */
-    foundCount?: number;
-}
-/**
- * Progress event for resource generation stream
- *
- * Sent by POST /resources/:resourceId/annotations/:annotationId/yield-resource
- *
- * @example
- * ```typescript
- * stream.onProgress((progress: YieldProgress) => {
- *   console.log(`${progress.status}: ${progress.percentage}%`);
- *   console.log(progress.message);
- * });
- * ```
- */
-interface YieldProgress {
-    /** Current stage of generation operation */
-    status: 'started' | 'fetching' | 'generating' | 'creating' | 'complete' | 'error';
-    /** Annotation ID being used as source */
-    referenceId: string;
-    /** Name of resource being generated */
-    resourceName?: string;
-    /** ID of generated resource (only present in 'complete') */
-    resourceId?: string;
-    /** ID of source resource */
-    sourceResourceId?: string;
-    /** Percentage complete (0-100) */
-    percentage: number;
-    /** Human-readable status message */
-    message?: string;
-}
-/**
- * Resource event from real-time event stream
- *
- * Sent by GET /resources/:id/events/stream
- *
- * This represents a single event from the event store, broadcast in real-time
- * as it occurs. Used for real-time collaboration - multiple users see each
- * other's changes as they happen.
- *
- * Re-exported from @semiont/core (authoritative source).
- * The discriminated union type provides type-safe event handling.
- *
- * @example
- * ```typescript
- * stream.onEvent((event) => {
- *   console.log(`Event: ${event.type}`);
- *   console.log(`User: ${event.userId}`);
- *   console.log(`Payload:`, event.payload);
- * });
- * ```
- */
-/**
- * SSE stream controller interface
- *
- * Returned by all SSE methods. Events auto-emit to EventBus (required).
- *
- * **Architecture Note**: All SSE methods require `eventBus` in options to enforce
- * event-driven architecture. This is enforced at compile time via TypeScript.
- *
- * @example
- * ```typescript
- * const eventBus = new EventBus();
- *
- * // Subscribe to events
- * eventBus.get('detection:progress').subscribe((p) => console.log(p.message));
- * eventBus.get('detection:complete').subscribe(() => console.log('Done!'));
- * eventBus.get('detection:failed').subscribe(({ error }) => console.error(error));
- *
- * // Start stream - eventBus is required (TypeScript enforced)
- * const stream = client.sse.markReferences(resourceId, request, { auth, eventBus });
- *
- * // Cleanup when done
- * stream.close();
- * ```
- */
-interface SSEStream {
-    /**
-     * Close the SSE stream and abort the connection
-     *
-     * Should be called to cleanup resources when stream is no longer needed.
-     * Safe to call multiple times.
-     *
-     * @example
-     * ```typescript
-     * // React cleanup
-     * useEffect(() => {
-     *   const stream = client.sse.markReferences(..., { auth, eventBus });
-     *   return () => stream.close();
-     * }, []);
-     * ```
-     */
-    close(): void;
+interface ViewModel {
+    dispose(): void;
 }
+declare function createDisposer(): {
+    add(vm: ViewModel | (() => void)): void;
+    dispose(): void;
+};
 
-/**
- * SSE meta event for stream connection lifecycle
- * Internal to SSE infrastructure, not part of core event protocol
- */
-declare const SSE_STREAM_CONNECTED: "stream-connected";
-type SSEStreamConnected = typeof SSE_STREAM_CONNECTED;
-/**
- * SSE Client configuration
- */
-interface SSEClientConfig {
-    baseUrl: BaseUrl;
-    logger?: Logger;
+interface BusEvent {
+    channel: string;
+    payload: Record<string, unknown>;
+    scope?: string;
 }
-/**
- * Options for SSE requests
- */
-interface SSERequestOptions {
-    auth?: AccessToken;
-    /** EventBus for event-driven architecture (required) */
-    eventBus: _semiont_core.EventBus;
+interface ActorVMOptions {
+    baseUrl: string;
+    token: string | (() => string);
+    channels: string[];
+    scope?: string;
+    reconnectMs?: number;
 }
 /**
- * SSE Client for long-lived streaming connections.
- *
- * This client has three methods — one per long-lived broadcast stream.
- * Per-operation SSE routes have been replaced by plain HTTP POSTs with
- * results delivered via the events-stream.
- *
- * Uses native fetch() instead of ky for SSE support.
- * Auth tokens are passed per-request via options.
- *
- * @example
- * ```typescript
- * const sseClient = new SSEClient({ baseUrl: 'http://localhost:4000' });
+ * Connection state exposed by the SSE bus actor.
  *
- * // Open a long-lived resource events stream (auto-reconnects on disconnect)
- * const stream = sseClient.resourceEvents(resourceId, { auth, eventBus });
+ *   initial      ─ before start() has been called
+ *   connecting   ─ fetch() in flight, no bytes yet
+ *   open         ─ SSE stream live, first byte seen
+ *   reconnecting ─ open → dropped, retrying; may be transient
+ *   degraded     ─ has been reconnecting for > DEGRADED_THRESHOLD_MS;
+ *                  UI banner threshold; distinguishes brief mount-
+ *                  churn cycles from sustained disconnection
+ *   closed       ─ stop()/dispose() called; terminal
  *
- * // Events auto-route to EventBus typed channels
- * eventBus.get('mark:body-updated').subscribe((event) => { ... });
- *
- * // Close when done
- * stream.close();
- * ```
+ * Transition rules are enforced by a helper that throws on invalid
+ * transitions — catches bugs in the reconnect loop that would
+ * otherwise strand the observable in a lying value.
  */
-declare class SSEClient {
-    private baseUrl;
-    private logger?;
-    constructor(config: SSEClientConfig);
-    /**
-     * Get common headers for SSE requests
-     */
-    private getHeaders;
-    /**
-     * Subscribe to resource events (long-lived stream)
-     *
-     * Opens a long-lived SSE connection to receive real-time events for a resource.
-     * Used for collaborative editing - see events from other users as they happen.
-     *
-     * This stream does NOT have a complete event - it stays open until explicitly closed.
-     *
-     * @param resourceId - Resource URI or ID to subscribe to
-     * @param options - Request options (auth token)
-     * @returns SSE stream controller with event callback
-     *
-     * @example
-     * ```typescript
-     * const stream = sseClient.resourceEvents(
-     *   'http://localhost:4000/resources/doc-123',
-     *   { auth: 'your-token' }
-     * );
-     *
-     * stream.onProgress((event) => {
-     *   console.log(`Event: ${event.type}`);
-     *   console.log(`User: ${event.userId}`);
-     *   console.log(`Sequence: ${event.metadata.sequenceNumber}`);
-     *   console.log(`Payload:`, event.payload);
-     * });
-     *
-     * stream.onError((error) => {
-     *   console.error('Stream error:', error.message);
-     * });
-     *
-     * // Close when no longer needed (e.g., component unmount)
-     * stream.close();
-     * ```
-     */
-    resourceEvents(resourceId: ResourceId, options: SSERequestOptions & {
-        onConnected?: () => void;
-    }): SSEStream;
-    /**
-     * Subscribe to global system events (long-lived stream)
-     *
-     * Opens a long-lived SSE connection to receive system-level domain events
-     * (entity type additions, etc.) that are not scoped to a specific resource.
-     *
-     * @param options - Request options (auth token, eventBus)
-     * @returns SSE stream controller
-     *
-     * @example
-     * ```typescript
-     * const stream = sseClient.globalEvents({ auth: 'your-token', eventBus });
-     *
-     * // Events auto-emit to EventBus typed channels — subscribe there
-     * eventBus.get('mark:entity-type-added').subscribe((stored) => {
-     *   // Invalidate entity types query
-     * });
-     *
-     * // Close when no longer needed
-     * stream.close();
-     * ```
-     */
-    globalEvents(options: SSERequestOptions & {
-        onConnected?: () => void;
-    }): SSEStream;
-    /**
-     * Subscribe to participant attention stream (long-lived stream)
-     *
-     * Opens a participant-scoped SSE connection to receive cross-participant
-     * beckon signals. Signals are delivered as 'beckon:focus' events routed
-     * to the EventBus — the existing scroll/highlight machinery handles them.
-     *
-     * Signals are ephemeral — delivered if connected, dropped if not.
-     *
-     * @param options - Request options (auth token, eventBus)
-     * @returns SSE stream controller
-     */
-    attentionStream(options: SSERequestOptions & {
-        onConnected?: () => void;
-    }): SSEStream;
+type ConnectionState = 'initial' | 'connecting' | 'open' | 'reconnecting' | 'degraded' | 'closed';
+/** Time in the `reconnecting` state before transitioning to `degraded`. */
+declare const DEGRADED_THRESHOLD_MS = 3000;
+interface ActorVM extends ViewModel {
+    on$<T = Record<string, unknown>>(channel: string): Observable<T>;
+    emit(channel: string, payload: Record<string, unknown>, emitScope?: string): Promise<void>;
+    state$: Observable<ConnectionState>;
+    addChannels(channels: string[], scope?: string): void;
+    removeChannels(channels: string[]): void;
+    start(): void;
+    stop(): void;
 }
+declare function createActorVM(options: ActorVMOptions): ActorVM;
 
 /**
  * Verb Namespace Interfaces
@@ -280,19 +65,20 @@ declare class SSEClient {
  * proxy handles HTTP, auth, SSE, and caching internally.
  *
  * Return type conventions:
- * - Browse live queries → Observable (events-stream driven, cached)
+ * - Browse live queries → Observable (bus gateway driven, cached)
  * - Browse one-shot reads → Promise (fetch once, no cache)
  * - Commands (mark, bind, yield.resource) → Promise (fire-and-forget)
  * - Long-running ops (gather, match, yield.fromAnnotation, mark.assist) → Observable (progress + result)
  * - Ephemeral signals (beckon) → void
  */
 
-type Annotation$1 = components['schemas']['Annotation'];
-type ResourceDescriptor$2 = components['schemas']['ResourceDescriptor'];
-type StoredEventResponse$1 = components['schemas']['StoredEventResponse'];
+type Annotation$2 = components['schemas']['Annotation'];
+type ResourceDescriptor$5 = components['schemas']['ResourceDescriptor'];
+type StoredEventResponse$2 = components['schemas']['StoredEventResponse'];
 type GatherProgress = components['schemas']['GatherProgress'];
 type MatchSearchResult = components['schemas']['MatchSearchResult'];
-type MarkAssistFinished = components['schemas']['MarkAssistFinished'];
+type JobProgress$2 = components['schemas']['JobProgress'];
+type YieldProgress$1 = JobProgress$2;
 type GatherAnnotationComplete = components['schemas']['GatherAnnotationComplete'];
 type JobStatusResponse$1 = components['schemas']['JobStatusResponse'];
 type AuthResponse$1 = components['schemas']['AuthResponse'];
@@ -314,6 +100,14 @@ type ResponseContent$1<T> = T extends {
             };
         };
     };
+} ? R : T extends {
+    responses: {
+        202: {
+            content: {
+                'application/json': infer R;
+            };
+        };
+    };
 } ? R : never;
 type RequestContent$1<T> = T extends {
     requestBody?: {
@@ -323,7 +117,7 @@ type RequestContent$1<T> = T extends {
     };
 } ? R : never;
 /** Input for creating an annotation via mark.annotation() */
-type CreateAnnotationInput = RequestContent$1<paths['/resources/{id}/annotations']['post']>;
+type CreateAnnotationInput = components['schemas']['CreateAnnotationRequest'];
 /** Input for creating a resource via yield.resource() */
 interface CreateResourceInput {
     name: string;
@@ -335,6 +129,11 @@ interface CreateResourceInput {
     sourceAnnotationId?: string;
     sourceResourceId?: string;
     storageUri: string;
+    /** Prompt that drove AI generation (for AI-generated resources). */
+    generationPrompt?: string;
+    /** Agent(s) that generated the content (for AI-generated resources). */
+    generator?: components['schemas']['Agent'] | components['schemas']['Agent'][];
+    isDraft?: boolean;
 }
 /** Options for yield.fromAnnotation() */
 interface GenerationOptions {
@@ -358,11 +157,16 @@ interface MarkAssistOptions {
     categories?: string[];
 }
 /** Options for yield.createFromToken() */
-type CreateFromTokenOptions = RequestContent$1<paths['/api/clone-tokens/create-resource']['post']>;
+type CreateFromTokenOptions = {
+    token: string;
+    name: string;
+    content: string;
+    archiveOriginal?: boolean;
+};
 /** Referenced-by entry from browse.referencedBy() */
-type ReferencedByEntry = ResponseContent$1<paths['/resources/{id}/referenced-by']['get']>['referencedBy'][number];
+type ReferencedByEntry = components['schemas']['GetReferencedByResponse']['referencedBy'][number];
 /** Annotation history from browse.annotationHistory() */
-type AnnotationHistoryResponse = ResponseContent$1<paths['/resources/{resourceId}/annotations/{annotationId}/history']['get']>;
+type AnnotationHistoryResponse = components['schemas']['GetAnnotationHistoryResponse'];
 /** User object from auth/admin responses */
 type User = AuthResponse$1['user'];
 /**
@@ -377,30 +181,31 @@ type GatherAnnotationProgress = GatherProgress | GatherAnnotationComplete;
 type MatchSearchProgress = MatchSearchResult;
 /**
  * Progress emitted by mark.assist() Observable.
- * Emits MarkProgress during scanning, then MarkAssistFinished on completion.
- * On failure, the Observable errors with MarkAssistFailed.
+ * Each emission is a JobProgress snapshot (unified job lifecycle). The
+ * Observable completes on `job:complete`; errors on `job:fail`.
  */
-type MarkAssistProgress = MarkProgress | MarkAssistFinished;
+type MarkAssistProgress = JobProgress$2;
 /**
  * Browse — reads from materialized views
  *
  * Live queries return Observables that emit initial state and re-emit
- * on events-stream updates. One-shot reads return Promises.
+ * on bus gateway updates. One-shot reads return Promises.
  *
  * Backend actor: Browser (context classes)
  * Event prefix: browse:*
  */
 interface BrowseNamespace$1 {
-    resource(resourceId: ResourceId): Observable<ResourceDescriptor$2 | undefined>;
+    resource(resourceId: ResourceId): Observable<ResourceDescriptor$5 | undefined>;
     resources(filters?: {
         limit?: number;
         archived?: boolean;
         search?: string;
-    }): Observable<ResourceDescriptor$2[] | undefined>;
-    annotations(resourceId: ResourceId): Observable<Annotation$1[] | undefined>;
-    annotation(resourceId: ResourceId, annotationId: AnnotationId): Observable<Annotation$1 | undefined>;
+    }): Observable<ResourceDescriptor$5[] | undefined>;
+    annotations(resourceId: ResourceId): Observable<Annotation$2[] | undefined>;
+    annotation(resourceId: ResourceId, annotationId: AnnotationId): Observable<Annotation$2 | undefined>;
     entityTypes(): Observable<string[] | undefined>;
     referencedBy(resourceId: ResourceId): Observable<ReferencedByEntry[] | undefined>;
+    events(resourceId: ResourceId): Observable<StoredEventResponse$2[] | undefined>;
     resourceContent(resourceId: ResourceId): Promise<string>;
     resourceRepresentation(resourceId: ResourceId, options?: {
         accept?: string;
@@ -414,18 +219,18 @@ interface BrowseNamespace$1 {
         stream: ReadableStream<Uint8Array>;
         contentType: string;
     }>;
-    resourceEvents(resourceId: ResourceId): Promise<StoredEventResponse$1[]>;
+    resourceEvents(resourceId: ResourceId): Promise<StoredEventResponse$2[]>;
     annotationHistory(resourceId: ResourceId, annotationId: AnnotationId): Promise<AnnotationHistoryResponse>;
     connections(resourceId: ResourceId): Promise<GraphConnection[]>;
-    backlinks(resourceId: ResourceId): Promise<Annotation$1[]>;
-    resourcesByName(query: string, limit?: number): Promise<ResourceDescriptor$2[]>;
-    files(dirPath?: string, sort?: 'name' | 'mtime' | 'annotationCount'): Promise<ResponseContent$1<paths['/api/browse/files']['get']>>;
+    backlinks(resourceId: ResourceId): Promise<Annotation$2[]>;
+    resourcesByName(query: string, limit?: number): Promise<ResourceDescriptor$5[]>;
+    files(dirPath?: string, sort?: 'name' | 'mtime' | 'annotationCount'): Promise<components['schemas']['BrowseFilesResponse']>;
 }
 /**
  * Mark — annotation CRUD, entity types, AI assist
  *
  * Commands return Promises that resolve on HTTP acceptance (202).
- * Results appear on browse Observables via events-stream.
+ * Results appear on browse Observables via bus gateway.
  * assist() returns an Observable for long-running progress.
  *
  * Backend actor: Stower
@@ -506,7 +311,7 @@ interface YieldNamespace$1 {
         token: string;
         expiresAt: string;
     }>;
-    fromToken(token: string): Promise<ResourceDescriptor$2>;
+    fromToken(token: string): Promise<ResourceDescriptor$5>;
     createFromToken(options: CreateFromTokenOptions): Promise<{
         resourceId: string;
     }>;
@@ -586,53 +391,55 @@ interface AdminNamespace$1 {
     }>;
 }
 
-/**
- * BrowseNamespace — reads from materialized views
- *
- * Absorbs AnnotationStore and ResourceStore logic. Live queries return
- * Observables backed by BehaviorSubjects that update reactively when
- * EventBus events arrive. One-shot reads are Promise wrappers over HTTP.
- *
- * Backend actor: Browser (context classes)
- * Event prefix: browse:*
- */
-
-type Annotation = components['schemas']['Annotation'];
-type ResourceDescriptor$1 = components['schemas']['ResourceDescriptor'];
-type StoredEventResponse = components['schemas']['StoredEventResponse'];
-type TokenGetter$9 = () => AccessToken | undefined;
+type Annotation$1 = components['schemas']['Annotation'];
+type ResourceDescriptor$4 = components['schemas']['ResourceDescriptor'];
+type StoredEventResponse$1 = components['schemas']['StoredEventResponse'];
+type TokenGetter$4 = () => AccessToken | undefined;
+type ResourceListFilters = {
+    limit?: number;
+    archived?: boolean;
+    search?: string;
+};
 declare class BrowseNamespace implements BrowseNamespace$1 {
     private readonly http;
     private readonly eventBus;
-    private readonly annotationList$;
-    private readonly fetchingAnnotationList;
-    private readonly annotationListObs$;
-    private readonly annotationDetail$;
-    private readonly fetchingAnnotationDetail;
-    private readonly annotationDetailObs$;
-    private readonly resourceDetail$;
-    private readonly fetchingResourceDetail;
-    private readonly resourceDetailObs$;
-    private readonly resourceList$;
-    private readonly fetchingResourceList;
-    private readonly resourceListObs$;
-    private readonly entityTypes$;
-    private fetchingEntityTypes;
-    private readonly referencedBy$;
-    private readonly fetchingReferencedBy;
-    private readonly referencedByObs$;
+    private readonly resourceCache;
+    private readonly resourceListCache;
+    private readonly annotationListCache;
+    /**
+     * Annotation-detail cache keyed by `annotationId` only — the resourceId
+     * is a routing hint for the backend fetch, not an identity component.
+     * We track the most recent resourceId per annotationId in a side-map
+     * so `mark:delete-ok` (which carries only `annotationId`) can reach
+     * the right cache entry. Aligns with the pre-refactor semantics.
+     */
+    private readonly annotationDetailCache;
+    private readonly annotationResources;
+    private readonly entityTypesCache;
+    private readonly referencedByCache;
+    private readonly resourceEventsCache;
+    /** Filter-blob memory so `invalidateResourceLists` can replay per-key. */
+    private readonly resourceListFilters;
+    /**
+     * Per-key memo for `annotations()` observables. The cache stores the
+     * full `AnnotationsListResponse`; the public shape is just the inner
+     * `Annotation[]`. Without this memo, every call to `annotations(rId)`
+     * would produce a fresh `.pipe(map(...))` observable, violating B4
+     * (per-key observable stability). Consumers that compare observable
+     * identity — React hooks depending on the observable reference,
+     * `distinctUntilChanged` at a higher level — would misbehave.
+     */
+    private readonly annotationListObs;
     private readonly getToken;
-    constructor(http: SemiontApiClient, eventBus: EventBus, getToken: TokenGetter$9);
-    resource(resourceId: ResourceId): Observable<ResourceDescriptor$1 | undefined>;
-    resources(filters?: {
-        limit?: number;
-        archived?: boolean;
-        search?: string;
-    }): Observable<ResourceDescriptor$1[] | undefined>;
-    annotations(resourceId: ResourceId): Observable<Annotation[] | undefined>;
-    annotation(resourceId: ResourceId, annotationId: AnnotationId): Observable<Annotation | undefined>;
+    private readonly actor;
+    constructor(http: SemiontApiClient, eventBus: EventBus, getToken: TokenGetter$4, actor: ActorVM);
+    resource(resourceId: ResourceId): Observable<ResourceDescriptor$4 | undefined>;
+    resources(filters?: ResourceListFilters): Observable<ResourceDescriptor$4[] | undefined>;
+    annotations(resourceId: ResourceId): Observable<Annotation$1[] | undefined>;
+    annotation(resourceId: ResourceId, annotationId: AnnotationId): Observable<Annotation$1 | undefined>;
     entityTypes(): Observable<string[] | undefined>;
     referencedBy(resourceId: ResourceId): Observable<ReferencedByEntry[] | undefined>;
+    events(resourceId: ResourceId): Observable<StoredEventResponse$1[] | undefined>;
     resourceContent(resourceId: ResourceId): Promise<string>;
     resourceRepresentation(resourceId: ResourceId, options?: {
         accept?: string;
@@ -646,45 +453,56 @@ declare class BrowseNamespace implements BrowseNamespace$1 {
         stream: ReadableStream<Uint8Array>;
         contentType: string;
     }>;
-    resourceEvents(resourceId: ResourceId): Promise<StoredEventResponse[]>;
+    resourceEvents(resourceId: ResourceId): Promise<StoredEventResponse$1[]>;
     annotationHistory(resourceId: ResourceId, annotationId: AnnotationId): Promise<AnnotationHistoryResponse>;
     connections(_resourceId: ResourceId): Promise<GraphConnection[]>;
-    backlinks(_resourceId: ResourceId): Promise<Annotation[]>;
-    resourcesByName(_query: string, _limit?: number): Promise<ResourceDescriptor$1[]>;
-    files(dirPath?: string, sort?: 'name' | 'mtime' | 'annotationCount'): Promise<ResponseContent$1<paths['/api/browse/files']['get']>>;
+    backlinks(_resourceId: ResourceId): Promise<Annotation$1[]>;
+    resourcesByName(_query: string, _limit?: number): Promise<ResourceDescriptor$4[]>;
+    files(dirPath?: string, sort?: 'name' | 'mtime' | 'annotationCount'): Promise<components['schemas']['BrowseFilesResponse']>;
     invalidateAnnotationList(resourceId: ResourceId): void;
-    invalidateAnnotationDetail(annotationId: AnnotationId): void;
+    removeAnnotationDetail(annotationId: AnnotationId): void;
     invalidateResourceDetail(id: ResourceId): void;
     invalidateResourceLists(): void;
     invalidateEntityTypes(): void;
     invalidateReferencedBy(resourceId: ResourceId): void;
-    updateAnnotationInPlace(resourceId: ResourceId, annotation: Annotation): void;
+    invalidateResourceEvents(resourceId: ResourceId): void;
+    updateAnnotationInPlace(resourceId: ResourceId, annotation: Annotation$1): void;
+    /**
+     * Typed shorthand for `eventBus.get(channel).subscribe(handler)`.
+     * Preserves per-channel payload typing so handlers read
+     * `EventMap[K]` without any casts.
+     */
+    private on;
+    /**
+     * Handler shared by `mark:entity-tag-added` and `mark:entity-tag-removed`.
+     * Both events carry the same effect: the annotation list, the
+     * resource descriptor, and the event log for that resource all may
+     * now reflect different entity tagging, so invalidate all three.
+     */
+    private onEntityTagChanged;
+    /**
+     * Handler shared by `mark:archived` and `mark:unarchived`. Both
+     * change a resource's archived flag, which is stored on the resource
+     * descriptor and affects the resource-list filter.
+     */
+    private onArchiveToggled;
+    /**
+     * Handler shared by `yield:create-ok` and `yield:update-ok`. Both
+     * report a resource mutation with the resourceId as a string (not
+     * yet branded), so we brand and apply the same effect as
+     * `onArchiveToggled`.
+     */
+    private onYieldResourceMutated;
     private subscribeToEvents;
-    private fetchAnnotationList;
-    private fetchAnnotationDetail;
-    private fetchResourceDetail;
-    private fetchResourceList;
-    private fetchEntityTypes;
-    private fetchReferencedBy;
 }
 
-/**
- * MarkNamespace — annotation CRUD, entity types, AI assist
- *
- * Commands return Promises that resolve on HTTP acceptance.
- * Results appear on browse Observables via events-stream.
- * assist() returns an Observable for long-running progress.
- *
- * Backend actor: Stower
- * Event prefix: mark:*
- */
-
-type TokenGetter$8 = () => AccessToken | undefined;
+type TokenGetter$3 = () => AccessToken | undefined;
 declare class MarkNamespace implements MarkNamespace$1 {
     private readonly http;
     private readonly eventBus;
     private readonly getToken;
-    constructor(http: SemiontApiClient, eventBus: EventBus, getToken: TokenGetter$8);
+    private readonly actor;
+    constructor(http: SemiontApiClient, eventBus: EventBus, getToken: TokenGetter$3, actor: ActorVM);
     annotation(resourceId: ResourceId, input: CreateAnnotationInput): Promise<{
         annotationId: string;
     }>;
@@ -698,41 +516,16 @@ declare class MarkNamespace implements MarkNamespace$1 {
     private dispatchAssist;
 }
 
-/**
- * BindNamespace — reference linking
- *
- * The simplest namespace. One method. The result (updated annotation
- * with resolved reference) arrives on browse.annotations() via the
- * enriched mark:body-updated event.
- *
- * Backend actor: Stower (via mark:update-body)
- * Event prefix: mark:body-updated (shares mark event pipeline)
- */
-
-type TokenGetter$7 = () => AccessToken | undefined;
 declare class BindNamespace implements BindNamespace$1 {
-    private readonly http;
-    private readonly getToken;
-    constructor(http: SemiontApiClient, getToken: TokenGetter$7);
+    private readonly actor;
+    constructor(actor: ActorVM);
     body(resourceId: ResourceId, annotationId: AnnotationId, operations: BodyOperation[]): Promise<void>;
 }
 
-/**
- * GatherNamespace — context assembly
- *
- * Long-running (LLM calls + graph traversal). Returns Observables
- * that emit progress then the gathered context.
- *
- * Backend actor: Gatherer
- * Event prefix: gather:*
- */
-
-type TokenGetter$6 = () => AccessToken | undefined;
 declare class GatherNamespace implements GatherNamespace$1 {
-    private readonly http;
     private readonly eventBus;
-    private readonly getToken;
-    constructor(http: SemiontApiClient, eventBus: EventBus, getToken: TokenGetter$6);
+    private readonly actor;
+    constructor(eventBus: EventBus, actor: ActorVM);
     annotation(annotationId: AnnotationId, resourceId: ResourceId, options?: {
         contextWindow?: number;
     }): Observable<GatherAnnotationProgress>;
@@ -741,87 +534,50 @@ declare class GatherNamespace implements GatherNamespace$1 {
     }): Observable<GatherAnnotationProgress>;
 }
 
-/**
- * MatchNamespace — search and ranking
- *
- * Long-running (semantic search, optional LLM scoring). Returns
- * Observable with results.
- *
- * Backend actor: Matcher
- * Event prefix: match:*
- */
-
-type TokenGetter$5 = () => AccessToken | undefined;
 declare class MatchNamespace implements MatchNamespace$1 {
-    private readonly http;
     private readonly eventBus;
-    private readonly getToken;
-    constructor(http: SemiontApiClient, eventBus: EventBus, getToken: TokenGetter$5);
+    private readonly actor;
+    constructor(eventBus: EventBus, actor: ActorVM);
     search(resourceId: ResourceId, referenceId: string, context: GatheredContext, options?: {
         limit?: number;
         useSemanticScoring?: boolean;
     }): Observable<MatchSearchProgress>;
 }
 
-/**
- * YieldNamespace — resource creation
- *
- * resource() is synchronous file upload (Promise).
- * fromAnnotation() is long-running LLM generation (Observable).
- *
- * Backend actor: Stower + generation worker
- * Event prefix: yield:*
- */
+type YieldProgress = components['schemas']['JobProgress'];
 
-type ResourceDescriptor = components['schemas']['ResourceDescriptor'];
-type TokenGetter$4 = () => AccessToken | undefined;
+type ResourceDescriptor$3 = components['schemas']['ResourceDescriptor'];
+type TokenGetter$2 = () => AccessToken | undefined;
 declare class YieldNamespace implements YieldNamespace$1 {
     private readonly http;
     private readonly eventBus;
     private readonly getToken;
-    constructor(http: SemiontApiClient, eventBus: EventBus, getToken: TokenGetter$4);
+    private readonly actor;
+    constructor(http: SemiontApiClient, eventBus: EventBus, getToken: TokenGetter$2, actor: ActorVM);
     resource(data: CreateResourceInput): Promise<{
         resourceId: string;
     }>;
-    fromAnnotation(resourceId: ResourceId, annotationId: AnnotationId, options: GenerationOptions): Observable<YieldProgress$1>;
+    fromAnnotation(resourceId: ResourceId, annotationId: AnnotationId, options: GenerationOptions): Observable<YieldProgress>;
     cloneToken(resourceId: ResourceId): Promise<{
         token: string;
         expiresAt: string;
     }>;
-    fromToken(token: string): Promise<ResourceDescriptor>;
+    fromToken(token: string): Promise<ResourceDescriptor$3>;
     createFromToken(options: CreateFromTokenOptions): Promise<{
         resourceId: string;
     }>;
 }
 
-/**
- * BeckonNamespace — attention coordination
- *
- * Fire-and-forget. Ephemeral presence signal delivered via the
- * attention-stream to other participants.
- *
- * Backend actor: (frontend relay via attention-stream)
- * Event prefix: beckon:*
- */
-
-type TokenGetter$3 = () => AccessToken | undefined;
 declare class BeckonNamespace implements BeckonNamespace$1 {
-    private readonly http;
-    private readonly getToken;
-    constructor(http: SemiontApiClient, getToken: TokenGetter$3);
+    private readonly actor;
+    constructor(actor: ActorVM);
     attention(annotationId: AnnotationId, resourceId: ResourceId): void;
 }
 
-/**
- * JobNamespace — worker lifecycle
- */
-
 type JobStatusResponse = components['schemas']['JobStatusResponse'];
-type TokenGetter$2 = () => AccessToken | undefined;
 declare class JobNamespace implements JobNamespace$1 {
-    private readonly http;
-    private readonly getToken;
-    constructor(http: SemiontApiClient, getToken: TokenGetter$2);
+    private readonly actor;
+    constructor(actor: ActorVM);
     status(jobId: JobId): Promise<JobStatusResponse>;
     pollUntilComplete(jobId: JobId, options?: {
         interval?: number;
@@ -923,6 +679,14 @@ type ResponseContent<T> = T extends {
             };
         };
     };
+} ? R : T extends {
+    responses: {
+        202: {
+            content: {
+                'application/json': infer R;
+            };
+        };
+    };
 } ? R : never;
 type RequestContent<T> = T extends {
     requestBody?: {
@@ -944,27 +708,24 @@ declare class APIError extends Error {
  * 401 propagates as an APIError.
  *
  * Implementations must dedupe concurrent calls so that simultaneous 401s
- * don't fire multiple parallel refresh requests. The frontend's
- * KnowledgeBaseSessionProvider provides this via an in-flight Promise map
- * keyed by KB id.
+ * don't fire multiple parallel refresh requests. `SemiontSession.refresh()`
+ * satisfies this via an in-flight Promise map keyed by KB id.
  */
 type TokenRefresher = () => Promise<string | null>;
 interface SemiontApiClientConfig {
     baseUrl: BaseUrl;
-    /** Per-workspace EventBus. Required — one bus per workspace, constructed externally. */
-    eventBus: EventBus;
+    /**
+     * Observable access token. All auth (HTTP + bus) reads the current value.
+     * Update by calling `.next(newToken)` on the BehaviorSubject. The bus actor
+     * auto-starts when the value transitions from null to a real token.
+     * If omitted, the client operates unauthenticated (public endpoints only).
+     */
+    token$?: BehaviorSubject<AccessToken | null>;
     timeout?: number;
     retry?: number;
     logger?: Logger;
     /** Optional 401-recovery hook. See {@link TokenRefresher}. */
     tokenRefresher?: TokenRefresher;
-    /**
-     * Token getter for the verb-namespace API (client.browse, client.mark, etc.).
-     * When provided, auth is managed internally — no per-call auth needed.
-     * The getter is called on each request to get the current token.
-     * If not provided, namespace methods use undefined auth (public endpoints only).
-     */
-    getToken?: () => AccessToken | undefined;
 }
 /**
  * Options for individual API requests
@@ -982,21 +743,18 @@ interface RequestOptions {
 declare class SemiontApiClient {
     private http;
     readonly baseUrl: BaseUrl;
-    /** The workspace-scoped EventBus this client was constructed with. */
-    readonly eventBus: EventBus;
-    private logger?;
     /**
-     * Shared mutable token getter. All verb namespaces read from this.
-     * Updated via setTokenGetter() from the React auth layer.
+     * Workspace-scoped EventBus — owned by the client, constructed
+     * internally, never accepted from config. Private: all bus access
+     * goes through `client.emit` / `client.on` / `client.stream`.
      */
-    private _getToken;
+    private readonly eventBus;
+    private logger?;
     /**
-     * SSE streaming client for real-time operations
-     *
-     * Separate from the main HTTP client to clearly mark streaming endpoints.
-     * Uses native fetch() instead of ky for SSE support.
+     * Observable token source. All auth reads from this.
      */
-    readonly sse: SSEClient;
+    private readonly token$;
+    private _actor;
     readonly browse: BrowseNamespace;
     readonly mark: MarkNamespace;
     readonly bind: BindNamespace;
@@ -1008,12 +766,41 @@ declare class SemiontApiClient {
     readonly auth: AuthNamespace;
     readonly admin: AdminNamespace;
     constructor(config: SemiontApiClientConfig);
+    private _actorStarted;
+    get actor(): ActorVM;
+    private activeResource;
     /**
-     * Update the token getter for all verb namespaces.
-     * Called from the React auth layer when the token changes.
-     * All namespaces share this getter via closure — no per-namespace sync needed.
+     * Subscribe the bus actor to the resource-scoped SSE stream for a single
+     * resource and bridge incoming scoped events into the workspace event bus.
+     *
+     * **One distinct scope at a time**: the client supports subscriptions
+     * to a single resource scope concurrently. Multiple calls with the
+     * **same** resourceId are ref-counted — each returns an independent
+     * unsubscribe; the underlying SSE scope is torn down only when the
+     * last unsubscribe fires. Calling with a **different** resourceId
+     * while a subscription is live throws. Widening this to multiple
+     * concurrent scopes is deferred until a product requirement (e.g.
+     * split-pane viewer, headless fleet-watcher) forces the design.
+     *
+     * @returns a disposer that decrements the ref count (and tears down
+     *          the SSE scope + bridges when it reaches zero).
+     */
+    subscribeToResource(resourceId: ResourceId): () => void;
+    private makeUnsubscriber;
+    dispose(): void;
+    /** Emit an event on the internal bus. */
+    emit<K extends keyof EventMap>(channel: K, payload: EventMap[K]): void;
+    /** Subscribe to an event on the internal bus; returns unsubscribe. */
+    on<K extends keyof EventMap>(channel: K, handler: (payload: EventMap[K]) => void): () => void;
+    /** Read-only observable for a bus channel. Consumers `.pipe(...)` over this. */
+    stream<K extends keyof EventMap>(channel: K): Observable<EventMap[K]>;
+    /**
+     * Build the `Authorization: Bearer <token>` header. If the caller passed
+     * an explicit `{ auth }` it wins (used by session-internal throwaway
+     * clients that need to run a validation request with a specific token).
+     * Otherwise the current value of `this.token$` is used, so external
+     * callers never have to plumb the token themselves.
      */
-    setTokenGetter(getter: () => AccessToken | undefined): void;
     private authHeaders;
     authenticatePassword(email: Email, password: string, options?: RequestOptions): Promise<ResponseContent<paths['/api/tokens/password']['post']>>;
     refreshToken(token: RefreshToken, options?: RequestOptions): Promise<ResponseContent<paths['/api/tokens/refresh']['post']>>;
@@ -1037,6 +824,8 @@ declare class SemiontApiClient {
      * @param data.creationMethod - Optional creation method
      * @param data.sourceAnnotationId - Optional source annotation ID
      * @param data.sourceResourceId - Optional source resource ID
+     * @param data.generationPrompt - Optional prompt that drove AI generation
+     * @param data.generator - Optional Agent(s) that generated the content
      * @param options - Request options including auth
      */
     yieldResource(data: {
@@ -1049,10 +838,11 @@ declare class SemiontApiClient {
         sourceAnnotationId?: string;
         sourceResourceId?: string;
         storageUri: string;
-    }, options?: RequestOptions): Promise<{
-        resourceId: string;
-    }>;
-    browseResource(id: ResourceId, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{id}']['get']>>;
+        generationPrompt?: string;
+        generator?: components['schemas']['Agent'] | components['schemas']['Agent'][];
+        isDraft?: boolean;
+    }, options?: RequestOptions): Promise<ResponseContent<paths['/resources']['post']>>;
+    browseResource(id: ResourceId, _options?: RequestOptions): Promise<components['schemas']['GetResourceResponse']>;
     /**
      * Get resource representation using W3C content negotiation
      * Returns raw binary content (images, PDFs, text, etc.) with content type
@@ -1125,39 +915,47 @@ declare class SemiontApiClient {
         stream: ReadableStream<Uint8Array>;
         contentType: string;
     }>;
-    browseResources(limit?: number, archived?: boolean, query?: SearchQuery, options?: RequestOptions): Promise<ResponseContent<paths['/resources']['get']>>;
-    updateResource(id: ResourceId, data: RequestContent<paths['/resources/{id}']['patch']>, options?: RequestOptions): Promise<void>;
-    getResourceEvents(id: ResourceId, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{id}/events']['get']>>;
-    browseReferences(id: ResourceId, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{id}/referenced-by']['get']>>;
-    generateCloneToken(id: ResourceId, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{id}/clone-with-token']['post']>>;
-    getResourceByToken(token: CloneToken, options?: RequestOptions): Promise<ResponseContent<paths['/api/clone-tokens/{token}']['get']>>;
-    createResourceFromToken(data: RequestContent<paths['/api/clone-tokens/create-resource']['post']>, options?: RequestOptions): Promise<{
+    browseResources(limit?: number, archived?: boolean, query?: SearchQuery, _options?: RequestOptions): Promise<components['schemas']['ListResourcesResponse']>;
+    updateResource(id: ResourceId, data: {
+        archived?: boolean;
+        entityTypes?: string[];
+    }, options?: RequestOptions): Promise<void>;
+    getResourceEvents(id: ResourceId, _options?: RequestOptions): Promise<components['schemas']['GetEventsResponse']>;
+    browseReferences(id: ResourceId, _options?: RequestOptions): Promise<components['schemas']['GetReferencedByResponse']>;
+    generateCloneToken(id: ResourceId, _options?: RequestOptions): Promise<components['schemas']['CloneResourceWithTokenResponse']>;
+    getResourceByToken(token: CloneToken, _options?: RequestOptions): Promise<components['schemas']['GetResourceByTokenResponse']>;
+    createResourceFromToken(data: {
+        token: string;
+        name: string;
+        content: string;
+        archiveOriginal?: boolean;
+    }, _options?: RequestOptions): Promise<{
         resourceId: string;
     }>;
-    markAnnotation(id: ResourceId, data: RequestContent<paths['/resources/{id}/annotations']['post']>, options?: RequestOptions): Promise<{
+    markAnnotation(id: ResourceId, data: components['schemas']['CreateAnnotationRequest'], _options?: RequestOptions): Promise<{
         annotationId: string;
     }>;
-    getAnnotation(id: AnnotationId, options?: RequestOptions): Promise<ResponseContent<paths['/annotations/{id}']['get']>>;
-    browseAnnotation(resourceId: ResourceId, annotationId: AnnotationId, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{resourceId}/annotations/{annotationId}']['get']>>;
-    browseAnnotations(id: ResourceId, motivation?: Motivation, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{id}/annotations']['get']>>;
-    deleteAnnotation(resourceId: ResourceId, annotationId: AnnotationId, options?: RequestOptions): Promise<void>;
+    getAnnotation(id: AnnotationId, _options?: RequestOptions): Promise<components['schemas']['GetAnnotationResponse']>;
+    browseAnnotation(resourceId: ResourceId, annotationId: AnnotationId, _options?: RequestOptions): Promise<components['schemas']['GetAnnotationResponse']>;
+    browseAnnotations(id: ResourceId, _motivation?: Motivation, _options?: RequestOptions): Promise<components['schemas']['GetAnnotationsResponse']>;
+    deleteAnnotation(resourceId: ResourceId, annotationId: AnnotationId, _options?: RequestOptions): Promise<void>;
     bindAnnotation(resourceId: ResourceId, annotationId: AnnotationId, data: {
         operations: BodyOperation[];
-    }, options?: RequestOptions): Promise<{
+    }, _options?: RequestOptions): Promise<{
         correlationId: string;
     }>;
-    getAnnotationHistory(resourceId: ResourceId, annotationId: AnnotationId, options?: RequestOptions): Promise<ResponseContent<paths['/resources/{resourceId}/annotations/{annotationId}/history']['get']>>;
+    getAnnotationHistory(resourceId: ResourceId, annotationId: AnnotationId, _options?: RequestOptions): Promise<components['schemas']['GetAnnotationHistoryResponse']>;
     annotateReferences(resourceId: ResourceId, data: {
         entityTypes: string[];
         includeDescriptiveReferences?: boolean;
-    }, options?: RequestOptions): Promise<{
+    }, _options?: RequestOptions): Promise<{
         correlationId: string;
         jobId: string;
     }>;
     annotateHighlights(resourceId: ResourceId, data: {
         instructions?: string;
         density?: number;
-    }, options?: RequestOptions): Promise<{
+    }, _options?: RequestOptions): Promise<{
         correlationId: string;
         jobId: string;
     }>;
@@ -1166,7 +964,7 @@ declare class SemiontApiClient {
         tone?: string;
         density?: number;
         language?: string;
-    }, options?: RequestOptions): Promise<{
+    }, _options?: RequestOptions): Promise<{
         correlationId: string;
         jobId: string;
     }>;
@@ -1175,14 +973,14 @@ declare class SemiontApiClient {
         tone?: string;
         density?: number;
         language?: string;
-    }, options?: RequestOptions): Promise<{
+    }, _options?: RequestOptions): Promise<{
         correlationId: string;
         jobId: string;
     }>;
     annotateTags(resourceId: ResourceId, data: {
         schemaId: string;
         categories: string[];
-    }, options?: RequestOptions): Promise<{
+    }, _options?: RequestOptions): Promise<{
         correlationId: string;
         jobId: string;
     }>;
@@ -1194,14 +992,14 @@ declare class SemiontApiClient {
         language?: string;
         temperature?: number;
         maxTokens?: number;
-    }, options?: RequestOptions): Promise<{
+    }, _options?: RequestOptions): Promise<{
         correlationId: string;
         jobId: string;
     }>;
     gatherAnnotationContext(resourceId: ResourceId, annotationId: AnnotationId, data: {
         correlationId: string;
         contextWindow?: number;
-    }, options?: RequestOptions): Promise<{
+    }, _options?: RequestOptions): Promise<{
         correlationId: string;
     }>;
     matchSearch(resourceId: ResourceId, data: {
@@ -1210,13 +1008,17 @@ declare class SemiontApiClient {
         context: unknown;
         limit?: number;
         useSemanticScoring?: boolean;
-    }, options?: RequestOptions): Promise<{
+    }, _options?: RequestOptions): Promise<{
         correlationId: string;
     }>;
-    addEntityType(type: EntityType, options?: RequestOptions): Promise<void>;
-    addEntityTypesBulk(types: EntityType[], options?: RequestOptions): Promise<void>;
-    listEntityTypes(options?: RequestOptions): Promise<ResponseContent<paths['/api/entity-types']['get']>>;
-    beckonAttention(participantId: string, data: RequestContent<paths['/api/participants/{id}/attention']['post']>, options?: RequestOptions): Promise<ResponseContent<paths['/api/participants/{id}/attention']['post']>>;
+    addEntityType(type: EntityType, _options?: RequestOptions): Promise<void>;
+    addEntityTypesBulk(types: EntityType[], _options?: RequestOptions): Promise<void>;
+    listEntityTypes(_options?: RequestOptions): Promise<components['schemas']['GetEntityTypesResponse']>;
+    beckonAttention(_participantId: string, data: {
+        annotationId?: string;
+        resourceId: string;
+        message?: string;
+    }, _options?: RequestOptions): Promise<components['schemas']['BeckonResponse']>;
     listUsers(options?: RequestOptions): Promise<ResponseContent<paths['/api/admin/users']['get']>>;
     getUserStats(options?: RequestOptions): Promise<ResponseContent<paths['/api/admin/users/stats']['get']>>;
     /**
@@ -1268,7 +1070,7 @@ declare class SemiontApiClient {
         result?: Record<string, unknown>;
     }>;
     private parseSSEStream;
-    getJobStatus(id: JobId, options?: RequestOptions): Promise<ResponseContent<paths['/api/jobs/{id}']['get']>>;
+    getJobStatus(id: JobId, _options?: RequestOptions): Promise<components['schemas']['JobStatusResponse']>;
     /**
      * Poll a job until it completes or fails
      * @param id - The job ID to poll
@@ -1278,13 +1080,935 @@ declare class SemiontApiClient {
     pollJobUntilComplete(id: JobId, options?: {
         interval?: number;
         timeout?: number;
-        onProgress?: (status: ResponseContent<paths['/api/jobs/{id}']['get']>) => void;
+        onProgress?: (status: components['schemas']['JobStatusResponse']) => void;
         auth?: AccessToken;
-    }): Promise<ResponseContent<paths['/api/jobs/{id}']['get']>>;
+    }): Promise<components['schemas']['JobStatusResponse']>;
     healthCheck(options?: RequestOptions): Promise<ResponseContent<paths['/api/health']['get']>>;
     getStatus(options?: RequestOptions): Promise<ResponseContent<paths['/api/status']['get']>>;
-    browseFiles(dirPath?: string, sort?: 'name' | 'mtime' | 'annotationCount', options?: RequestOptions): Promise<ResponseContent<paths['/api/browse/files']['get']>>;
+    browseFiles(dirPath?: string, sort?: 'name' | 'mtime' | 'annotationCount', _options?: RequestOptions): Promise<components['schemas']['BrowseFilesResponse']>;
+}
+
+declare class BusRequestError extends Error {
+    constructor(message: string);
+}
+declare function busRequest<TResult>(actor: ActorVM, emitChannel: string, payload: Record<string, unknown>, resultChannel: string, failureChannel: string, timeoutMs?: number): Promise<TResult>;
+
+/**
+ * RxJS-native read-through cache primitive.
+ *
+ * Behavioral contract: packages/api-client/docs/CACHE-SEMANTICS.md (B1–B13).
+ *
+ * Framework-agnostic: no React, no dependency on any namespace. Used by
+ * `BrowseNamespace` to back its per-key stores, but equally usable from
+ * CLI, MCP, or worker code.
+ *
+ * Shape:
+ *   - `observe(key)`: returns an Observable<V | undefined> that triggers
+ *     a fetch on first subscription for a missing key, dedup-joins any
+ *     concurrent fetch, and emits the stored value thereafter.
+ *   - `invalidate(key)`: stale-while-revalidate — keeps the current
+ *     value visible to observers, clears the in-flight guard, starts a
+ *     fresh fetch. If the previous fetch was orphaned (SSE torn down,
+ *     response lost), this is how the cache recovers.
+ *   - `remove(key)`: drops the cache entry entirely. Used for entity
+ *     deletions (B13a). No refetch.
+ *   - `set(key, value)`: writes through without a fetch. Used when a
+ *     bus event carries the new value inline (B13b).
+ *   - `invalidateAll()`: per-key SWR refetch of every currently-cached
+ *     entry. Used by gap-detection paths.
+ *   - `dispose()`: completes the store so observers unsubscribe.
+ *
+ * What's deliberately out:
+ *   - No subscriber ref-counting / GC of unobserved keys. The per-key
+ *     observable memo grows with the set of observed keys for the cache's
+ *     lifetime (B11). Acceptable given cache lifetime == client lifetime.
+ *   - No TTL / cacheTime. Entries are evicted only by explicit remove.
+ *   - No retry / backoff. A failing fetch leaves the cache unchanged
+ *     (B6); the caller drives retry via invalidate.
+ */
+
+interface Cache<K, V> {
+    /** Observable stream of the value at `key`. Triggers a fetch if not cached. */
+    observe(key: K): Observable<V | undefined>;
+    /** Synchronous snapshot of the current value, without triggering a fetch. */
+    get(key: K): V | undefined;
+    /** Iterator of currently-cached keys. For invalidateAll and diagnostics. */
+    keys(): K[];
+    /**
+     * Mark the entry stale and refetch. Keeps the previous value visible
+     * to observers during the refetch (stale-while-revalidate).
+     */
+    invalidate(key: K): void;
+    /** Drop the entry from the cache. No refetch. */
+    remove(key: K): void;
+    /** Write-through: set the value directly without a fetch. */
+    set(key: K, value: V): void;
+    /** Per-key SWR refetch of every currently-cached entry. */
+    invalidateAll(): void;
+    /** Release the underlying subject. Observers complete. */
+    dispose(): void;
+}
+declare function createCache<K, V>(fetchFn: (key: K) => Promise<V>): Cache<K, V>;
+
+/**
+ * KnowledgeBase — a connection to a Semiont backend instance.
+ *
+ * Each KB has its own JWT, its own API base URL, and its own session.
+ * The user is "authenticated against KB X" — never globally authenticated.
+ */
+interface KnowledgeBase {
+    id: string;
+    label: string;
+    host: string;
+    port: number;
+    protocol: 'http' | 'https';
+    email: string;
+    gitBranch?: string;
+}
+/**
+ * Input shape for adding a new KB. The id is generated by the provider.
+ */
+type NewKnowledgeBase = Omit<KnowledgeBase, 'id'>;
+/**
+ * Status of the locally-stored credential for a KB. Derived from the
+ * presence and validity of the JWT in session storage.
+ */
+type KbSessionStatus = 'authenticated' | 'expired' | 'signed-out' | 'unreachable';
+
+/**
+ * Session-level error surface. Emitted on `SemiontBrowser.error$` for
+ * failures that make the session itself unusable (auth failed, actor
+ * couldn't start, token refresh terminally exhausted). Per-request
+ * errors stay with the caller as normal Promise rejections.
+ */
+type SemiontErrorCode = 'session.construct-failed' | 'session.auth-failed' | 'session.refresh-exhausted' | 'browser.sign-in-failed';
+declare class SemiontError extends Error {
+    readonly code: SemiontErrorCode;
+    readonly kbId: string | null;
+    constructor(code: SemiontErrorCode, message: string, kbId?: string | null);
+}
+
+/**
+ * SessionStorage — environment-agnostic persistence adapter for the
+ * Semiont session layer. Decouples `SemiontSession` / `SemiontBrowser`
+ * from `localStorage` / `window` so the same classes can run in a
+ * browser, a CLI process, or tests without environment guards.
+ *
+ * Implementations shipped here:
+ *  - `InMemorySessionStorage` — map-backed, for tests.
+ *
+ * Browser-backed (`WebBrowserStorage`) lives in `@semiont/react-ui`
+ * because it touches browser-only globals.
+ */
+/** String key/value store with optional cross-context change subscription. */
+interface SessionStorage {
+    /** Read a string value; null if absent. */
+    get(key: string): string | null;
+    /** Write a string value. */
+    set(key: string, value: string): void;
+    /** Remove a key. No-op if absent. */
+    delete(key: string): void;
+    /**
+     * Optional: subscribe to external changes (cross-tab, cross-process).
+     * Browser implements via the `storage` event; filesystem would use
+     * fs.watch; in-memory omits this method. Returns an unsubscribe
+     * callback. If omitted, cross-context sync simply isn't available
+     * in that environment — the session still works correctly within a
+     * single process.
+     */
+    subscribe?(handler: (key: string, newValue: string | null) => void): () => void;
+}
+/**
+ * Map-backed `SessionStorage`. Cross-context sync is not implemented;
+ * tests that need it can drive it manually.
+ */
+declare class InMemorySessionStorage implements SessionStorage {
+    private readonly map;
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    delete(key: string): void;
+}
+
+/**
+ * SemiontSession — per-backend session lifetime object. Owns the
+ * SemiontApiClient, the access token BehaviorSubject, and optionally
+ * an authenticated user. One SemiontSession exists per active backend
+ * connection; lifetime is decoupled from React mount lifetime.
+ *
+ * Headless by design. Runs in browsers, CLIs, workers, and tests.
+ * UI-specific state (session-expired/permission-denied modals) lives
+ * in `FrontendSessionSignals`, which wraps a session — the session
+ * itself has no modal observables, no user-facing notifications.
+ *
+ * Auth is parameterized via callbacks passed at construction:
+ *
+ *   - `refresh()` — invoked on 401 / proactive re-auth. Returns the
+ *     new access token, or null on failure. The frontend passes a
+ *     closure that runs the refresh-token flow; the worker passes
+ *     one that exchanges the shared secret.
+ *
+ *   - `validate(token)` — optional. If provided, the session calls
+ *     it once at startup with the stored token to confirm it's
+ *     still good and populate `user$`. Frontend passes `getMe`;
+ *     worker omits this (service principals have no user record).
+ *
+ *   - `onAuthFailed(message)` — optional. Invoked when refresh
+ *     terminally fails (expired token, no recovery possible). The
+ *     frontend wires this to `FrontendSessionSignals.notifySessionExpired`
+ *     so the modal surfaces; headless consumers typically just log.
+ *
+ * Persistence goes through a `SessionStorage` adapter provided at
+ * construction — the session never touches `localStorage` or `window`
+ * directly.
+ */
+
+type UserInfo = components['schemas']['UserResponse'];
+interface SemiontSessionConfig {
+    kb: KnowledgeBase;
+    /** Persistence adapter. Reads/writes tokens via this. */
+    storage: SessionStorage;
+    /**
+     * Re-authenticate after expiry / 401. Returns a new access token
+     * (no "Bearer " prefix) on success, or null if recovery is
+     * impossible (user needs to sign in again, or the service secret
+     * is missing). Callers must dedupe concurrent invocations if the
+     * underlying auth call isn't itself idempotent.
+     */
+    refresh: () => Promise<string | null>;
+    /**
+     * Validate the stored token at startup and populate `user$`. Omit
+     * for service-principal sessions (worker, CLI tools) where there
+     * is no user record to fetch.
+     */
+    validate?: (token: AccessToken) => Promise<UserInfo | null>;
+    /**
+     * Invoked when refresh terminally fails. Frontend consumers wire
+     * this to a UI signal that surfaces the session-expired modal.
+     */
+    onAuthFailed?: (message: string | null) => void;
+    /** Called for session-level failures (auth, refresh exhaustion). */
+    onError?: (err: SemiontError) => void;
+}
+declare class SemiontSession {
+    readonly kb: KnowledgeBase;
+    readonly client: SemiontApiClient;
+    readonly token$: BehaviorSubject<AccessToken | null>;
+    readonly user$: BehaviorSubject<UserInfo | null>;
+    readonly streamState$: Observable<ConnectionState>;
+    /** Resolves after the initial validation round-trip completes (success or failure). */
+    readonly ready: Promise<void>;
+    private readonly storage;
+    private readonly doRefresh;
+    private readonly doValidate?;
+    private readonly onAuthFailed;
+    private readonly onError;
+    private refreshTimer;
+    private unsubscribeStorage;
+    private disposed;
+    constructor(config: SemiontSessionConfig);
+    /**
+     * Run the initial mount-time validation. If a stored access token is
+     * present and unexpired, call the configured `validate` with it to
+     * confirm it still works and populate `user$`. If expired, try
+     * refresh first. On 401 from validate, try refresh once. Surfaces
+     * auth-failed on terminal failure.
+     *
+     * When no `validate` callback is provided (service principals), this
+     * still runs through the refresh-if-expired step so the stored
+     * token is current — it just skips the user-validation round trip.
+     */
+    private validate;
+    /**
+     * Refresh the access token via the configured `refresh` callback.
+     * On success, pushes the new token into `token$` and schedules the
+     * next proactive refresh. On failure, clears persisted state and
+     * fires `onAuthFailed` — the frontend's wiring of that callback is
+     * what surfaces the session-expired modal.
+     */
+    refresh(): Promise<AccessToken | null>;
+    private scheduleProactiveRefresh;
+    private clearRefreshTimer;
+    /**
+     * Cross-context sync: another tab/process refreshed or signed out this
+     * KB. Mirror the change into our in-memory state.
+     */
+    private handleStorageChange;
+    get expiresAt(): Date | null;
+    dispose(): Promise<void>;
+}
+
+/**
+ * OpenResource — a single entry in the open-resources list (tabs).
+ *
+ * The list itself lives on `SemiontBrowser.openResources$`. The CRUD
+ * methods (`addOpenResource`, `removeOpenResource`, `updateOpenResourceName`,
+ * `reorderOpenResources`) live on `SemiontBrowser` too.
+ */
+interface OpenResource {
+    /** Unique identifier for the resource */
+    id: string;
+    /** Display name of the resource */
+    name: string;
+    /** Timestamp when the resource was opened */
+    openedAt: number;
+    /** Order/position for manual sorting (optional for backward compatibility) */
+    order?: number;
+    /** Media type for icon display (e.g., 'application/pdf', 'text/plain') */
+    mediaType?: string;
+    /** Working-tree URI (e.g. "file://docs/overview.md") — used as tooltip in navigation */
+    storageUri?: string;
+}
+
+/**
+ * FrontendSessionSignals — modal state that belongs to the UI, not
+ * the session itself.
+ *
+ * `SemiontSession` is a headless per-backend client + token + user
+ * holder. It can run in any process: browser, worker, CLI, test. But
+ * the session-expired / permission-denied *modals* only make sense
+ * in a UI context. Keeping those observables on `SemiontSession`
+ * meant workers and CLIs carried four dead BehaviorSubjects that
+ * nothing would ever fire.
+ *
+ * `FrontendSessionSignals` owns the modal state and has no hard
+ * reference to a session. `SemiontBrowser` constructs one alongside
+ * every frontend session and wires:
+ *
+ *   - `session.onAuthFailed` → `signals.notifySessionExpired` so
+ *     proactive-refresh failures surface as modals
+ *   - `notify` module handlers → the active signals' methods so
+ *     external callers (e.g. React Query's QueryCache.onError) can
+ *     trigger the modals without touching the session
+ *
+ * React consumers that need modal state subscribe here; consumers
+ * that need bus/HTTP access continue to subscribe to the session.
+ *
+ * Session auth-state cleanup (clearing token, clearing storage) is
+ * the session's own responsibility inside `refresh()` — by the time
+ * `notifySessionExpired` runs, the session has already torn down.
+ * Signals only surfaces the modal.
+ */
+
+declare class FrontendSessionSignals {
+    readonly sessionExpiredAt$: BehaviorSubject<number | null>;
+    readonly sessionExpiredMessage$: BehaviorSubject<string | null>;
+    readonly permissionDeniedAt$: BehaviorSubject<number | null>;
+    readonly permissionDeniedMessage$: BehaviorSubject<string | null>;
+    constructor();
+    notifySessionExpired(message: string | null): void;
+    notifyPermissionDenied(message: string | null): void;
+    acknowledgeSessionExpired(): void;
+    acknowledgePermissionDenied(): void;
+    dispose(): void;
+}
+
+/**
+ * SemiontBrowser — top-level app-facing container for non-KB state.
+ *
+ * Holds the list of configured KBs, the active KB selection, the active
+ * SemiontSession, the identity token, the open-resources list, and a
+ * session-level error stream. Module-scoped singleton — survives every
+ * React re-render, remount, and route change. `SemiontProvider` hands
+ * the singleton to the React tree; `useSemiont()` returns it.
+ *
+ * Persistence goes through a `SessionStorage` adapter provided at
+ * construction — the browser never touches `localStorage` or `window`
+ * directly.
+ */
+
+interface SemiontBrowserConfig {
+    /** Persistence adapter. The browser reads/writes all persisted state via this. */
+    storage: SessionStorage;
+}
+declare class SemiontBrowser {
+    readonly kbs$: BehaviorSubject<KnowledgeBase[]>;
+    readonly activeKbId$: BehaviorSubject<string | null>;
+    readonly activeSession$: BehaviorSubject<SemiontSession | null>;
+    /**
+     * Modal signals (session-expired / permission-denied) for the
+     * currently-active session. Parallels `activeSession$` — always
+     * non-null when `activeSession$` is non-null, always null when it
+     * is. Extracted from the session itself so headless sessions
+     * (workers, CLIs, tests) don't carry dead modal observables.
+     * See [FrontendSessionSignals](./frontend-session-signals.ts).
+     */
+    readonly activeSignals$: BehaviorSubject<FrontendSessionSignals | null>;
+    /**
+     * True while a session is actively being constructed (setActiveKb /
+     * signIn in flight, awaiting `session.ready`). Distinguishes the
+     * "session about to arrive" intermediate state from "session
+     * intentionally null" (after signOut, or when the active KB has no
+     * stored credentials). UIs that want a loading spinner should gate
+     * on this; otherwise they get stuck spinning after every signOut.
+     */
+    readonly sessionActivating$: BehaviorSubject<boolean>;
+    readonly openResources$: BehaviorSubject<OpenResource[]>;
+    readonly error$: Subject<SemiontError>;
+    readonly identityToken$: BehaviorSubject<string | null>;
+    private readonly storage;
+    /**
+     * App-scoped EventBus. Hosts UI-shell events that must work regardless
+     * of whether a KB session is active: panel toggles, sidebar state,
+     * tab reorders, routing, settings, etc. Disjoint from the per-session
+     * bus inside `SemiontApiClient`, which carries KB-content events
+     * (mark:*, beckon:*, gather:*, match:*, bind:*, yield:*, browse:click).
+     */
+    private readonly eventBus;
+    private unregisterNotify;
+    private unsubscribeStorage;
+    private disposed;
+    private activating;
+    /**
+     * Per-KB in-flight refresh dedup. Simultaneous 401s for the same
+     * KB converge on a single `/api/tokens/refresh` network call.
+     * Was previously module-scoped in `refresh.ts`; moved here when
+     * that file was deleted — SemiontBrowser is a singleton so the
+     * scoping is equivalent.
+     */
+    private readonly inFlightRefreshes;
+    constructor(config: SemiontBrowserConfig);
+    /** Emit an event on the browser's app-scoped bus. */
+    emit<K extends keyof EventMap>(channel: K, payload: EventMap[K]): void;
+    /** Subscribe to an event; returns unsubscribe. */
+    on<K extends keyof EventMap>(channel: K, handler: (payload: EventMap[K]) => void): () => void;
+    /** Read-only observable for an app-scoped channel. */
+    stream<K extends keyof EventMap>(channel: K): Observable<EventMap[K]>;
+    /**
+     * Set the app-level identity token (from NextAuth's useSession).
+     * Called at the root layout via a single `useEffect`. No other site
+     * in the codebase should call this.
+     */
+    setIdentityToken(token: string | null): void;
+    addKb(input: NewKnowledgeBase, access: string, refresh: string): KnowledgeBase;
+    removeKb(id: string): void;
+    updateKb(id: string, updates: Partial<KnowledgeBase>): void;
+    /**
+     * Read the locally-stored credential status for a KB. Pure / synchronous —
+     * does not subscribe to context changes. Used by KB-list UI to color status
+     * dots without requiring re-renders on every tick.
+     */
+    getKbSessionStatus(kbId: string): KbSessionStatus;
+    /**
+     * Switch the active KB. Follows the D2 disposal contract:
+     *   1. Synchronously announce the new id on `activeKbId$` and null out
+     *      `activeSession$` so views see a safe empty state first.
+     *   2. Serialize overlapping calls — if an activation is in flight, wait
+     *      for it before proceeding.
+     *   3. Dispose whatever session is currently live.
+     *   4. Construct the next session and await `session.ready`.
+     *   5. Before emitting, re-check `activeKbId$` — if a newer call superseded
+     *      us while we waited, dispose our session and skip the emit.
+     *   6. Emit the new session.
+     */
+    setActiveKb(id: string | null): Promise<void>;
+    /**
+     * Sign in to an existing KB: store the tokens and (re)activate the
+     * session. If the KB is already active, the current session is disposed
+     * and replaced so the new tokens take effect.
+     */
+    signIn(id: string, access: string, refresh: string): Promise<void>;
+    /**
+     * Sign out of a KB: clear stored tokens. If the KB is active, dispose
+     * its session + signals and emit null for both.
+     */
+    signOut(id: string): Promise<void>;
+    addOpenResource(id: string, name: string, mediaType?: string, storageUri?: string): void;
+    removeOpenResource(id: string): void;
+    updateOpenResourceName(id: string, name: string): void;
+    reorderOpenResources(oldIndex: number, newIndex: number): void;
+    /**
+     * Refresh the active KB's access token. Returns the new token on
+     * success, null on failure. Concurrent calls for the same KB
+     * dedupe through `inFlightRefreshes`, so simultaneous 401s trigger
+     * only one `/api/tokens/refresh` round trip.
+     *
+     * Uses a throwaway `SemiontApiClient` with no `tokenRefresher` —
+     * a refresh call returning 401 would otherwise re-enter this
+     * function infinitely.
+     */
+    private performRefresh;
+    /**
+     * Validate an access token by calling `getMe` on a throwaway
+     * client. The session uses this once at startup to populate
+     * `user$`; 401 triggers a refresh-then-retry inside the session.
+     */
+    private performValidate;
+    dispose(): Promise<void>;
+}
+
+/**
+ * Module-scoped singleton for SemiontBrowser. Constructed lazily on first
+ * `getBrowser()` call, survives every React re-render, remount, and route
+ * change.
+ *
+ * The caller provides a `SessionStorage` implementation — there is no
+ * default here because storage-backend selection is environment-specific
+ * (browsers use `WebBrowserStorage`, CLI uses a filesystem adapter,
+ * tests use `InMemorySessionStorage`). The first call to `getBrowser`
+ * wins; subsequent calls return the cached instance regardless of the
+ * storage passed.
+ */
+
+interface GetBrowserOptions {
+    /** Persistence adapter used to construct the singleton on first call. */
+    storage: SessionStorage;
+}
+declare function getBrowser(options: GetBrowserOptions): SemiontBrowser;
+
+/**
+ * Pure helpers and storage-adapter-driven loaders for the Semiont
+ * session layer.
+ *
+ * Contains:
+ *  - Storage key shape (constants, `sessionKey(kbId)`)
+ *  - JWT expiry parsing and "is expired" check
+ *  - URL/protocol helpers for KB instances
+ *  - Loaders/savers that take a `SessionStorage` and operate over it
+ *    (no direct `localStorage` access)
+ *
+ * No React imports, no module-scoped state, no side effects beyond
+ * whatever the passed-in `SessionStorage` does.
+ */
+
+/** The shape persisted per KB. */
+interface StoredSession {
+    access: string;
+    refresh: string;
+}
+declare function setStoredSession(storage: SessionStorage, kbId: string, session: StoredSession): void;
+declare function defaultProtocol(host: string): 'http' | 'https';
+declare function isValidHostname(host: string): boolean;
+declare function kbBackendUrl(kb: KnowledgeBase): string;
+
+declare function notifySessionExpired(message?: string): void;
+declare function notifyPermissionDenied(message?: string): void;
+
+/**
+ * createSearchPipeline
+ *
+ * A debounced-search RxJS pipeline factory. Combines an input Subject with a
+ * downstream fetch function and emits typed `{ results, isSearching }` state.
+ *
+ * Designed to be created once per component instance via React's
+ * `useState(() => createSearchPipeline(...))` lazy initializer, then consumed
+ * via `useObservable(pipeline.state$)`. The pipeline holds no React state and
+ * has no React imports — it's pure RxJS, unit-testable without a renderer.
+ *
+ * The fetch function is expected to return `Observable<T[] | undefined>`,
+ * matching the cache-miss-then-data shape of `BrowseNamespace` Observables:
+ * `undefined` means "fetch in flight, no value yet"; an array means "data
+ * available (possibly empty)".
+ */
+
+interface SearchState<T> {
+    results: T[];
+    isSearching: boolean;
+}
+interface SearchPipeline<T> {
+    /** Latest query string. Bind to a controlled input via `useObservable`. */
+    query$: Observable<string>;
+    /** Latest search state — results plus a loading flag. */
+    state$: Observable<SearchState<T>>;
+    /** Push a new query value. Triggers the debounced fetch. */
+    setQuery(value: string): void;
+    /** Tear down the input Subject. Call from `useEffect` cleanup. */
+    dispose(): void;
+}
+interface SearchPipelineOptions {
+    /** Milliseconds to wait after the last keystroke before fetching. Default 250. */
+    debounceMs?: number;
+    /** Initial query value. Useful for modals that open with a pre-filled term. */
+    initialQuery?: string;
+}
+declare function createSearchPipeline<T>(fetch: (query: string) => Observable<T[] | undefined>, options?: SearchPipelineOptions): SearchPipeline<T>;
+
+interface BeckonVM extends ViewModel {
+    hoveredAnnotationId$: Observable<string | null>;
+    hover(annotationId: string | null): void;
+    focus(annotationId: string): void;
+    sparkle(annotationId: string): void;
+}
+declare function createBeckonVM(client: SemiontApiClient): BeckonVM;
+/** Default milliseconds the mouse must dwell before beckon:hover is emitted. */
+declare const HOVER_DELAY_MS = 150;
+type EmitHover = (annotationId: string | null) => void;
+interface HoverHandlers {
+    handleMouseEnter: (annotationId: string) => void;
+    handleMouseLeave: () => void;
+    cleanup: () => void;
+}
+declare function createHoverHandlers(emit: EmitHover, delayMs: number): HoverHandlers;
+
+/**
+ * ShellVM — app-shell state: which toolbar panel is open, tab-bar
+ * coordination helpers, scroll-to-annotation signals. Lives on
+ * `SemiontBrowser`'s app-scoped bus (not the per-session client bus)
+ * because panel toggles and shell chrome must work regardless of
+ * whether a KB session is active.
+ *
+ * Channels: `panel:toggle`, `panel:open`, `panel:close`.
+ */
+
+type ToolbarPanelType = 'history' | 'info' | 'annotations' | 'settings' | 'collaboration' | 'user' | 'jsonld' | 'knowledge-base';
+declare const COMMON_PANELS: readonly ToolbarPanelType[];
+declare const RESOURCE_PANELS: readonly ToolbarPanelType[];
+interface ShellVM extends ViewModel {
+    activePanel$: Observable<ToolbarPanelType | null>;
+    scrollToAnnotationId$: Observable<string | null>;
+    panelInitialTab$: Observable<{
+        tab: string;
+        generation: number;
+    } | null>;
+    openPanel(panel: string): void;
+    closePanel(): void;
+    togglePanel(panel: string): void;
+    onScrollCompleted(): void;
+}
+interface ShellVMOptions {
+    initialPanel?: ToolbarPanelType | null;
+    onPanelChange?: (panel: ToolbarPanelType | null) => void;
+}
+declare function createShellVM(browser: SemiontBrowser, options?: ShellVMOptions): ShellVM;
+
+interface GatherVM extends ViewModel {
+    context$: Observable<GatheredContext | null>;
+    loading$: Observable<boolean>;
+    error$: Observable<Error | null>;
+    annotationId$: Observable<AnnotationId | null>;
+}
+declare function createGatherVM(client: SemiontApiClient, resourceId: ResourceId): GatherVM;
+
+interface MatchVM extends ViewModel {
+}
+declare function createMatchVM(client: SemiontApiClient, _resourceId: ResourceId): MatchVM;
+
+type JobProgress$1 = components['schemas']['JobProgress'];
+interface GenerateDocumentOptions {
+    title: string;
+    storageUri: string;
+    prompt?: string;
+    language?: string;
+    temperature?: number;
+    maxTokens?: number;
+    context: GatheredContext;
+}
+interface YieldVM extends ViewModel {
+    isGenerating$: Observable<boolean>;
+    progress$: Observable<JobProgress$1 | null>;
+    generate(referenceId: string, options: GenerateDocumentOptions): void;
+}
+declare function createYieldVM(client: SemiontApiClient, resourceId: ResourceId, locale: string): YieldVM;
+
+type JobProgress = components['schemas']['JobProgress'];
+interface PendingAnnotation {
+    selector: Selector | Selector[];
+    motivation: Motivation;
+}
+interface MarkVM extends ViewModel {
+    pendingAnnotation$: Observable<PendingAnnotation | null>;
+    assistingMotivation$: Observable<Motivation | null>;
+    progress$: Observable<JobProgress | null>;
+}
+declare function createMarkVM(client: SemiontApiClient, resourceId: ResourceId): MarkVM;
+
+type ResourceDescriptor$2 = components['schemas']['ResourceDescriptor'];
+interface DiscoverVM extends ViewModel {
+    browse: ShellVM;
+    search: SearchPipeline<ResourceDescriptor$2>;
+    recentResources$: Observable<ResourceDescriptor$2[]>;
+    entityTypes$: Observable<string[]>;
+    isLoadingRecent$: Observable<boolean>;
+}
+declare function createDiscoverVM(client: SemiontApiClient, browse: ShellVM): DiscoverVM;
+
+interface EntityTagsVM extends ViewModel {
+    browse: ShellVM;
+    entityTypes$: Observable<string[]>;
+    isLoading$: Observable<boolean>;
+    newTag$: Observable<string>;
+    error$: Observable<string>;
+    isAdding$: Observable<boolean>;
+    setNewTag(value: string): void;
+    addTag(): Promise<void>;
+}
+declare function createEntityTagsVM(client: SemiontApiClient, browse: ShellVM): EntityTagsVM;
+
+interface ImportPreview {
+    format: string;
+    version: number;
+    sourceUrl: string;
+    stats: Record<string, number>;
+}
+interface ExchangeVM extends ViewModel {
+    browse: ShellVM;
+    selectedFile$: Observable<File | null>;
+    preview$: Observable<ImportPreview | null>;
+    importPhase$: Observable<string | null>;
+    importMessage$: Observable<string | undefined>;
+    importResult$: Observable<Record<string, unknown> | undefined>;
+    isExporting$: Observable<boolean>;
+    isImporting$: Observable<boolean>;
+    selectFile(file: File): void;
+    cancelImport(): void;
+    doExport(): Promise<{
+        blob: Blob;
+        filename: string;
+    }>;
+    doImport(): Promise<void>;
+}
+declare function createExchangeVM(browse: ShellVM, exportFn: (params?: {
+    includeArchived?: boolean;
+}) => Promise<Response>, importFn: (file: File, options?: {
+    onProgress?: (event: {
+        phase: string;
+        message?: string;
+        result?: Record<string, unknown>;
+    }) => void;
+}) => Promise<{
+    phase: string;
+    message?: string;
+    result?: Record<string, unknown>;
+}>): ExchangeVM;
+
+interface AdminUsersVM extends ViewModel {
+    browse: ShellVM;
+    users$: Observable<unknown[]>;
+    stats$: Observable<unknown | null>;
+    usersLoading$: Observable<boolean>;
+    statsLoading$: Observable<boolean>;
+    updateUser(id: string, data: {
+        isAdmin?: boolean;
+        isActive?: boolean;
+    }): Promise<void>;
+}
+declare function createAdminUsersVM(client: SemiontApiClient, browse: ShellVM): AdminUsersVM;
+
+interface AdminSecurityVM extends ViewModel {
+    browse: ShellVM;
+    providers$: Observable<unknown[]>;
+    allowedDomains$: Observable<string[]>;
+    isLoading$: Observable<boolean>;
+}
+declare function createAdminSecurityVM(client: SemiontApiClient, browse: ShellVM): AdminSecurityVM;
+
+interface WelcomeVM extends ViewModel {
+    userData$: Observable<{
+        termsAcceptedAt?: string;
+    } | null>;
+    isProcessing$: Observable<boolean>;
+    acceptTerms(): Promise<void>;
+}
+declare function createWelcomeVM(client: SemiontApiClient): WelcomeVM;
+
+type ResourceDescriptor$1 = components['schemas']['ResourceDescriptor'];
+interface ResourceLoaderVM extends ViewModel {
+    resource$: Observable<ResourceDescriptor$1 | undefined>;
+    isLoading$: Observable<boolean>;
+    invalidate(): void;
+}
+declare function createResourceLoaderVM(client: SemiontApiClient, resourceId: ResourceId): ResourceLoaderVM;
+
+interface SessionVM extends ViewModel {
+    isLoggingOut$: Observable<boolean>;
+    logout(): Promise<void>;
+}
+declare function createSessionVM(client: SemiontApiClient): SessionVM;
+
+interface SmelterEvent {
+    type: string;
+    resourceId?: string;
+    payload: Record<string, unknown>;
+}
+interface SmelterActorVMOptions {
+    baseUrl: string;
+    token: string;
+    reconnectMs?: number;
+}
+interface SmelterActorVM extends ViewModel {
+    events$: Observable<SmelterEvent>;
+    state$: Observable<ConnectionState>;
+    emit(channel: string, payload: Record<string, unknown>): Promise<void>;
+    start(): void;
+    stop(): void;
+}
+declare function createSmelterActorVM(options: SmelterActorVMOptions): SmelterActorVM;
+
+/**
+ * Job Claim Adapter — worker-side job lifecycle glue on top of a
+ * shared `ActorVM`.
+ *
+ * Replaces the old `WorkerVM`, which owned its own actor and
+ * duplicated the SSE connection that `SemiontApiClient` already held.
+ * Workers now construct a `SemiontSession` normally (one actor, one
+ * SSE connection) and use this adapter to attach job-claim behaviour
+ * on top of `session.client.actor`.
+ *
+ * The adapter is intentionally thin: it subscribes to `job:queued`
+ * on the actor, claims jobs via the existing request-response
+ * protocol (`job:claim` → `job:claimed` / `job:claim-failed`), and
+ * exposes observables for job orchestration. It does **not** own
+ * the actor, has no HTTP concerns, and has no modal state.
+ */
+
+interface JobAssignment {
+    jobId: string;
+    type: string;
+    resourceId: string;
+}
+interface ActiveJob {
+    jobId: string;
+    type: string;
+    resourceId: string;
+    userId: string;
+    params: Record<string, unknown>;
+}
+interface JobClaimAdapterOptions {
+    /** Shared actor (typically `session.client.actor`). */
+    actor: ActorVM;
+    /**
+     * Job types this worker can process. Jobs of other types that
+     * arrive on `job:queued` are ignored. Empty array = accept any.
+     */
+    jobTypes: string[];
+}
+interface JobClaimAdapter {
+    /** Currently-claimed job, or null when idle. */
+    readonly activeJob$: Observable<ActiveJob | null>;
+    /** True while a claim is in flight or a job is being processed. */
+    readonly isProcessing$: Observable<boolean>;
+    /** Monotonically-incrementing count of successfully-completed jobs. */
+    readonly jobsCompleted$: Observable<number>;
+    /** Stream of job failures (including claim-failed and processing errors). */
+    readonly errors$: Observable<{
+        jobId: string;
+        error: string;
+    }>;
+    /**
+     * Subscribe to `job:queued` events (adding the channel to the actor
+     * if not already subscribed) and begin claiming matching jobs.
+     * Idempotent — calling `start()` twice is a no-op.
+     */
+    start(): void;
+    /** Stop claiming new jobs. Does not cancel an in-flight job. */
+    stop(): void;
+    /** Signal successful completion of `activeJob$`. */
+    completeJob(): void;
+    /** Signal failure of `activeJob$`. Emits on `errors$`. */
+    failJob(jobId: string, error: string): void;
+    /** Release observables. Does not dispose the shared actor. */
+    dispose(): void;
+}
+/**
+ * Attach job-claim behaviour to a shared `ActorVM`.
+ */
+declare function createJobClaimAdapter(options: JobClaimAdapterOptions): JobClaimAdapter;
+
+interface Job {
+    jobId: string;
+    type: string;
+    status: string;
+    resourceId: string;
+    userId: string;
+    created: string;
+    startedAt?: string;
+    completedAt?: string;
+    error?: string;
+    progress?: Record<string, unknown>;
+    result?: Record<string, unknown>;
+}
+interface JobQueueVM extends ViewModel {
+    jobs$: Observable<Job[]>;
+    pendingByType$: Observable<Map<string, number>>;
+    runningJobs$: Observable<Job[]>;
+    jobCreated$: Observable<Job>;
+    jobCompleted$: Observable<Job>;
+    jobFailed$: Observable<Job>;
+}
+declare function createJobQueueVM(client: SemiontApiClient): JobQueueVM;
+
+type Annotation = components['schemas']['Annotation'];
+interface AnnotationGroups {
+    highlights: Annotation[];
+    comments: Annotation[];
+    assessments: Annotation[];
+    references: Annotation[];
+    tags: Annotation[];
+}
+type StoredEventResponse = components['schemas']['StoredEventResponse'];
+interface WizardState {
+    open: boolean;
+    annotationId: string | null;
+    resourceId: string | null;
+    defaultTitle: string;
+    entityTypes: string[];
+}
+interface ResourceViewerPageVM extends ViewModel {
+    beckon: BeckonVM;
+    browse: ShellVM;
+    mark: MarkVM;
+    gather: GatherVM;
+    yield: YieldVM;
+    annotations$: Observable<Annotation[]>;
+    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 createResourceViewerPageVM(client: SemiontApiClient, resourceId: ResourceId, locale: string, browse: ShellVM, options?: {
+    mediaType?: string;
+}): ResourceViewerPageVM;
+
+type ResourceDescriptor = components['schemas']['ResourceDescriptor'];
+type ComposeMode = 'new' | 'clone' | 'reference';
+interface ComposeParams {
+    mode?: string | undefined;
+    token?: string | undefined;
+    annotationUri?: string | undefined;
+    sourceDocumentId?: string | undefined;
+    name?: string | undefined;
+    entityTypes?: string | undefined;
+    storedContext?: string | undefined;
+}
+interface CloneData {
+    sourceResource: ResourceDescriptor;
+    sourceContent: string;
+}
+interface ReferenceData {
+    annotationUri: string;
+    sourceDocumentId: string;
+    name: string;
+    entityTypes: string[];
+}
+interface SaveResourceParams {
+    mode: ComposeMode;
+    name: string;
+    storageUri: string;
+    content?: string;
+    file?: File;
+    format?: string;
+    charset?: string;
+    entityTypes?: string[];
+    language: string;
+    archiveOriginal?: boolean;
+    annotationUri?: string;
+    sourceDocumentId?: string;
+}
+interface ComposePageVM extends ViewModel {
+    browse: ShellVM;
+    mode$: Observable<ComposeMode>;
+    loading$: Observable<boolean>;
+    cloneData$: Observable<CloneData | null>;
+    referenceData$: Observable<ReferenceData | null>;
+    gatheredContext$: Observable<GatheredContext | null>;
+    entityTypes$: Observable<string[]>;
+    save(params: SaveResourceParams): Promise<string>;
 }
+declare function createComposePageVM(client: SemiontApiClient, browse: ShellVM, params: ComposeParams, auth?: AccessToken): ComposePageVM;
 
 /**
  * MIME type utilities for Semiont
@@ -1324,4 +2048,4 @@ declare function isPdfMimeType(mimeType: string): boolean;
 type MimeCategory = 'text' | 'image' | 'unsupported';
 declare function getMimeCategory(mimeType: string): MimeCategory;
 
-export { APIError, AdminNamespace, type AnnotationHistoryResponse, AuthNamespace, BeckonNamespace, BindNamespace, BrowseNamespace, type CreateAnnotationInput, type CreateFromTokenOptions, type CreateResourceInput, type GatherAnnotationProgress, GatherNamespace, type GenerationOptions, JobNamespace, type MarkAssistOptions, type MarkAssistProgress, MarkNamespace, MatchNamespace, type MatchSearchProgress, type MimeCategory, type ReferenceDetectionProgress, type ReferencedByEntry, type RequestContent$1 as RequestContent, type RequestOptions, type ResponseContent$1 as ResponseContent, SSEClient, type SSEClientConfig, type SSEStream, type SSEStreamConnected, SSE_STREAM_CONNECTED, SemiontApiClient, type SemiontApiClientConfig, type TokenRefresher, type User, YieldNamespace, type YieldProgress, getExtensionForMimeType, getMimeCategory, isImageMimeType, isPdfMimeType, isTextMimeType };
+export { APIError, type ActiveJob, type ActorVM, type ActorVMOptions, AdminNamespace, type AdminSecurityVM, type AdminUsersVM, type AnnotationGroups, type AnnotationHistoryResponse, AuthNamespace, BeckonNamespace, type BeckonVM, BindNamespace, BrowseNamespace, type BusEvent, BusRequestError, COMMON_PANELS, type Cache, type CloneData, type ComposeMode, type ComposePageVM, type ComposeParams, type ConnectionState, type CreateAnnotationInput, type CreateFromTokenOptions, type CreateResourceInput, DEGRADED_THRESHOLD_MS, type DiscoverVM, type EntityTagsVM, type ExchangeVM, FrontendSessionSignals, type GatherAnnotationProgress, GatherNamespace, type GatherVM, type GenerateDocumentOptions, type GenerationOptions, type GetBrowserOptions, HOVER_DELAY_MS, type HoverHandlers, type ImportPreview, InMemorySessionStorage, type Job, type JobAssignment, type JobClaimAdapter, type JobClaimAdapterOptions, JobNamespace, type JobQueueVM, type KbSessionStatus, type KnowledgeBase, type MarkAssistOptions, type MarkAssistProgress, MarkNamespace, type MarkVM, MatchNamespace, type MatchSearchProgress, type MatchVM, type MimeCategory, type NewKnowledgeBase, type OpenResource, type PendingAnnotation, RESOURCE_PANELS, type ReferenceData, type ReferencedByEntry, type RequestContent$1 as RequestContent, type RequestOptions, type ResourceLoaderVM, type ResourceViewerPageVM, type ResponseContent$1 as ResponseContent, type SaveResourceParams, type SearchPipeline, type SearchPipelineOptions, type SearchState, SemiontApiClient, type SemiontApiClientConfig, SemiontBrowser, type SemiontBrowserConfig, SemiontError, type SemiontErrorCode, SemiontSession, type SemiontSessionConfig, type SessionStorage, type SessionVM, type ShellVM, type ShellVMOptions, type SmelterActorVM, type SmelterActorVMOptions, type SmelterEvent, type StoredSession, type TokenRefresher, type ToolbarPanelType, type User, type UserInfo, type ViewModel, type WelcomeVM, type WizardState, YieldNamespace, type YieldVM, busRequest, createActorVM, createAdminSecurityVM, createAdminUsersVM, createBeckonVM, createCache, createComposePageVM, createDiscoverVM, createDisposer, createEntityTagsVM, createExchangeVM, createGatherVM, createHoverHandlers, createJobClaimAdapter, createJobQueueVM, createMarkVM, createMatchVM, createResourceLoaderVM, createResourceViewerPageVM, createSearchPipeline, createSessionVM, createShellVM, createSmelterActorVM, createWelcomeVM, createYieldVM, defaultProtocol, getBrowser, getExtensionForMimeType, getMimeCategory, isImageMimeType, isPdfMimeType, isTextMimeType, isValidHostname, kbBackendUrl, notifyPermissionDenied, notifySessionExpired, setStoredSession };