@semiont/sdk 0.5.0 → 0.5.2

package/dist/index.d.ts

@@ -1,31 +1,142 @@
 import * as rxjs from 'rxjs';
 import { Observable, BehaviorSubject, Subject } from 'rxjs';
+export { firstValueFrom, lastValueFrom } 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';
+import { ResourceId, components, UserDID, paths, BackendDownload, ProgressEvent, AnnotationId, BodyOperation, EventMap, ResourceDescriptor, Annotation, GraphConnection, Motivation, GatheredContext, JobId, ITransport, EventBus, IContentTransport, IBackendOperations, BaseUrl, AccessToken, SemiontError, ConnectionState, Selector } from '@semiont/core';
+export { AccessToken, Annotation, AnnotationId, BaseUrl, BodyItem, BodyOperation, ConnectionState, EntityType, EventMap, GatheredContext, IContentTransport, ITransport, Logger, Motivation, RefreshToken, ResourceDescriptor, ResourceId, SemiontError, UserId, accessToken, annotationId, baseUrl, entityType, refreshToken, resourceId, userId } from '@semiont/core';
+export { APIError, HttpContentTransport, HttpTransport, HttpTransportConfig, TokenRefresher } from '@semiont/api-client';
+
+/**
+ * Thenable Observable subclasses.
+ *
+ * Two thin Observable subclasses that also implement `PromiseLike<T>`. Used as
+ * the public return type of namespace methods that emit streams (job
+ * lifecycle, generation progress) and cache reads (Browse live queries).
+ *
+ * The point: scripts can `await` the call directly without `lastValueFrom` /
+ * `firstValueFrom` wrappers; reactive consumers keep using `.subscribe(...)`
+ * and `.pipe(...)` exactly as before.
+ *
+ * The asymmetric `.then()` semantics — last-value-on-completion for streams,
+ * first-non-undefined-value for caches — is encoded by the subclass name. The
+ * docstring on the namespace method tells the consumer which one applies.
+ *
+ * `.pipe(...)` returns a plain `Observable<T>` (RxJS doesn't propagate
+ * subclasses through `pipe`). Once you compose, you've explicitly entered
+ * RxJS land; `lastValueFrom` from `rxjs` is the right bridge there.
+ */
+
+/**
+ * Bounded Observable stream — emits zero-or-more progress values, then a
+ * final value on completion. Used by job-lifecycle methods like
+ * `mark.assist`, `gather.annotation`, `match.search`, `yield.fromAnnotation`.
+ *
+ * Awaiting resolves to the **last** emitted value (via `lastValueFrom`).
+ * Subscribing yields every emission, ending in `complete`.
+ */
+declare class StreamObservable<T> extends Observable<T> implements PromiseLike<T> {
+    then<R1 = T, R2 = never>(onfulfilled?: ((v: T) => R1 | PromiseLike<R1>) | null, onrejected?: ((e: unknown) => R2 | PromiseLike<R2>) | null): PromiseLike<R1 | R2>;
+    /** Wrap an existing Observable's subscribe behavior in a StreamObservable. */
+    static from<T>(source: Observable<T>): StreamObservable<T>;
+}
+/**
+ * Multicast cache observable — emits `undefined` while the underlying value
+ * is loading, then the value, then re-emits when bus events invalidate the
+ * cache entry. Used by Browse live-query methods (`browse.resource`,
+ * `browse.annotations`, etc.).
+ *
+ * Awaiting resolves to the **first non-undefined** value (waits past the
+ * loading state). Subscribing yields the full sequence including the
+ * initial `undefined`, so reactive consumers can render a loading state.
+ *
+ * The class is parameterized as `CacheObservable<T>` even though the
+ * stream's element type is `T | undefined` — `T` is what the consumer
+ * gets from `await`, and that's the contract we want to advertise. The
+ * `Observable<T | undefined>` shape leaks through `.subscribe` and
+ * `.pipe` in the natural way.
+ */
+declare class CacheObservable<T> extends Observable<T | undefined> implements PromiseLike<T> {
+    then<R1 = T, R2 = never>(onfulfilled?: ((v: T) => R1 | PromiseLike<R1>) | null, onrejected?: ((e: unknown) => R2 | PromiseLike<R2>) | null): PromiseLike<R1 | R2>;
+    /**
+     * Wrap an existing Observable's subscribe behavior in a `CacheObservable`.
+     *
+     * Memoizes on source identity: passing the same `source` returns the same
+     * wrapper instance. The Browse cache primitive already returns a stable
+     * Observable per key (its B4 contract), so this preserves that contract
+     * through the awaitable wrapping. Without the memo, every public-method
+     * call would produce a fresh wrapper and break referential-equality
+     * guarantees that hook-style reactive consumers depend on.
+     *
+     * Backed by a `WeakMap`, so wrappers are GC'd when their source is.
+     */
+    static from<T>(source: Observable<T | undefined>): CacheObservable<T>;
+}
+/**
+ * Discriminated phases of an upload's lifecycle.
+ *
+ * - `started` — emitted immediately on `yield.resource(...)` invocation, before any bytes flow.
+ * - `progress` — emitted as bytes flow over the wire. Wired by `HttpContentTransport`'s XHR path when a caller passes `onProgress` (or, transitively, when `yield.resource` is the caller — it always wires the hook so subscribers see byte counts). `bytesUploaded` and `totalBytes` carry the running counts; `totalBytes` may be 0 when the transport can't determine the total (rare, e.g. chunked encoding) — UI consumers should render an indeterminate state in that case.
+ * - `finished` — emitted on backend acknowledgement, carries the assigned `resourceId`.
+ *
+ * Failures surface as `Observable.error(...)` (typically an `APIError` from the transport's `errors$` Subject), not as a `phase: 'failed'` event — `subscribe`'s error callback handles them. Cancellation is honored: unsubscribing before `finished` aborts the in-flight HTTP request on the XHR path.
+ */
+type UploadProgress = {
+    phase: 'started';
+    totalBytes: number;
+} | {
+    phase: 'progress';
+    bytesUploaded: number;
+    totalBytes: number;
+} | {
+    phase: 'finished';
+    resourceId: ResourceId;
+};
+/**
+ * Specialized `StreamObservable` for `yield.resource`. Subscribers see the
+ * full `UploadProgress` event sequence (started → optional progress → finished).
+ * Awaiting resolves specifically to `{ resourceId }` extracted from the
+ * `'finished'` event — preserving the pre-Phase-18 awaited shape so existing
+ * `await client.yield.resource(...)` callers don't need to narrow the union.
+ */
+declare class UploadObservable extends Observable<UploadProgress> implements PromiseLike<{
+    resourceId: ResourceId;
+}> {
+    then<R1 = {
+        resourceId: ResourceId;
+    }, R2 = never>(onfulfilled?: ((v: {
+        resourceId: ResourceId;
+    }) => R1 | PromiseLike<R1>) | null, onrejected?: ((e: unknown) => R2 | PromiseLike<R2>) | null): PromiseLike<R1 | R2>;
+}
 
 /**
  * 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).
+ * These interfaces define the public API of `@semiont/sdk`, 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.
+ * 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
+ * client 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
+ * - Browse live queries → `CacheObservable<T>` (bus-driven, cached;
+ *   subscribe yields `T | undefined`, await yields `T` after first load)
+ * - Browse one-shot reads → `Promise<T>` (fetch once, no cache)
+ * - Commands (mark, bind, yield.resource) → `Promise<T>` (atomic ops)
+ * - Long-running ops (gather, match, yield.fromAnnotation, mark.assist)
+ *   → `StreamObservable<T>` (progress + result; subscribe yields every
+ *   emit, await yields the last one)
+ * - Ephemeral signals (beckon) → `void`
+ *
+ * `StreamObservable` and `CacheObservable` are `Observable` subclasses
+ * that also implement `PromiseLike<T>` — `await client.X.Y(...)` works
+ * directly without `lastValueFrom`/`firstValueFrom` wrappers.
+ * `.pipe(...)` returns a plain `Observable<T>` (the thenable subclass
+ * does not propagate through pipe — by design).
  */
 
