@semiont/sdk 0.4.21

package/dist/index.d.ts

@@ -0,0 +1,1688 @@
+import * as rxjs from 'rxjs';
+import { Observable, BehaviorSubject, Subject } from 'rxjs';
+import * as _semiont_core from '@semiont/core';
+import { components, UserDID, paths, ResourceId, AnnotationId, BodyOperation, EventMap, ResourceDescriptor, Annotation, GraphConnection, Motivation, GatheredContext, JobId, ITransport, EventBus, IContentTransport, BaseUrl, AccessToken, ConnectionState, Selector } from '@semiont/core';
+export { ConnectionState, Logger } from '@semiont/core';
+import { ActorVM } from '@semiont/api-client';
+export { APIError, ActorVM, ActorVMOptions, BusEvent, DEGRADED_THRESHOLD_MS, HttpContentTransport, HttpTransport, HttpTransportConfig, TokenRefresher, createActorVM } from '@semiont/api-client';
+
+/**
+ * Verb Namespace Interfaces
+ *
+ * These interfaces define the public API of the Semiont api-client,
+ * organized by the 7 domain flows (Browse, Mark, Bind, Gather, Match,
+ * Yield, Beckon) plus infrastructure namespaces (Job, Auth, Admin).
+ *
+ * Each namespace maps 1:1 to a flow. Each flow maps to a clear actor
+ * on the backend. The frontend calls `client.mark.annotation()` and the
+ * proxy handles HTTP, auth, SSE, and caching internally.
+ *
+ * Return type conventions:
+ * - 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 StoredEventResponse$2 = components['schemas']['StoredEventResponse'];
+type GatherProgress = components['schemas']['GatherProgress'];
+type MatchSearchResult = components['schemas']['MatchSearchResult'];
+type JobProgress$2 = components['schemas']['JobProgress'];
+type GatherAnnotationComplete = components['schemas']['GatherAnnotationComplete'];
+type JobStatusResponse$1 = components['schemas']['JobStatusResponse'];
+type AuthResponse$1 = components['schemas']['AuthResponse'];
+type TokenRefreshResponse$1 = components['schemas']['TokenRefreshResponse'];
+type OAuthConfigResponse$1 = components['schemas']['OAuthConfigResponse'];
+type AdminUserStatsResponse$1 = components['schemas']['AdminUserStatsResponse'];
+type ResponseContent<T> = T extends {
+    responses: {
+        200: {
+            content: {
+                'application/json': infer R;
+            };
+        };
+    };
+} ? R : T extends {
+    responses: {
+        201: {
+            content: {
+                'application/json': infer R;
+            };
+        };
+    };
+} ? R : T extends {
+    responses: {
+        202: {
+            content: {
+                'application/json': infer R;
+            };
+        };
+    };
+} ? R : never;
+type RequestContent<T> = T extends {
+    requestBody?: {
+        content: {
+            'application/json': infer R;
+        };
+    };
+} ? R : never;
+/** Input for creating an annotation via mark.annotation() */
+type CreateAnnotationInput = components['schemas']['CreateAnnotationRequest'];
+/** Input for creating a resource via yield.resource() */
+interface CreateResourceInput {
+    name: string;
+    file: File | Buffer;
+    format: string;
+    entityTypes?: string[];
+    language?: string;
+    creationMethod?: string;
+    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 {
+    title: string;
+    storageUri: string;
+    context: GatheredContext;
+    prompt?: string;
+    language?: string;
+    temperature?: number;
+    maxTokens?: number;
+}
+/** Options for mark.assist() */
+interface MarkAssistOptions {
+    entityTypes?: string[];
+    includeDescriptiveReferences?: boolean;
+    instructions?: string;
+    density?: number;
+    tone?: string;
+    language?: string;
+    schemaId?: string;
+    categories?: string[];
+}
+/** Options for yield.createFromToken() */
+type CreateFromTokenOptions = {
+    token: string;
+    name: string;
+    content: string;
+    archiveOriginal?: boolean;
+};
+/** Referenced-by entry from browse.referencedBy() */
+type ReferencedByEntry = components['schemas']['GetReferencedByResponse']['referencedBy'][number];
+/** Annotation history from browse.annotationHistory() */
+type AnnotationHistoryResponse = components['schemas']['GetAnnotationHistoryResponse'];
+/** User object from auth/admin responses */
+type User = AuthResponse$1['user'];
+/**
+ * Progress emitted by gather.annotation() Observable.
+ * Emits GatherProgress during assembly, then GatherAnnotationComplete on finish.
+ */
+type GatherAnnotationProgress = GatherProgress | GatherAnnotationComplete;
+/**
+ * Progress emitted by match.search() Observable.
+ * Emits the final MatchSearchResult (no intermediate progress events currently).
+ */
+type MatchSearchProgress = MatchSearchResult;
+/**
+ * Progress payload emitted by mark.assist() and yield.fromAnnotation()
+ * Observables. Each progress emission carries a JobProgress snapshot
+ * (unified job lifecycle).
+ */
+type MarkAssistProgress = JobProgress$2;
+/**
+ * Discriminated event yielded by the `mark.assist()` Observable. Progress
+ * events stream while the worker runs; the final value before the
+ * Observable completes is a `complete` event carrying the `JobCompleteCommand`
+ * payload (with `result`, `jobId`, `jobType`, etc.). The Observable errors
+ * on `job:fail`.
+ */
+type MarkAssistEvent = {
+    kind: 'progress';
+    data: MarkAssistProgress;
+} | {
+    kind: 'complete';
+    data: components['schemas']['JobCompleteCommand'];
+};
+/**
+ * Discriminated event yielded by the `yield.fromAnnotation()` Observable.
+ * Same shape and semantics as `MarkAssistEvent`.
+ */
+type YieldGenerationEvent = {
+    kind: 'progress';
+    data: JobProgress$2;
+} | {
+    kind: 'complete';
+    data: components['schemas']['JobCompleteCommand'];
+};
+/**
+ * Browse — reads from materialized views
+ *
+ * Live queries return Observables that emit initial state and re-emit
+ * 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 | undefined>;
+    resources(filters?: {
+        limit?: number;
+        archived?: boolean;
+        search?: string;
+    }): Observable<ResourceDescriptor[] | undefined>;
+    annotations(resourceId: ResourceId): Observable<Annotation[] | undefined>;
+    annotation(resourceId: ResourceId, annotationId: AnnotationId): Observable<Annotation | 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;
+    }): Promise<{
+        data: ArrayBuffer;
+        contentType: string;
+    }>;
+    resourceRepresentationStream(resourceId: ResourceId, options?: {
+        accept?: string;
+    }): Promise<{
+        stream: ReadableStream<Uint8Array>;
+        contentType: string;
+    }>;
+    resourceEvents(resourceId: ResourceId): Promise<StoredEventResponse$2[]>;
+    annotationHistory(resourceId: ResourceId, annotationId: AnnotationId): Promise<AnnotationHistoryResponse>;
+    connections(resourceId: ResourceId): Promise<GraphConnection[]>;
+    backlinks(resourceId: ResourceId): Promise<Annotation[]>;
+    resourcesByName(query: string, limit?: number): Promise<ResourceDescriptor[]>;
+    files(dirPath?: string, sort?: 'name' | 'mtime' | 'annotationCount'): Promise<components['schemas']['BrowseFilesResponse']>;
+    click(annotationId: AnnotationId, motivation: Motivation): void;
+    navigateReference(resourceId: ResourceId): void;
+}
+/**
+ * Mark — annotation CRUD, entity types, AI assist
+ *
+ * Commands return Promises that resolve on HTTP acceptance (202).
+ * Results appear on browse Observables via bus gateway.
+ * assist() returns an Observable for long-running progress.
+ *
+ * Backend actor: Stower
+ * Event prefix: mark:*
+ */
+interface MarkNamespace$1 {
+    annotation(resourceId: ResourceId, input: CreateAnnotationInput): Promise<{
+        annotationId: string;
+    }>;
+    delete(resourceId: ResourceId, annotationId: AnnotationId): Promise<void>;
+    entityType(type: string): Promise<void>;
+    entityTypes(types: string[]): Promise<void>;
+    archive(resourceId: ResourceId): Promise<void>;
+    unarchive(resourceId: ResourceId): Promise<void>;
+    assist(resourceId: ResourceId, motivation: Motivation, options: MarkAssistOptions): Observable<MarkAssistEvent>;
+    request(selector: components['schemas']['MarkRequestedEvent']['selector'], motivation: Motivation): void;
+    /** Fire-and-forget variant of `assist` — mark-vm orchestrates the call and its progress Observable. */
+    requestAssist(motivation: Motivation, options: MarkAssistOptions, correlationId?: string): void;
+    /** Submit the currently pending annotation with its selector and optional body. */
+    submit(input: components['schemas']['MarkSubmitEvent']): void;
+    /** Cancel the currently pending annotation (if any). */
+    cancelPending(): void;
+    /** Dismiss the in-progress AI-assist widget. */
+    dismissProgress(): void;
+    changeSelection(motivation: Motivation | null): void;
+    changeClick(action: string): void;
+    changeShape(shape: string): void;
+    toggleMode(): void;
+}
+/**
+ * Bind — 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)
+ */
+interface BindNamespace$1 {
+    body(resourceId: ResourceId, annotationId: AnnotationId, operations: BodyOperation[]): Promise<void>;
+    /** UI signal: a reference-binding flow is requested for an annotation. */
+    initiate(input: EventMap['bind:initiate']): void;
+}
+/**
+ * Gather — context assembly
+ *
+ * Long-running (LLM calls + graph traversal). Returns Observables
+ * that emit progress then the gathered context.
+ *
+ * Backend actor: Gatherer
+ * Event prefix: gather:*
+ */
+interface GatherNamespace$1 {
+    annotation(annotationId: AnnotationId, resourceId: ResourceId, options?: {
+        contextWindow?: number;
+    }): Observable<GatherAnnotationProgress>;
+    resource(resourceId: ResourceId, options?: {
+        contextWindow?: number;
+    }): Observable<GatherAnnotationProgress>;
+}
+/**
+ * Match — search and ranking
+ *
+ * Long-running (semantic search, optional LLM scoring). Returns
+ * Observable with progress then results.
+ *
+ * Backend actor: Matcher
+ * Event prefix: match:*
+ */
+interface MatchNamespace$1 {
+    search(resourceId: ResourceId, referenceId: string, context: GatheredContext, options?: {
+        limit?: number;
+        useSemanticScoring?: boolean;
+    }): Observable<MatchSearchProgress>;
+    /** Fire-and-forget variant: match-vm orchestrates the call and its result Observable. */
+    requestSearch(input: components['schemas']['MatchSearchRequest']): void;
+}
+/**
+ * Yield — resource creation
+ *
+ * resource() is synchronous file upload (Promise).
+ * fromAnnotation() is long-running LLM generation (Observable).
+ *
+ * Backend actor: Stower + generation worker
+ * Event prefix: yield:*
+ */
+interface YieldNamespace$1 {
+    resource(data: CreateResourceInput): Promise<{
+        resourceId: string;
+    }>;
+    fromAnnotation(resourceId: ResourceId, annotationId: AnnotationId, options: GenerationOptions): Observable<YieldGenerationEvent>;
+    cloneToken(resourceId: ResourceId): Promise<{
+        token: string;
+        expiresAt: string;
+    }>;
+    fromToken(token: string): Promise<ResourceDescriptor>;
+    createFromToken(options: CreateFromTokenOptions): Promise<{
+        resourceId: string;
+    }>;
+    /** UI signal: user invoked the clone action from the resource-info panel. */
+    clone(): void;
+}
+/**
+ * Beckon — 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:*
+ */
+interface BeckonNamespace$1 {
+    attention(annotationId: AnnotationId, resourceId: ResourceId): void;
+    hover(annotationId: AnnotationId | null): void;
+    sparkle(annotationId: AnnotationId): void;
+}
+/**
+ * Job — worker lifecycle
+ */
+interface JobNamespace$1 {
+    /** Live stream of `job:queued` events from the bus. */
+    readonly queued$: Observable<EventMap['job:queued']>;
+    /** Live stream of `job:report-progress` events from the bus. */
+    readonly progress$: Observable<EventMap['job:report-progress']>;
+    /** Live stream of `job:complete` events from the bus. */
+    readonly complete$: Observable<EventMap['job:complete']>;
+    /** Live stream of `job:fail` events from the bus. */
+    readonly fail$: Observable<EventMap['job:fail']>;
+    status(jobId: JobId): Promise<JobStatusResponse$1>;
+    pollUntilComplete(jobId: JobId, options?: {
+        interval?: number;
+        timeout?: number;
+        onProgress?: (status: JobStatusResponse$1) => void;
+    }): Promise<JobStatusResponse$1>;
+    cancel(jobId: JobId, type: string): Promise<void>;
+    /** UI signal: cancel all active jobs of a given type (e.g. "annotation"). */
+    cancelRequest(jobType: 'annotation' | 'generation'): void;
+}
+/**
+ * Auth — authentication
+ */
+interface AuthNamespace$1 {
+    password(email: string, password: string): Promise<AuthResponse$1>;
+    google(credential: string): Promise<AuthResponse$1>;
+    refresh(token: string): Promise<TokenRefreshResponse$1>;
+    logout(): Promise<void>;
+    me(): Promise<User>;
+    acceptTerms(): Promise<void>;
+    mcpToken(): Promise<{
+        token: string;
+    }>;
+    mediaToken(resourceId: ResourceId): Promise<{
+        token: string;
+    }>;
+}
+/**
+ * Admin — administration
+ */
+interface AdminNamespace$1 {
+    users(): Promise<User[]>;
+    userStats(): Promise<AdminUserStatsResponse$1>;
+    updateUser(userId: UserDID, data: RequestContent<paths['/api/admin/users/{id}']['patch']>): Promise<User>;
+    oauthConfig(): Promise<OAuthConfigResponse$1>;
+    healthCheck(): Promise<ResponseContent<paths['/api/health']['get']>>;
+    status(): Promise<ResponseContent<paths['/api/status']['get']>>;
+    backup(): Promise<Response>;
+    restore(file: File, onProgress?: (event: {
+        phase: string;
+        message?: string;
+        result?: Record<string, unknown>;
+    }) => void): Promise<{
+        phase: string;
+        message?: string;
+        result?: Record<string, unknown>;
+    }>;
+    exportKnowledgeBase(params?: {
+        includeArchived?: boolean;
+    }): Promise<Response>;
+    importKnowledgeBase(file: File, onProgress?: (event: {
+        phase: string;
+        message?: string;
+        result?: Record<string, unknown>;
+    }) => void): Promise<{
+        phase: string;
+        message?: string;
+        result?: Record<string, unknown>;
+    }>;
+}
+
+type StoredEventResponse$1 = components['schemas']['StoredEventResponse'];
+type ResourceListFilters = {
+    limit?: number;
+    archived?: boolean;
+    search?: string;
+};
+declare class BrowseNamespace implements BrowseNamespace$1 {
+    private readonly transport;
+    private readonly bus;
+    private readonly content;
+    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;
+    constructor(transport: ITransport, bus: EventBus, content: IContentTransport);
+    resource(resourceId: ResourceId): Observable<ResourceDescriptor | undefined>;
+    resources(filters?: ResourceListFilters): Observable<ResourceDescriptor[] | undefined>;
+    annotations(resourceId: ResourceId): Observable<Annotation[] | undefined>;
+    annotation(resourceId: ResourceId, annotationId: AnnotationId): Observable<Annotation | 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;
+    }): Promise<{
+        data: ArrayBuffer;
+        contentType: string;
+    }>;
+    resourceRepresentationStream(resourceId: ResourceId, options?: {
+        accept?: string;
+    }): Promise<{
+        stream: ReadableStream<Uint8Array>;
+        contentType: string;
+    }>;
+    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[]>;
+    files(dirPath?: string, sort?: 'name' | 'mtime' | 'annotationCount'): Promise<components['schemas']['BrowseFilesResponse']>;
+    click(annotationId: AnnotationId, motivation: Motivation): void;
+    navigateReference(resourceId: ResourceId): void;
+    invalidateAnnotationList(resourceId: ResourceId): void;
+    removeAnnotationDetail(annotationId: AnnotationId): void;
+    invalidateResourceDetail(id: ResourceId): void;
+    invalidateResourceLists(): void;
+    invalidateEntityTypes(): void;
+    invalidateReferencedBy(resourceId: ResourceId): void;
+    invalidateResourceEvents(resourceId: ResourceId): void;
+    updateAnnotationInPlace(resourceId: ResourceId, annotation: Annotation): 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;
+}
+
+declare class MarkNamespace implements MarkNamespace$1 {
+    private readonly transport;
+    private readonly bus;
+    constructor(transport: ITransport, bus: EventBus);
+    annotation(resourceId: ResourceId, input: CreateAnnotationInput): Promise<{
+        annotationId: string;
+    }>;
+    delete(resourceId: ResourceId, annotationId: AnnotationId): Promise<void>;
+    entityType(type: string): Promise<void>;
+    entityTypes(types: string[]): Promise<void>;
+    archive(resourceId: ResourceId): Promise<void>;
+    unarchive(resourceId: ResourceId): Promise<void>;
+    assist(resourceId: ResourceId, motivation: Motivation, options: MarkAssistOptions): Observable<MarkAssistEvent>;
+    request(selector: components['schemas']['MarkRequestedEvent']['selector'], motivation: Motivation): void;
+    requestAssist(motivation: Motivation, options: MarkAssistOptions, correlationId?: string): void;
+    submit(input: components['schemas']['MarkSubmitEvent']): void;
+    cancelPending(): void;
+    dismissProgress(): void;
+    changeSelection(motivation: Motivation | null): void;
+    changeClick(action: string): void;
+    changeShape(shape: string): void;
+    toggleMode(): void;
+    private dispatchAssist;
+}
+
+declare class BindNamespace implements BindNamespace$1 {
+    private readonly transport;
+    private readonly bus;
+    constructor(transport: ITransport, bus: EventBus);
+    body(resourceId: ResourceId, annotationId: AnnotationId, operations: BodyOperation[]): Promise<void>;
+    initiate(input: EventMap['bind:initiate']): void;
+}
+
+declare class GatherNamespace implements GatherNamespace$1 {
+    private readonly transport;
+    private readonly bus;
+    constructor(transport: ITransport, bus: EventBus);
+    annotation(annotationId: AnnotationId, resourceId: ResourceId, options?: {
+        contextWindow?: number;
+    }): Observable<GatherAnnotationProgress>;
+    resource(_resourceId: ResourceId, _options?: {
+        contextWindow?: number;
+    }): Observable<GatherAnnotationProgress>;
+}
+
+declare class MatchNamespace implements MatchNamespace$1 {
+    private readonly transport;
+    private readonly bus;
+    constructor(transport: ITransport, bus: EventBus);
+    requestSearch(input: components['schemas']['MatchSearchRequest']): void;
+    search(resourceId: ResourceId, referenceId: string, context: GatheredContext, options?: {
+        limit?: number;
+        useSemanticScoring?: boolean;
+    }): Observable<MatchSearchProgress>;
+}
+
+declare class YieldNamespace implements YieldNamespace$1 {
+    private readonly transport;
+    private readonly bus;
+    private readonly content;
+    constructor(transport: ITransport, bus: EventBus, content: IContentTransport);
+    resource(data: CreateResourceInput): Promise<{
+        resourceId: string;
+    }>;
+    fromAnnotation(resourceId: ResourceId, annotationId: AnnotationId, options: GenerationOptions): Observable<YieldGenerationEvent>;
+    cloneToken(resourceId: ResourceId): Promise<{
+        token: string;
+        expiresAt: string;
+    }>;
+    fromToken(token: string): Promise<ResourceDescriptor>;
+    createFromToken(options: CreateFromTokenOptions): Promise<{
+        resourceId: string;
+    }>;
+    clone(): void;
+}
+
+declare class BeckonNamespace implements BeckonNamespace$1 {
+    private readonly transport;
+    private readonly bus;
+    constructor(transport: ITransport, bus: EventBus);
+    attention(annotationId: AnnotationId, resourceId: ResourceId): void;
+    hover(annotationId: AnnotationId | null): void;
+    sparkle(annotationId: AnnotationId): void;
+}
+
+type JobStatusResponse = components['schemas']['JobStatusResponse'];
+declare class JobNamespace implements JobNamespace$1 {
+    private readonly transport;
+    private readonly bus;
+    constructor(transport: ITransport, bus: EventBus);
+    /**
+     * Live stream of `job:queued` events. Surfaces a typed view onto the
+     * underlying bus channel for consumers (CLIs, MCP handlers, widgets)
+     * that orchestrate jobs and need to react to lifecycle transitions.
+     */
+    get queued$(): Observable<EventMap['job:queued']>;
+    /** Live stream of `job:report-progress` events. */
+    get progress$(): Observable<EventMap['job:report-progress']>;
+    /** Live stream of `job:complete` events. */
+    get complete$(): Observable<EventMap['job:complete']>;
+    /** Live stream of `job:fail` events. */
+    get fail$(): Observable<EventMap['job:fail']>;
+    status(jobId: JobId): Promise<JobStatusResponse>;
+    pollUntilComplete(jobId: JobId, options?: {
+        interval?: number;
+        timeout?: number;
+        onProgress?: (status: JobStatusResponse) => void;
+    }): Promise<JobStatusResponse>;
+    cancel(_jobId: JobId, type: string): Promise<void>;
+    cancelRequest(jobType: 'annotation' | 'generation'): void;
+}
+
+/**
+ * AuthNamespace — authentication. Pure wire, no bus.
+ */
+
+type AuthResponse = components['schemas']['AuthResponse'];
+type TokenRefreshResponse = components['schemas']['TokenRefreshResponse'];
+declare class AuthNamespace implements AuthNamespace$1 {
+    private readonly transport;
+    constructor(transport: ITransport);
+    password(emailStr: string, passwordStr: string): Promise<AuthResponse>;
+    google(credential: string): Promise<AuthResponse>;
+    refresh(token: string): Promise<TokenRefreshResponse>;
+    logout(): Promise<void>;
+    me(): Promise<User>;
+    acceptTerms(): Promise<void>;
+    mcpToken(): Promise<{
+        token: string;
+    }>;
+    mediaToken(resourceId: ResourceId): Promise<{
+        token: string;
+    }>;
+}
+
+/**
+ * AdminNamespace — administration. Pure wire, no bus.
+ */
+
+type AdminUserStatsResponse = components['schemas']['AdminUserStatsResponse'];
+type OAuthConfigResponse = components['schemas']['OAuthConfigResponse'];
+declare class AdminNamespace implements AdminNamespace$1 {
+    private readonly transport;
+    constructor(transport: ITransport);
+    users(): Promise<User[]>;
+    userStats(): Promise<AdminUserStatsResponse>;
+    updateUser(userId: UserDID, data: RequestContent<paths['/api/admin/users/{id}']['patch']>): Promise<User>;
+    oauthConfig(): Promise<OAuthConfigResponse>;
+    healthCheck(): Promise<ResponseContent<paths['/api/health']['get']>>;
+    status(): Promise<ResponseContent<paths['/api/status']['get']>>;
+    backup(): Promise<Response>;
+    restore(file: File, onProgress?: (event: {
+        phase: string;
+        message?: string;
+        result?: Record<string, unknown>;
+    }) => void): Promise<{
+        phase: string;
+        message?: string;
+        result?: Record<string, unknown>;
+    }>;
+    exportKnowledgeBase(params?: {
+        includeArchived?: boolean;
+    }): Promise<Response>;
+    importKnowledgeBase(file: File, onProgress?: (event: {
+        phase: string;
+        message?: string;
+        result?: Record<string, unknown>;
+    }) => void): Promise<{
+        phase: string;
+        message?: string;
+        result?: Record<string, unknown>;
+    }>;
+}
+
+declare class SemiontClient {
+    /**
+     * The wire-facing transport. Owns bus actor, HTTP, auth, admin, exchange,
+     * system. Exposed for advanced consumers (workers, custom job adapters)
+     * that need raw `transport.emit(channel, payload, scope)` access. Ordinary
+     * consumers go through typed namespace methods.
+     */
+    readonly transport: ITransport;
+    /** Binary I/O transport. */
+    private readonly content;
+    /**
+     * Per-client local EventBus. Wire events flow in via the transport
+     * bridge. Read-only public so `SemiontSession.subscribe(channel, …)`
+     * can wire arbitrary-channel subscriptions; everything else uses
+     * typed namespace methods.
+     */
+    readonly bus: EventBus;
+    readonly baseUrl: BaseUrl;
+    readonly browse: BrowseNamespace;
+    readonly mark: MarkNamespace;
+    readonly bind: BindNamespace;
+    readonly gather: GatherNamespace;
+    readonly match: MatchNamespace;
+    readonly yield: YieldNamespace;
+    readonly beckon: BeckonNamespace;
+    readonly job: JobNamespace;
+    readonly auth: AuthNamespace;
+    readonly admin: AdminNamespace;
+    /**
+     * The client *owns* its bus. The constructor creates a fresh `EventBus`
+     * and hands it to the transport via `transport.bridgeInto(this.bus)`.
+     * The reference flows client → transport, never the other way:
+     * the transport stores the reference and publishes the events it
+     * receives onto that bus. `HttpTransport` does so for every channel
+     * delivered on its SSE wire; in-process transports adapt their
+     * internal source.
+     *
+     * Callers do not pass a bus in. If they need to interact with the bus
+     * (e.g. for tests or to subscribe to arbitrary channels), they read it
+     * back via `client.bus`.
+     */
+    constructor(transport: ITransport, content: IContentTransport);
+    /** Transport-level connection state. HTTP reflects SSE health; local is always 'connected'. */
+    get state$(): rxjs.Observable<_semiont_core.ConnectionState>;
+    subscribeToResource(resourceId: ResourceId): () => void;
+    dispose(): void;
+}
+
+declare class BusRequestError extends Error {
+    constructor(message: string);
+}
+/**
+ * Subset of ITransport that `busRequest` needs: a way to send a command and
+ * a way to observe channels. Generic enough that an in-process transport
+ * can satisfy it without round-tripping through HTTP.
+ */
+interface BusRequestPrimitive {
+    emit<K extends keyof EventMap>(channel: K, payload: EventMap[K]): Promise<void>;
+    stream<K extends keyof EventMap>(channel: K): Observable<EventMap[K]>;
+}
+declare function busRequest<TResult>(bus: BusRequestPrimitive, 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
+ * SemiontClient, 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;
+    /**
+     * Pre-built api client. The session does not construct it — caller
+     * builds the transport stack and passes the client in. This is the
+     * seam where consumers swap one `ITransport` implementation for
+     * another (HTTP, in-process, etc.).
+     */
+    client: SemiontClient;
+    /**
+     * Token observable shared with the transport. Caller must pass the
+     * SAME instance to both the transport (via `HttpTransport` config)
+     * and the session. The session writes refreshed tokens here; the
+     * transport reads from here.
+     */
+    token$: BehaviorSubject<AccessToken | null>;
+    /**
+     * Re-authenticate after expiry / 401. Returns a new access token
+     * (no "Bearer " prefix) on success, or null if recovery is
+     * impossible. Omit for transports where tokens don't apply.
+     */
+    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: SemiontClient;
+    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;
+    /**
+     * Subscribe to a session-bus channel. The single sanctioned escape hatch
+     * for generic-channel subscription (the case `useEventSubscription` needs
+     * — channel name is a hook parameter, not known statically). All other
+     * consumers must call typed namespace methods (e.g. `session.client.mark.archive(...)`).
+     *
+     * @returns disposer that unsubscribes the handler.
+     */
+    subscribe<K extends keyof EventMap>(channel: K, handler: (payload: EventMap[K]) => void): () => void;
+    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 `SemiontClient`, 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 `SemiontClient` with no `tokenRefresher` —
+     * a refresh call returning 401 would otherwise re-enter this
+     * function infinitely.
+     */
+    private performRefresh;
+    /**
+     * Validate an access token by calling `auth.me` on a throwaway
+     * client. The session uses this once at startup to populate
+     * `user$`; 401 triggers a refresh-then-retry inside the session.
+     *
+     * The throwaway transport is seeded with the specific token to
+     * validate so the request actually carries it (HttpTransport
+     * sources `Authorization` from its `token$`).
+     */
+    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;
+
+interface ViewModel {
+    dispose(): void;
+}
+declare function createDisposer(): {
+    add(vm: ViewModel | (() => void)): void;
+    dispose(): 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<AnnotationId | null>;
+    hover(annotationId: AnnotationId | null): void;
+    focus(annotationId: AnnotationId): void;
+    sparkle(annotationId: AnnotationId): void;
+}
+declare function createBeckonVM(client: SemiontClient): BeckonVM;
+/** Default milliseconds the mouse must dwell before beckon:hover is emitted. */
+declare const HOVER_DELAY_MS = 150;
+type EmitHover = (annotationId: AnnotationId | null) => void;
+interface HoverHandlers {
+    handleMouseEnter: (annotationId: AnnotationId) => 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: SemiontClient, resourceId: ResourceId): GatherVM;
+
+interface MatchVM extends ViewModel {
+}
+declare function createMatchVM(client: SemiontClient, _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: SemiontClient, 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: SemiontClient, resourceId: ResourceId): MarkVM;
+
+interface DiscoverVM extends ViewModel {
+    browse: ShellVM;
+    search: SearchPipeline<ResourceDescriptor>;
+    recentResources$: Observable<ResourceDescriptor[]>;
+    entityTypes$: Observable<string[]>;
+    isLoadingRecent$: Observable<boolean>;
+}
+declare function createDiscoverVM(client: SemiontClient, 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: SemiontClient, 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: SemiontClient, browse: ShellVM): AdminUsersVM;
+
+interface AdminSecurityVM extends ViewModel {
+    browse: ShellVM;
+    providers$: Observable<unknown[]>;
+    allowedDomains$: Observable<string[]>;
+    isLoading$: Observable<boolean>;
+}
+declare function createAdminSecurityVM(client: SemiontClient, browse: ShellVM): AdminSecurityVM;
+
+interface WelcomeVM extends ViewModel {
+    userData$: Observable<{
+        termsAcceptedAt?: string;
+    } | null>;
+    isProcessing$: Observable<boolean>;
+    acceptTerms(): Promise<void>;
+}
+declare function createWelcomeVM(client: SemiontClient): WelcomeVM;
+
+interface ResourceLoaderVM extends ViewModel {
+    resource$: Observable<ResourceDescriptor | undefined>;
+    isLoading$: Observable<boolean>;
+    invalidate(): void;
+}
+declare function createResourceLoaderVM(client: SemiontClient, resourceId: ResourceId): ResourceLoaderVM;
+
+interface SessionVM extends ViewModel {
+    isLoggingOut$: Observable<boolean>;
+    logout(): Promise<void>;
+}
+declare function createSessionVM(client: SemiontClient): 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 `SemiontClient` 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;
+    /** DID of the user who initiated the job (audit). */
+    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: SemiontClient): JobQueueVM;
+
+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: SemiontClient, resourceId: ResourceId, locale: string, browse: ShellVM, options?: {
+    mediaType?: string;
+}): ResourceViewerPageVM;
+
+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: SemiontClient, browse: ShellVM, params: ComposeParams, auth?: AccessToken): ComposePageVM;
+
+export { type ActiveJob, AdminNamespace, type AdminSecurityVM, type AdminUsersVM, type AnnotationGroups, type AnnotationHistoryResponse, AuthNamespace, BeckonNamespace, type BeckonVM, BindNamespace, BrowseNamespace, BusRequestError, type BusRequestPrimitive, COMMON_PANELS, type Cache, type CloneData, type ComposeMode, type ComposePageVM, type ComposeParams, type CreateAnnotationInput, type CreateFromTokenOptions, type CreateResourceInput, 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 MarkAssistEvent, type MarkAssistOptions, type MarkAssistProgress, MarkNamespace, type MarkVM, MatchNamespace, type MatchSearchProgress, type MatchVM, type NewKnowledgeBase, type OpenResource, type PendingAnnotation, RESOURCE_PANELS, type ReferenceData, type ReferencedByEntry, type RequestContent, type ResourceLoaderVM, type ResourceViewerPageVM, type ResponseContent, type SaveResourceParams, type SearchPipeline, type SearchPipelineOptions, type SearchState, SemiontBrowser, type SemiontBrowserConfig, SemiontClient, SemiontError, type SemiontErrorCode, SemiontSession, type SemiontSessionConfig, type SessionStorage, type SessionVM, type ShellVM, type ShellVMOptions, type SmelterActorVM, type SmelterActorVMOptions, type SmelterEvent, type StoredSession, type ToolbarPanelType, type User, type UserInfo, type ViewModel, type WelcomeVM, type WizardState, type YieldGenerationEvent, YieldNamespace, type YieldVM, busRequest, 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, isValidHostname, kbBackendUrl, notifyPermissionDenied, notifySessionExpired, setStoredSession };