-type StoredEventResponse$2 = components['schemas']['StoredEventResponse'];
+type StoredEventResponse$1 = components['schemas']['StoredEventResponse'];
 type GatherProgress = components['schemas']['GatherProgress'];
 type MatchSearchResult = components['schemas']['MatchSearchResult'];
 type JobProgress$2 = components['schemas']['JobProgress'];
@@ -92,7 +203,10 @@ interface GenerationOptions {
     storageUri: string;
     context: GatheredContext;
     prompt?: string;
+    /** Annotation/resource body locale — language the generated resource is written in (typically the user's UI locale). */
     language?: string;
+    /** Source-resource locale — language of the resource the annotation lives on, used in the prompt so the LLM understands embedded source-context snippets. BCP-47. */
+    sourceLanguage?: string;
     temperature?: number;
     maxTokens?: number;
 }
@@ -103,7 +217,10 @@ interface MarkAssistOptions {
     instructions?: string;
     density?: number;
     tone?: string;
+    /** Annotation body locale — language the LLM should write generated body text in (comment text, assessment text, tag/reference body language stamp). BCP-47. */
     language?: string;
+    /** Source-resource locale — language of the content being analyzed, used in the prompt so the LLM analyzes non-English source correctly. BCP-47. */
+    sourceLanguage?: string;
     schemaId?: string;
     categories?: string[];
 }
@@ -171,17 +288,17 @@ type YieldGenerationEvent = {
  * Event prefix: browse:*
  */
 interface BrowseNamespace$1 {
-    resource(resourceId: ResourceId): Observable<ResourceDescriptor | undefined>;
+    resource(resourceId: ResourceId): CacheObservable<ResourceDescriptor>;
     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>;
+    }): CacheObservable<ResourceDescriptor[]>;
+    annotations(resourceId: ResourceId): CacheObservable<Annotation[]>;
+    annotation(resourceId: ResourceId, annotationId: AnnotationId): CacheObservable<Annotation>;
+    entityTypes(): CacheObservable<string[]>;
+    referencedBy(resourceId: ResourceId): CacheObservable<ReferencedByEntry[]>;
+    events(resourceId: ResourceId): CacheObservable<StoredEventResponse$1[]>;
     resourceContent(resourceId: ResourceId): Promise<string>;
     resourceRepresentation(resourceId: ResourceId, options?: {
         accept?: string;
@@ -195,7 +312,7 @@ interface BrowseNamespace$1 {
         stream: ReadableStream<Uint8Array>;
         contentType: string;
     }>;
-    resourceEvents(resourceId: ResourceId): Promise<StoredEventResponse$2[]>;
+    resourceEvents(resourceId: ResourceId): Promise<StoredEventResponse$1[]>;
     annotationHistory(resourceId: ResourceId, annotationId: AnnotationId): Promise<AnnotationHistoryResponse>;
     connections(resourceId: ResourceId): Promise<GraphConnection[]>;
     backlinks(resourceId: ResourceId): Promise<Annotation[]>;
@@ -205,7 +322,33 @@ interface BrowseNamespace$1 {
     navigateReference(resourceId: ResourceId): void;
 }
 /**
- * Mark — annotation CRUD, entity types, AI assist
+ * Frame — schema-layer flow (the eighth flow).
+ *
+ * Frame operates on the KB's conceptual vocabulary — what *kinds* of
+ * things exist (entity types) and, in the future, what taxonomies are
+ * recognized (tag schemas), what relations are typed (predicate types),
+ * and how schemas are imported (ontology I/O). The other seven flows
+ * (yield, mark, match, bind, gather, browse, beckon) operate on
+ * content; Frame operates on the schema layer that content is expressed
+ * in.
+ *
+ * MVP scope is small: entity-type vocabulary writes only. Live reads of
+ * the entity-type vocabulary stay on Browse (`browse.entityTypes()` is
+ * a `CacheObservable<string[]>` consumed by 8+ call sites). Frame owns
+ * writes; Browse owns reads — the same asymmetry that already holds for
+ * resources and annotations.
+ *
+ * Backend actor: Stower
+ * Event prefix: frame:*
+ */
+interface FrameNamespace$1 {
+    /** Add a single entity type to the KB's vocabulary. Idempotent — adding an existing type is a no-op. */
+    addEntityType(type: string): Promise<void>;
+    /** Add multiple entity types in one call. Convenience over a loop of `addEntityType`. */
+    addEntityTypes(types: string[]): Promise<void>;
+}
+/**
+ * Mark — annotation CRUD, AI assist, resource lifecycle
  *
  * Commands return Promises that resolve on HTTP acceptance (202).
  * Results appear on browse Observables via bus gateway.
@@ -215,17 +358,15 @@ interface BrowseNamespace$1 {
  * Event prefix: mark:*
  */
 interface MarkNamespace$1 {
-    annotation(resourceId: ResourceId, input: CreateAnnotationInput): Promise<{
-        annotationId: string;
+    annotation(input: CreateAnnotationInput): Promise<{
+        annotationId: AnnotationId;
     }>;
     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>;
+    assist(resourceId: ResourceId, motivation: Motivation, options: MarkAssistOptions): StreamObservable<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. */
+    /** Fire-and-forget variant of `assist` — mark-state-unit 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;
@@ -263,12 +404,12 @@ interface BindNamespace$1 {
  * Event prefix: gather:*
  */
 interface GatherNamespace$1 {
-    annotation(annotationId: AnnotationId, resourceId: ResourceId, options?: {
+    annotation(resourceId: ResourceId, annotationId: AnnotationId, options?: {
         contextWindow?: number;
-    }): Observable<GatherAnnotationProgress>;
+    }): StreamObservable<GatherAnnotationProgress>;
     resource(resourceId: ResourceId, options?: {
         contextWindow?: number;
-    }): Observable<GatherAnnotationProgress>;
+    }): StreamObservable<GatherAnnotationProgress>;
 }
 /**
  * Match — search and ranking
@@ -280,11 +421,11 @@ interface GatherNamespace$1 {
  * Event prefix: match:*
  */
 interface MatchNamespace$1 {
-    search(resourceId: ResourceId, referenceId: string, context: GatheredContext, options?: {
+    search(resourceId: ResourceId, referenceId: AnnotationId, context: GatheredContext, options?: {
         limit?: number;
         useSemanticScoring?: boolean;
-    }): Observable<MatchSearchProgress>;
-    /** Fire-and-forget variant: match-vm orchestrates the call and its result Observable. */
+    }): StreamObservable<MatchSearchProgress>;
+    /** Fire-and-forget variant: match-state-unit orchestrates the call and its result Observable. */
     requestSearch(input: components['schemas']['MatchSearchRequest']): void;
 }
 /**
@@ -297,17 +438,15 @@ interface MatchNamespace$1 {
  * Event prefix: yield:*
  */
 interface YieldNamespace$1 {
-    resource(data: CreateResourceInput): Promise<{
-        resourceId: string;
-    }>;
-    fromAnnotation(resourceId: ResourceId, annotationId: AnnotationId, options: GenerationOptions): Observable<YieldGenerationEvent>;
+    resource(data: CreateResourceInput): UploadObservable;
+    fromAnnotation(resourceId: ResourceId, annotationId: AnnotationId, options: GenerationOptions): StreamObservable<YieldGenerationEvent>;
     cloneToken(resourceId: ResourceId): Promise<{
         token: string;
         expiresAt: string;
     }>;
     fromToken(token: string): Promise<ResourceDescriptor>;
     createFromToken(options: CreateFromTokenOptions): Promise<{
-        resourceId: string;
+        resourceId: ResourceId;
     }>;
     /** UI signal: user invoked the clone action from the resource-info panel. */
     clone(): void;
@@ -322,7 +461,7 @@ interface YieldNamespace$1 {
  * Event prefix: beckon:*
  */
 interface BeckonNamespace$1 {
-    attention(annotationId: AnnotationId, resourceId: ResourceId): void;
+    attention(resourceId: ResourceId, annotationId: AnnotationId): void;
     hover(annotationId: AnnotationId | null): void;
     sparkle(annotationId: AnnotationId): void;
 }
@@ -344,7 +483,7 @@ interface JobNamespace$1 {
         timeout?: number;
         onProgress?: (status: JobStatusResponse$1) => void;
     }): Promise<JobStatusResponse$1>;
-    cancel(jobId: JobId, type: string): Promise<void>;
+    cancelByType(jobType: 'annotation' | 'generation'): Promise<void>;
     /** UI signal: cancel all active jobs of a given type (e.g. "annotation"). */
     cancelRequest(jobType: 'annotation' | 'generation'): void;
 }
@@ -375,31 +514,21 @@ interface AdminNamespace$1 {
     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>;
-    }>;
+    backup(): Promise<BackendDownload>;
+    /**
+     * Restore from a backup archive. Returns a `StreamObservable` that
+     * emits each `ProgressEvent` as the operation runs (`'started'`,
+     * `'parsing'`, `'importing'`, ..., `'complete'`). Subscribers see
+     * every step; awaiters get the final event via the PromiseLike sugar.
+     */
+    restore(file: File): StreamObservable<ProgressEvent>;
     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>;
-    }>;
+    }): Promise<BackendDownload>;
+    importKnowledgeBase(file: File): StreamObservable<ProgressEvent>;
 }
 
-type StoredEventResponse$1 = components['schemas']['StoredEventResponse'];
+type StoredEventResponse = components['schemas']['StoredEventResponse'];
 type ResourceListFilters = {
     limit?: number;
     archived?: boolean;
@@ -437,13 +566,13 @@ declare class BrowseNamespace implements BrowseNamespace$1 {
      */
     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>;
+    resource(resourceId: ResourceId): CacheObservable<ResourceDescriptor>;
+    resources(filters?: ResourceListFilters): CacheObservable<ResourceDescriptor[]>;
+    annotations(resourceId: ResourceId): CacheObservable<Annotation[]>;
+    annotation(resourceId: ResourceId, annotationId: AnnotationId): CacheObservable<Annotation>;
+    entityTypes(): CacheObservable<string[]>;
+    referencedBy(resourceId: ResourceId): CacheObservable<ReferencedByEntry[]>;
+    events(resourceId: ResourceId): CacheObservable<StoredEventResponse[]>;
     resourceContent(resourceId: ResourceId): Promise<string>;
     resourceRepresentation(resourceId: ResourceId, options?: {
         accept?: string;
@@ -457,7 +586,7 @@ declare class BrowseNamespace implements BrowseNamespace$1 {
         stream: ReadableStream<Uint8Array>;
         contentType: string;
     }>;
-    resourceEvents(resourceId: ResourceId): Promise<StoredEventResponse$1[]>;
+    resourceEvents(resourceId: ResourceId): Promise<StoredEventResponse[]>;
     annotationHistory(resourceId: ResourceId, annotationId: AnnotationId): Promise<AnnotationHistoryResponse>;
     connections(_resourceId: ResourceId): Promise<GraphConnection[]>;
     backlinks(_resourceId: ResourceId): Promise<Annotation[]>;
@@ -506,15 +635,13 @@ 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;
+    annotation(input: CreateAnnotationInput): Promise<{
+        annotationId: AnnotationId;
     }>;
     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>;
+    assist(resourceId: ResourceId, motivation: Motivation, options: MarkAssistOptions): StreamObservable<MarkAssistEvent>;
     request(selector: components['schemas']['MarkRequestedEvent']['selector'], motivation: Motivation): void;
     requestAssist(motivation: Motivation, options: MarkAssistOptions, correlationId?: string): void;
     submit(input: components['schemas']['MarkSubmitEvent']): void;
@@ -539,12 +666,12 @@ declare class GatherNamespace implements GatherNamespace$1 {
     private readonly transport;
     private readonly bus;
     constructor(transport: ITransport, bus: EventBus);
-    annotation(annotationId: AnnotationId, resourceId: ResourceId, options?: {
+    annotation(resourceId: ResourceId, annotationId: AnnotationId, options?: {
         contextWindow?: number;
-    }): Observable<GatherAnnotationProgress>;
+    }): StreamObservable<GatherAnnotationProgress>;
     resource(_resourceId: ResourceId, _options?: {
         contextWindow?: number;
-    }): Observable<GatherAnnotationProgress>;
+    }): StreamObservable<GatherAnnotationProgress>;
 }
 
 declare class MatchNamespace implements MatchNamespace$1 {
@@ -552,10 +679,10 @@ declare class MatchNamespace implements MatchNamespace$1 {
     private readonly bus;
     constructor(transport: ITransport, bus: EventBus);
     requestSearch(input: components['schemas']['MatchSearchRequest']): void;
-    search(resourceId: ResourceId, referenceId: string, context: GatheredContext, options?: {
+    search(resourceId: ResourceId, referenceId: AnnotationId, context: GatheredContext, options?: {
         limit?: number;
         useSemanticScoring?: boolean;
-    }): Observable<MatchSearchProgress>;
+    }): StreamObservable<MatchSearchProgress>;
 }
 
 declare class YieldNamespace implements YieldNamespace$1 {
@@ -563,17 +690,15 @@ declare class YieldNamespace implements YieldNamespace$1 {
     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>;
+    resource(data: CreateResourceInput): UploadObservable;
+    fromAnnotation(resourceId: ResourceId, annotationId: AnnotationId, options: GenerationOptions): StreamObservable<YieldGenerationEvent>;
     cloneToken(resourceId: ResourceId): Promise<{
         token: string;
         expiresAt: string;
     }>;
     fromToken(token: string): Promise<ResourceDescriptor>;
     createFromToken(options: CreateFromTokenOptions): Promise<{
-        resourceId: string;
+        resourceId: ResourceId;
     }>;
     clone(): void;
 }
@@ -582,11 +707,38 @@ declare class BeckonNamespace implements BeckonNamespace$1 {
     private readonly transport;
     private readonly bus;
     constructor(transport: ITransport, bus: EventBus);
-    attention(annotationId: AnnotationId, resourceId: ResourceId): void;
+    attention(resourceId: ResourceId, annotationId: AnnotationId): void;
     hover(annotationId: AnnotationId | null): void;
     sparkle(annotationId: AnnotationId): void;
 }
 
+/**
+ * FrameNamespace — the eighth flow's surface.
+ *
+ * Frame operates on the KB's **schema layer** — the conceptual vocabulary
+ * the other seven flows are expressed in. Where yield/mark/match/bind/
+ * gather/browse/beckon act on content (resources, annotations, references,
+ * attention), Frame acts on what *kinds* of things exist: entity types,
+ * eventually tag schemas, relation/predicate types, ontology imports.
+ *
+ * The MVP owns a single primitive — entity-type vocabulary writes on the
+ * `frame:add-entity-type` channel. See `docs/protocol/flows/FRAME.md`
+ * for the per-flow contract.
+ *
+ * Live reads of the entity-type vocabulary stay on Browse
+ * (`browse.entityTypes()` is a `CacheObservable<string[]>`). Frame owns
+ * writes; Browse owns reads. The asymmetry is intentional — re-implementing
+ * Browse's cache primitives on Frame for a single read would duplicate
+ * machinery without benefit.
+ */
+
+declare class FrameNamespace implements FrameNamespace$1 {
+    private readonly transport;
+    constructor(transport: ITransport);
+    addEntityType(type: string): Promise<void>;
+    addEntityTypes(types: string[]): Promise<void>;
+}
+
 type JobStatusResponse = components['schemas']['JobStatusResponse'];
 declare class JobNamespace implements JobNamespace$1 {
     private readonly transport;
@@ -610,19 +762,19 @@ declare class JobNamespace implements JobNamespace$1 {
         timeout?: number;
         onProgress?: (status: JobStatusResponse) => void;
     }): Promise<JobStatusResponse>;
-    cancel(_jobId: JobId, type: string): Promise<void>;
+    cancelByType(jobType: 'annotation' | 'generation'): Promise<void>;
     cancelRequest(jobType: 'annotation' | 'generation'): void;
 }
 
 /**
- * AuthNamespace — authentication. Pure wire, no bus.
+ * AuthNamespace — authentication. Backend ops only; no bus.
  */
 
 type AuthResponse = components['schemas']['AuthResponse'];
 type TokenRefreshResponse = components['schemas']['TokenRefreshResponse'];
 declare class AuthNamespace implements AuthNamespace$1 {
-    private readonly transport;
-    constructor(transport: ITransport);
+    private readonly backend;
+    constructor(backend: IBackendOperations);
     password(emailStr: string, passwordStr: string): Promise<AuthResponse>;
     google(credential: string): Promise<AuthResponse>;
     refresh(token: string): Promise<TokenRefreshResponse>;
@@ -638,42 +790,26 @@ declare class AuthNamespace implements AuthNamespace$1 {
 }
 
 /**
- * AdminNamespace — administration. Pure wire, no bus.
+ * AdminNamespace — administration. Backend ops only; no bus.
  */
 
 type AdminUserStatsResponse = components['schemas']['AdminUserStatsResponse'];
 type OAuthConfigResponse = components['schemas']['OAuthConfigResponse'];
 declare class AdminNamespace implements AdminNamespace$1 {
-    private readonly transport;
-    constructor(transport: ITransport);
+    private readonly backend;
+    constructor(backend: IBackendOperations);
     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>;
-    }>;
+    backup(): Promise<BackendDownload>;
+    restore(file: File): StreamObservable<ProgressEvent>;
     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>;
-    }>;
+    }): Promise<BackendDownload>;
+    importKnowledgeBase(file: File): StreamObservable<ProgressEvent>;
 }
 
 declare class SemiontClient {
@@ -694,6 +830,7 @@ declare class SemiontClient {
      */
     readonly bus: EventBus;
     readonly baseUrl: BaseUrl;
+    readonly frame: FrameNamespace;
     readonly browse: BrowseNamespace;
     readonly mark: MarkNamespace;
     readonly bind: BindNamespace;
@@ -702,8 +839,8 @@ declare class SemiontClient {
     readonly yield: YieldNamespace;
     readonly beckon: BeckonNamespace;
     readonly job: JobNamespace;
-    readonly auth: AuthNamespace;
-    readonly admin: AdminNamespace;
+    readonly auth: AuthNamespace | undefined;
+    readonly admin: AdminNamespace | undefined;
     /**
      * The client *owns* its bus. The constructor creates a fresh `EventBus`
      * and hands it to the transport via `transport.bridgeInto(this.bus)`.
@@ -716,16 +853,78 @@ declare class SemiontClient {
      * 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`.
+     *
+     * `backend` is optional. When provided, the `auth` and `admin`
+     * namespaces are constructed against it; when omitted, they're
+     * `undefined`. For HTTP setups this is conventionally the same
+     * `HttpTransport` instance that's also passed as `transport` (HTTP
+     * implements both `ITransport` and `IBackendOperations`).
      */
-    constructor(transport: ITransport, content: IContentTransport);
+    constructor(transport: ITransport, content: IContentTransport, backend?: IBackendOperations);
     /** 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;
+    /**
+     * Convenience factory for the default HTTP setup. Constructs a
+     * `BehaviorSubject<AccessToken | null>` internally, plus an
+     * `HttpTransport` and `HttpContentTransport`, and returns the wired
+     * `SemiontClient`.
+     *
+     * Use this for one-shot scripts, CLI commands, or any consumer that
+     * doesn't need to drive the token from outside (no manual refresh,
+     * no cross-tab sync). For long-running scripts that need refresh,
+     * use `SemiontSession.fromHttp(...)` (with a token already on hand)
+     * or `SemiontSession.signInHttp(...)` (credentials-first) instead —
+     * either owns the same transport/client wiring plus the
+     * proactive-refresh + storage machinery.
+     *
+     * Strings are accepted for `baseUrl` and `token`; they are branded
+     * via `baseUrl()` / `accessToken()` from `@semiont/core` automatically.
+     * Pass the already-branded values if you have them.
+     *
+     * Omit `token` for unauthenticated usage (public endpoints only).
+     */
+    static fromHttp(opts: {
+        baseUrl: BaseUrl | string;
+        token?: AccessToken | string | null;
+    }): SemiontClient;
+    /**
+     * Async factory for the credentials-first script case. Builds a
+     * transient HTTP transport, calls `auth.password(email, password)`
+     * to acquire an access token, and returns the wired client with
+     * the token populated.
+     *
+     * This is the right entry point for skills, CLI scripts, and any
+     * consumer that starts with email + password rather than a JWT
+     * already on hand. For consumers that already hold a token (CLI
+     * cached-token path, env-var token, embedded auth flow), use
+     * `fromHttp({ baseUrl, token })` instead.
+     *
+     * For long-running scripts that need refresh, use
+     * `SemiontSession.signInHttp(...)` — same credentials shape, plus
+     * the session machinery for proactive refresh and persistence.
+     *
+     * Named `signInHttp` because email+password authentication is
+     * inherently an HTTP-shaped operation in the current backend; an
+     * in-process `LocalTransport` doesn't have a credentials login
+     * path. Non-HTTP transports construct the client directly from
+     * their package's transport instance.
+     *
+     * Throws if authentication fails. The transient client is disposed
+     * before the throw, so no resources leak on failure.
+     */
+    static signInHttp(opts: {
+        baseUrl: BaseUrl | string;
+        email: string;
+        password: string;
+    }): Promise<SemiontClient>;
 }
 
-declare class BusRequestError extends Error {
-    constructor(message: string);
+type BusRequestErrorCode = 'bus.timeout' | 'bus.rejected' | 'bus.bad-payload' | 'bus.unauthorized' | 'bus.forbidden' | 'bus.not-found';
+declare class BusRequestError extends SemiontError {
+    code: BusRequestErrorCode;
+    constructor(message: string, code: BusRequestErrorCode, details?: Record<string, unknown>);
 }
 /**
  * Subset of ITransport that `busRequest` needs: a way to send a command and
@@ -739,76 +938,49 @@ interface BusRequestPrimitive {
 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.
+ * KnowledgeBase — a connection to a Semiont knowledge system.
+ *
+ * The KB type itself is uniform. The transport-shape variation lives in
+ * the nested `endpoint` field, which is a discriminated union:
+ *
+ *  - `endpoint.kind === 'http'`  — a remote backend reached over HTTP+SSE.
+ *                                  Carries `host`/`port`/`protocol`.
+ *  - `endpoint.kind === 'local'` — an in-process knowledge system reached
+ *                                  via `LocalTransport` from
+ *                                  `@semiont/make-meaning`. Carries an
+ *                                  opaque `kbId` identifying the local
+ *                                  instance to the host process.
  *
- * 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.
+ * Code that doesn't know how to make a transport (`SemiontSession`,
+ * `SemiontBrowser`, the frontend KB list UI) treats `KnowledgeBase` as
+ * uniform and never inspects `endpoint`. Code that *does* construct
+ * transports (the transport-factory passed to `SemiontBrowser`,
+ * `kbBackendUrl` for HTTP URL construction) inspects `endpoint.kind`
+ * and dispatches.
+ *
+ * Each KB has its own session, its own credentials (where applicable),
+ * and its own JWT (HTTP only). The user is "authenticated against KB X" —
+ * never globally authenticated.
  */
+/** Fields shared by every KB regardless of endpoint kind. */
 interface KnowledgeBase {
     id: string;
     label: string;
+    email: string;
+    gitBranch?: string;
+    endpoint: KbEndpoint;
+}
+type KbEndpoint = HttpEndpoint | LocalEndpoint;
+interface HttpEndpoint {
+    kind: 'http';
     host: string;
     port: number;
     protocol: 'http' | 'https';
-    email: string;
-    gitBranch?: string;
+}
+interface LocalEndpoint {
+    kind: 'local';
+    /** Opaque identifier for the in-process KB instance the host has loaded. */
+    kbId: string;
 }
 /**
  * Input shape for adding a new KB. The id is generated by the provider.
@@ -819,18 +991,63 @@ type NewKnowledgeBase = Omit<KnowledgeBase, 'id'>;
  * presence and validity of the JWT in session storage.
  */
 type KbSessionStatus = 'authenticated' | 'expired' | 'signed-out' | 'unreachable';
+/**
+ * Construct a `KnowledgeBase` for an HTTP-backed Semiont backend without
+ * spelling out the nested `endpoint` literal. Convenience for tests,
+ * worker bootstraps, and one-off scripts.
+ *
+ * ```ts
+ * const kb = httpKb({
+ *   id: 'my-watcher',
+ *   label: 'My Watcher',
+ *   email: 'me@example.com',
+ *   host: 'localhost',
+ *   port: 4000,
+ *   protocol: 'http',
+ * });
+ * ```
+ *
+ * Equivalent to:
+ *
+ * ```ts
+ * const kb: KnowledgeBase = {
+ *   id, label, email,
+ *   endpoint: { kind: 'http', host, port, protocol },
+ * };
+ * ```
+ *
+ * UI hosts that have a structured form (host / port / protocol pickers)
+ * already construct the literal directly — they don't need this helper.
+ * Local-endpoint KBs construct the literal directly too; the local
+ * endpoint shape (`{ kind: 'local', kbId }`) is one line and doesn't
+ * earn a helper.
+ */
+declare function httpKb(opts: {
+    id: string;
+    label: string;
+    email: string;
+    host: string;
+    port: number;
+    protocol: 'http' | 'https';
+    gitBranch?: string;
+}): KnowledgeBase;
 
 /**
  * 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.
+ *
+ * `SemiontSessionError` extends `SemiontError` (the unified Semiont base)
+ * so consumers can catch with `instanceof SemiontError` for any error
+ * surfaced through the SDK.
  */
-type SemiontErrorCode = 'session.construct-failed' | 'session.auth-failed' | 'session.refresh-exhausted' | 'browser.sign-in-failed';
-declare class SemiontError extends Error {
-    readonly code: SemiontErrorCode;
+
+type SemiontSessionErrorCode = 'session.construct-failed' | 'session.auth-failed' | 'session.refresh-exhausted' | 'browser.sign-in-failed';
+declare class SemiontSessionError extends SemiontError {
+    code: SemiontSessionErrorCode;
     readonly kbId: string | null;
-    constructor(code: SemiontErrorCode, message: string, kbId?: string | null);
+    constructor(code: SemiontSessionErrorCode, message: string, kbId?: string | null);
 }
 
 /**
@@ -882,7 +1099,7 @@ declare class InMemorySessionStorage implements SessionStorage {
  *
  * 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
+ * in `SessionSignals`, which wraps a session — the session
  * itself has no modal observables, no user-facing notifications.
  *
  * Auth is parameterized via callbacks passed at construction:
@@ -898,9 +1115,9 @@ declare class InMemorySessionStorage implements SessionStorage {
  *     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.
+ *     terminally fails (expired token, no recovery possible). UI hosts
+ *     typically wire this to `SessionSignals.notifySessionExpired` so a
+ *     modal surfaces; headless consumers typically just log.
  *
  * Persistence goes through a `SessionStorage` adapter provided at
  * construction — the session never touches `localStorage` or `window`
@@ -944,7 +1161,7 @@ interface SemiontSessionConfig {
      */
     onAuthFailed?: (message: string | null) => void;
     /** Called for session-level failures (auth, refresh exhaustion). */
-    onError?: (err: SemiontError) => void;
+    onError?: (err: SemiontSessionError) => void;
 }
 declare class SemiontSession {
     readonly kb: KnowledgeBase;
@@ -952,6 +1169,18 @@ declare class SemiontSession {
     readonly token$: BehaviorSubject<AccessToken | null>;
     readonly user$: BehaviorSubject<UserInfo | null>;
     readonly streamState$: Observable<ConnectionState>;
+    /**
+     * Stream of `SemiontError` instances surfaced by the underlying transport
+     * just before they're thrown to the caller. For `HttpTransport` this is
+     * an `APIError` (status-coded); other transports emit their own subclass.
+     * Surfaced here so a host layer (e.g. `SemiontBrowser`) can route by
+     * `err.code` to global notifications without every call site handling
+     * errors itself. Headless consumers can subscribe for logging.
+     *
+     * Re-published from `client.transport.errors$` per the `ITransport`
+     * contract — the session is purely a passthrough.
+     */
+    readonly errors$: Observable<SemiontError>;
     /** Resolves after the initial validation round-trip completes (success or failure). */
     readonly ready: Promise<void>;
     private readonly storage;
@@ -1001,6 +1230,67 @@ declare class SemiontSession {
      */
     subscribe<K extends keyof EventMap>(channel: K, handler: (payload: EventMap[K]) => void): () => void;
     dispose(): Promise<void>;
+    /**
+     * Convenience factory for the default HTTP setup. Constructs the
+     * shared `BehaviorSubject<AccessToken | null>`, an `HttpTransport`,
+     * an `HttpContentTransport`, and a `SemiontClient`, then wires
+     * the session over them. Removes the load-bearing
+     * "same-token$-instance" invariant from the caller's hands.
+     *
+     * Strings are accepted for `baseUrl` and `token`; they are branded
+     * via `baseUrl()` / `accessToken()` from `@semiont/core` automatically.
+     *
+     * The remaining options (`refresh`, `validate`, `onAuthFailed`,
+     * `onError`) match `SemiontSessionConfig` exactly.
+     */
+    static fromHttp(opts: {
+        kb: KnowledgeBase;
+        storage: SessionStorage;
+        baseUrl: BaseUrl | string;
+        token?: AccessToken | string | null;
+        refresh?: () => Promise<string | null>;
+        validate?: (token: AccessToken) => Promise<UserInfo | null>;
+        onAuthFailed?: (message: string | null) => void;
+        onError?: (err: SemiontSessionError) => void;
+    }): SemiontSession;
+    /**
+     * Async factory for the credentials-first long-running script case.
+     * Builds the HTTP transport stack, calls `auth.password(email,
+     * password)` to acquire access + refresh tokens, persists them via
+     * the storage adapter, wires a default `refresh` callback that
+     * exchanges the refresh token via `auth.refresh(...)`, and returns
+     * the ready session.
+     *
+     * The consumer-supplied `refresh` callback becomes optional — only
+     * needed for non-standard refresh flows (worker-pool shared secret,
+     * OAuth refresh-token grant, interactive re-prompt). The default
+     * uses the refresh token returned by `auth.password`.
+     *
+     * `kb` is required and must be a full `KnowledgeBase`. The `id` field
+     * is the storage key for this session — distinct scripts sharing the
+     * same `SessionStorage` instance must use distinct ids to avoid
+     * trampling each other's tokens. The factory does not synthesize a
+     * default; the consumer makes the choice.
+     *
+     * Named `signInHttp` because email+password authentication is
+     * inherently an HTTP-shaped operation in the current backend; an
+     * in-process `LocalTransport` doesn't have a credentials login
+     * path. Non-HTTP transports construct the session directly from
+     * their package's transport instance.
+     *
+     * Throws on auth failure with no resources leaked. On success, the
+     * returned session's `ready` promise has already resolved.
+     */
+    static signInHttp(opts: {
+        kb: KnowledgeBase;
+        storage: SessionStorage;
+        baseUrl: BaseUrl | string;
+        email: string;
+        password: string;
+        validate?: (token: AccessToken) => Promise<UserInfo | null>;
+        onAuthFailed?: (message: string | null) => void;
+        onError?: (err: SemiontSessionError) => void;
+    }): Promise<SemiontSession>;
 }
 
 /**
@@ -1026,36 +1316,33 @@ interface OpenResource {
 }
 
 /**
- * FrontendSessionSignals — modal state that belongs to the UI, not
- * the session itself.
+ * SessionSignals — UI-facing notification state that belongs to the host
+ * surface, not to 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.
+ * the session-expired / permission-denied *notifications* are inherently
+ * a UI-host concern. 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:
+ * `SessionSignals` owns the notification state and has no hard reference
+ * to a session. A UI host (e.g. `SemiontBrowser`) constructs one alongside
+ * every active 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
+ *     proactive-refresh failures surface as a notification
  *
- * React consumers that need modal state subscribe here; consumers
- * that need bus/HTTP access continue to subscribe to the session.
+ * UI consumers that need to render modal/banner 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.
+ * Signals only surfaces the notification.
  */
 
-declare class FrontendSessionSignals {
+declare class SessionSignals {
     readonly sessionExpiredAt$: BehaviorSubject<number | null>;
     readonly sessionExpiredMessage$: BehaviorSubject<string | null>;
     readonly permissionDeniedAt$: BehaviorSubject<number | null>;
@@ -1068,14 +1355,46 @@ declare class FrontendSessionSignals {
     dispose(): void;
 }
 
+/**
+ * SessionFactory — the injection point that lets `SemiontBrowser` stay
+ * transport-agnostic.
+ *
+ * The browser knows how to manage the *lifecycle* of an active session
+ * (track it in `activeSession$`, dispose on KB switch, serialize
+ * overlapping activations) but does not know how to *construct* one —
+ * because that's where transport choice lives. The construction step
+ * is parameterized via this factory.
+ *
+ * The HTTP factory is provided by `createHttpSessionFactory`. A
+ * future in-process variant from `@semiont/make-meaning` would expose
+ * its own factory.
+ */
+
+interface SessionFactoryOptions {
+    /** The KB the session is being constructed for. */
+    kb: KnowledgeBase;
+    /** Persistence adapter — same one the browser uses. */
+    storage: SessionStorage;
+    /** Modal-signal sink for auth-failed / permission-denied notifications. */
+    signals: SessionSignals;
+    /** Receives session-level errors (auth-failed, refresh-exhausted, ...). */
+    onError: (err: SemiontSessionError) => void;
+}
+type SessionFactory = (opts: SessionFactoryOptions) => SemiontSession;
+
 /**
  * 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.
+ * session-level error stream. Held as a process-wide instance for the
+ * host's lifetime — see `getBrowser()` in `registry.ts` for the canonical
+ * accessor.
+ *
+ * Transport-agnostic: the browser orchestrates session *lifecycle* but
+ * delegates session *construction* to a `SessionFactory` injected at
+ * construction. HTTP-backed apps pass `createHttpSessionFactory()` from
+ * `@semiont/sdk`; in-process apps pass their own factory.
  *
  * Persistence goes through a `SessionStorage` adapter provided at
  * construction — the browser never touches `localStorage` or `window`
@@ -1085,6 +1404,14 @@ declare class FrontendSessionSignals {
 interface SemiontBrowserConfig {
     /** Persistence adapter. The browser reads/writes all persisted state via this. */
     storage: SessionStorage;
+    /**
+     * Builds a `SemiontSession` for a KB. The browser is transport-
+     * agnostic — every HTTP-vs-local construction concern lives in the
+     * factory. HTTP-backed apps pass `createHttpSessionFactory()` from
+     * `@semiont/sdk`; a future in-process variant from `@semiont/make-meaning`
+     * would expose its own factory.
+     */
+    sessionFactory: SessionFactory;
 }
 declare class SemiontBrowser {
     readonly kbs$: BehaviorSubject<KnowledgeBase[]>;
@@ -1096,9 +1423,9 @@ declare class SemiontBrowser {
      * 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).
+     * See [SessionSignals](./session-signals.ts).
      */
-    readonly activeSignals$: BehaviorSubject<FrontendSessionSignals | null>;
+    readonly activeSignals$: BehaviorSubject<SessionSignals | null>;
     /**
      * True while a session is actively being constructed (setActiveKb /
      * signIn in flight, awaiting `session.ready`). Distinguishes the
@@ -1109,9 +1436,10 @@ declare class SemiontBrowser {
      */
     readonly sessionActivating$: BehaviorSubject<boolean>;
     readonly openResources$: BehaviorSubject<OpenResource[]>;
-    readonly error$: Subject<SemiontError>;
+    readonly error$: Subject<SemiontSessionError>;
     readonly identityToken$: BehaviorSubject<string | null>;
     private readonly storage;
+    private readonly sessionFactory;
     /**
      * App-scoped EventBus. Hosts UI-shell events that must work regardless
      * of whether a KB session is active: panel toggles, sidebar state,
@@ -1120,18 +1448,9 @@ declare class SemiontBrowser {
      * (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;
@@ -1140,14 +1459,25 @@ declare class SemiontBrowser {
     /** 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.
+     * Set the app-level identity token. Sourced from whatever the host
+     * environment uses for OAuth sessions (e.g. NextAuth in a browser app).
+     * Should be called once from the host's startup-and-on-change site;
+     * no other code should write to this slot.
      */
     setIdentityToken(token: string | null): void;
     addKb(input: NewKnowledgeBase, access: string, refresh: string): KnowledgeBase;
     removeKb(id: string): void;
-    updateKb(id: string, updates: Partial<KnowledgeBase>): void;
+    /**
+     * Patch a KB in the list. Restricted to the common, endpoint-agnostic
+     * fields (`label`, `email`, `gitBranch`) — the `endpoint` shape isn't
+     * editable in place; remove and re-add to change the connection
+     * target.
+     */
+    updateKb(id: string, updates: {
+        label?: string;
+        email?: string;
+        gitBranch?: string;
+    }): 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
@@ -1182,46 +1512,45 @@ declare class SemiontBrowser {
     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.
+ * createHttpSessionFactory — the default `SessionFactory` for HTTP-backed
+ * KBs. Owns every HTTP-specific construction concern that used to live in
+ * `SemiontBrowser`: building `HttpTransport`/`HttpContentTransport`,
+ * wiring the `tokenRefresher` callback, deduplicating concurrent 401
+ * refresh round trips, and invoking the auth endpoints for token refresh
+ * and user-validate.
+ *
+ * Returned as a closure so a single `inFlightRefreshes` map is shared
+ * across every session this factory builds — the dedup is meaningful
+ * across concurrent session reactivations for the same KB id.
+ */
+
+declare function createHttpSessionFactory(): SessionFactory;
+
+/**
+ * Process-wide accessor for `SemiontBrowser`. Constructed lazily on the
+ * first `getBrowser()` call and held for the host's lifetime — a single
+ * instance owns the KB list, identity token, and active-session state,
+ * so callers throughout the host get the same view of "which KB am I
+ * talking to right now" regardless of where they pick it up.
+ *
+ * The caller provides a `SessionStorage` implementation and a
+ * `SessionFactory` — both are environment-specific (browsers use
+ * `WebBrowserStorage` + `createHttpSessionFactory()`, CLI/embedded
+ * hosts use a filesystem adapter and possibly a local-process
+ * factory, tests use `InMemorySessionStorage` and stubs). The first
+ * call to `getBrowser` wins; subsequent calls return the cached
+ * instance regardless of the options passed.
  */
 
 interface GetBrowserOptions {
     /** Persistence adapter used to construct the singleton on first call. */
     storage: SessionStorage;
+    /** Session factory used to build a `SemiontSession` per active KB. */
+    sessionFactory: SessionFactory;
 }
 declare function getBrowser(options: GetBrowserOptions): SemiontBrowser;
 
@@ -1248,16 +1577,45 @@ interface StoredSession {
 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;
+/**
+ * Build the wire URL for an HTTP KB endpoint. HTTP-shaped helper —
+ * lives next to the KB list machinery because the frontend Panel needs
+ * it for the auth round-trip when adding a KB. Code that holds a
+ * uniform `KnowledgeBase` should not call this; it should hand the KB
+ * to a transport factory and let the factory inspect `endpoint.kind`.
+ */
+declare function kbBackendUrl(endpoint: HttpEndpoint): string;
 
-interface ViewModel {
+/**
+ * Marker for the state-unit pattern: a stateful, lifecycled object with an
+ * RxJS-shaped public surface, constructed by a factory function
+ * (`createFooStateUnit`), with internal state held in a closure.
+ *
+ * The structural contract is `dispose()` — the rest of the pattern
+ * (closure-based identity, Observable public surface, internal Subjects
+ * exposed as `.asObservable()` views, no leaked subscriptions, composition
+ * by parameter rather than ownership) is convention enforced by review,
+ * not the type system.
+ *
+ * See `packages/sdk/docs/STATE-UNITS.md` for the full axioms and rationale.
+ */
+interface StateUnit {
+    /**
+     * Idempotent, total teardown. Completes every Subject the unit owns,
+     * unsubscribes every internal subscription, releases timers / abort
+     * controllers / network handles. Safe to call multiple times — the
+     * second call is a no-op.
+     */
     dispose(): void;
 }
+/**
+ * Compose multiple disposers into a single `dispose()` call. Accepts either
+ * a `StateUnit` (whose `dispose()` will be invoked) or a plain teardown
+ * function. The returned object is itself disposable; call its `dispose()`
+ * once to tear down everything that was added.
+ */
 declare function createDisposer(): {
-    add(vm: ViewModel | (() => void)): void;
+    add(item: StateUnit | (() => void)): void;
     dispose(): void;
 };
 
@@ -1267,10 +1625,9 @@ declare function createDisposer(): {
  * 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.
+ * Designed to be created once per consumer instance and held for its lifetime
+ * (e.g. by a view layer's lazy initializer), then observed via `state$`. The
+ * pipeline is pure RxJS — unit-testable without any view-layer dependency.
  *
  * The fetch function is expected to return `Observable<T[] | undefined>`,
  * matching the cache-miss-then-data shape of `BrowseNamespace` Observables:
@@ -1283,13 +1640,13 @@ interface SearchState<T> {
     isSearching: boolean;
 }
 interface SearchPipeline<T> {
-    /** Latest query string. Bind to a controlled input via `useObservable`. */
+    /** Latest query string. Bind to a controlled input. */
     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. */
+    /** Tear down the input Subject. Call from the consumer's cleanup hook. */
     dispose(): void;
 }
 interface SearchPipelineOptions {
@@ -1300,13 +1657,34 @@ interface SearchPipelineOptions {
 }
 declare function createSearchPipeline<T>(fetch: (query: string) => Observable<T[] | undefined>, options?: SearchPipelineOptions): SearchPipeline<T>;
 
-interface BeckonVM extends ViewModel {
+/**
+ * WorkerBus — minimal channel-bus surface that worker-side adapters
+ * (e.g. `JobClaimAdapter` in `@semiont/jobs`, `SmelterActorStateUnit` in
+ * `@semiont/make-meaning`) need.
+ *
+ * Transport-neutral by design. HTTP `ActorStateUnit` (from `@semiont/api-client`)
+ * satisfies it directly; an in-process worker can pass a small shim around
+ * an `EventBus` with a `() => Promise<void>` `emit` that calls into the
+ * actor system.
+ *
+ * `addChannels` is optional because in-process buses receive every emit
+ * implicitly — only HTTP needs to widen its SSE subscription set to
+ * include worker-only channels (`job:queued`, `yield:created`, etc.).
+ */
+
+interface WorkerBus {
+    on$<T = Record<string, unknown>>(channel: string): Observable<T>;
+    emit(channel: string, payload: Record<string, unknown>): Promise<void>;
+    addChannels?(channels: readonly string[]): void;
+}
+
+interface BeckonStateUnit extends StateUnit {
     hoveredAnnotationId$: Observable<AnnotationId | null>;
     hover(annotationId: AnnotationId | null): void;
     focus(annotationId: AnnotationId): void;
     sparkle(annotationId: AnnotationId): void;
 }
-declare function createBeckonVM(client: SemiontClient): BeckonVM;
+declare function createBeckonStateUnit(client: SemiontClient): BeckonStateUnit;
 /** Default milliseconds the mouse must dwell before beckon:hover is emitted. */
 declare const HOVER_DELAY_MS = 150;
 type EmitHover = (annotationId: AnnotationId | null) => void;
@@ -1317,372 +1695,48 @@ interface HoverHandlers {
 }
 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 {
+interface GatherStateUnit extends StateUnit {
     context$: Observable<GatheredContext | null>;
     loading$: Observable<boolean>;
     error$: Observable<Error | null>;
     annotationId$: Observable<AnnotationId | null>;
 }
-declare function createGatherVM(client: SemiontClient, resourceId: ResourceId): GatherVM;
+declare function createGatherStateUnit(client: SemiontClient, resourceId: ResourceId): GatherStateUnit;
 
-interface MatchVM extends ViewModel {
+interface MatchStateUnit extends StateUnit {
 }
-declare function createMatchVM(client: SemiontClient, _resourceId: ResourceId): MatchVM;
+declare function createMatchStateUnit(client: SemiontClient, _resourceId: ResourceId): MatchStateUnit;
 
 type JobProgress$1 = components['schemas']['JobProgress'];
 interface GenerateDocumentOptions {
     title: string;
     storageUri: string;
     prompt?: string;
+    /** Body locale — language the generated resource is written in. Falls back to the state unit's UI locale when unset. */
     language?: string;
+    /** Source-resource locale — language of the resource the annotation lives on. Forwarded to the prompt for context-snippet awareness. BCP-47. */
+    sourceLanguage?: string;
     temperature?: number;
     maxTokens?: number;
     context: GatheredContext;
 }
-interface YieldVM extends ViewModel {
+interface YieldStateUnit extends StateUnit {
     isGenerating$: Observable<boolean>;
     progress$: Observable<JobProgress$1 | null>;
     generate(referenceId: string, options: GenerateDocumentOptions): void;
 }
-declare function createYieldVM(client: SemiontClient, resourceId: ResourceId, locale: string): YieldVM;
+declare function createYieldStateUnit(client: SemiontClient, resourceId: ResourceId, locale: string): YieldStateUnit;
 
 type JobProgress = components['schemas']['JobProgress'];
 interface PendingAnnotation {
     selector: Selector | Selector[];
     motivation: Motivation;
 }
-interface MarkVM extends ViewModel {
+interface MarkStateUnit extends StateUnit {
     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;
+declare function createMarkStateUnit(client: SemiontClient, resourceId: ResourceId): MarkStateUnit;
 
-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 };
+export { AdminNamespace, type AnnotationHistoryResponse, AuthNamespace, BeckonNamespace, type BeckonStateUnit, BindNamespace, BrowseNamespace, BusRequestError, type BusRequestErrorCode, type BusRequestPrimitive, CacheObservable, type CreateAnnotationInput, type CreateFromTokenOptions, type CreateResourceInput, FrameNamespace, type GatherAnnotationProgress, GatherNamespace, type GatherStateUnit, type GenerateDocumentOptions, type GenerationOptions, type GetBrowserOptions, HOVER_DELAY_MS, type HoverHandlers, type HttpEndpoint, InMemorySessionStorage, JobNamespace, type KbEndpoint, type KbSessionStatus, type KnowledgeBase, type LocalEndpoint, type MarkAssistEvent, type MarkAssistOptions, type MarkAssistProgress, MarkNamespace, type MarkStateUnit, MatchNamespace, type MatchSearchProgress, type MatchStateUnit, type NewKnowledgeBase, type OpenResource, type PendingAnnotation, type ReferencedByEntry, type RequestContent, type ResponseContent, type SearchPipeline, type SearchPipelineOptions, type SearchState, SemiontBrowser, type SemiontBrowserConfig, SemiontClient, SemiontSession, type SemiontSessionConfig, SemiontSessionError, type SemiontSessionErrorCode, type SessionFactory, type SessionFactoryOptions, SessionSignals, type SessionStorage, type StateUnit, type StoredSession, StreamObservable, UploadObservable, type UploadProgress, type User, type UserInfo, type WorkerBus, type YieldGenerationEvent, YieldNamespace, type YieldStateUnit, busRequest, createBeckonStateUnit, createDisposer, createGatherStateUnit, createHoverHandlers, createHttpSessionFactory, createMarkStateUnit, createMatchStateUnit, createSearchPipeline, createYieldStateUnit, defaultProtocol, getBrowser, httpKb, isValidHostname, kbBackendUrl, setStoredSession };