@semiont/sdk 0.5.0 → 0.5.2

package/dist/index.js

@@ -1,13 +1,61 @@
-import { annotationId, resourceId, email, googleCredential, refreshToken, EventBus, accessToken, baseUrl, isHighlight, isComment, isAssessment, isReference, isTag, decodeWithCharset, getPrimaryMediaType, userDID, searchQuery } from '@semiont/core';
-import { merge, firstValueFrom, BehaviorSubject, map as map$1, distinctUntilChanged, Observable, Subject, Subscription, of, filter as filter$1, take as take$1, timeout as timeout$1 } from 'rxjs';
-import { filter, map, take, timeout, takeUntil, startWith, debounceTime, distinctUntilChanged as distinctUntilChanged$1, switchMap } from 'rxjs/operators';
-import { HttpTransport, HttpContentTransport, createActorVM, APIError } from '@semiont/api-client';
-export { APIError, DEGRADED_THRESHOLD_MS, HttpContentTransport, HttpTransport, createActorVM } from '@semiont/api-client';
+import { SemiontError, annotationId, resourceId, email, googleCredential, refreshToken, EventBus, baseUrl, accessToken, searchQuery } from '@semiont/core';
+export { SemiontError, accessToken, annotationId, baseUrl, entityType, refreshToken, resourceId, userId } from '@semiont/core';
+import { Observable, lastValueFrom, firstValueFrom, merge, TimeoutError, throwError, map as map$1, BehaviorSubject, Subject, Subscription, of, distinctUntilChanged as distinctUntilChanged$1 } from 'rxjs';
+export { firstValueFrom, lastValueFrom } from 'rxjs';
+import { filter, map, take, timeout, catchError, takeUntil, startWith, debounceTime, distinctUntilChanged, switchMap } from 'rxjs/operators';
+import { HttpTransport, HttpContentTransport, APIError } from '@semiont/api-client';
+export { APIError, HttpContentTransport, HttpTransport } from '@semiont/api-client';
 
 // src/client.ts
-var BusRequestError = class extends Error {
-  constructor(message) {
-    super(message);
+var StreamObservable = class _StreamObservable extends Observable {
+  then(onfulfilled, onrejected) {
+    return lastValueFrom(this).then(onfulfilled, onrejected);
+  }
+  /** Wrap an existing Observable's subscribe behavior in a StreamObservable. */
+  static from(source) {
+    return new _StreamObservable((subscriber) => source.subscribe(subscriber));
+  }
+};
+var CacheObservable = class _CacheObservable extends Observable {
+  then(onfulfilled, onrejected) {
+    return firstValueFrom(this.pipe(filter((v) => v !== void 0))).then(onfulfilled, onrejected);
+  }
+  /**
+   * 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(source) {
+    let wrapper = wrapperCache.get(source);
+    if (!wrapper) {
+      wrapper = new _CacheObservable((subscriber) => source.subscribe(subscriber));
+      wrapperCache.set(source, wrapper);
+    }
+    return wrapper;
+  }
+};
+var wrapperCache = /* @__PURE__ */ new WeakMap();
+var UploadObservable = class extends Observable {
+  then(onfulfilled, onrejected) {
+    return lastValueFrom(this).then((v) => {
+      if (v.phase !== "finished") {
+        throw new Error(`UploadObservable resolved on a non-finished event: ${v.phase}`);
+      }
+      const result = { resourceId: v.resourceId };
+      return onfulfilled ? onfulfilled(result) : result;
+    }, onrejected);
+  }
+};
+var BusRequestError = class extends SemiontError {
+  constructor(message, code, details) {
+    super(message, code, details);
     this.name = "BusRequestError";
   }
 };
@@ -21,9 +69,31 @@ async function busRequest(bus, emitChannel, payload, resultChannel, failureChann
     ),
     bus.stream(failureChannel).pipe(
       filter((e) => e.correlationId === correlationId),
-      map((e) => ({ ok: false, error: new BusRequestError(e.message) }))
+      map((e) => ({
+        ok: false,
+        error: new BusRequestError(e.message ?? "Bus request rejected", "bus.rejected", {
+          channel: failureChannel,
+          correlationId,
+          payload: e
+        })
+      }))
     )
-  ).pipe(take(1), timeout(timeoutMs));
+  ).pipe(
+    take(1),
+    timeout(timeoutMs),
+    catchError((err) => {
+      if (err instanceof TimeoutError) {
+        return throwError(
+          () => new BusRequestError(
+            `Bus request timed out after ${timeoutMs}ms on ${resultChannel}`,
+            "bus.timeout",
+            { channel: emitChannel, resultChannel, correlationId, timeoutMs }
+          )
+        );
+      }
+      return throwError(() => err);
+    })
+  );
   const resultPromise = firstValueFrom(result$);
   await bus.emit(emitChannel, fullPayload);
   const result = await resultPromise;
@@ -58,7 +128,7 @@ function createCache(fetchFn) {
       if (!obs) {
         obs = store$.pipe(
           map$1((m) => m.get(key)),
-          distinctUntilChanged()
+          distinctUntilChanged$1()
         );
         obsCache.set(key, obs);
       }
@@ -106,11 +176,6 @@ var BrowseNamespace = class {
     this.transport = transport;
     this.bus = bus;
     this.content = content;
-    const g = globalThis;
-    g.__SEMIONT_BROWSE_INSTANCES__ = (g.__SEMIONT_BROWSE_INSTANCES__ ?? 0) + 1;
-    const browseSerial = g.__SEMIONT_BROWSE_INSTANCES__;
-    this.__serial__ = browseSerial;
-    console.debug(`[diag] BrowseNamespace #${browseSerial} constructed`);
     this.resourceCache = createCache(async (id) => {
       const result = await busRequest(
         this.transport,
@@ -133,32 +198,30 @@ var BrowseNamespace = class {
       );
       return result.resources;
     });
-    this.annotationListCache = createCache(async (resourceId) => {
+    this.annotationListCache = createCache(async (resourceId2) => {
       return busRequest(
         this.transport,
         "browse:annotations-requested",
-        { resourceId },
+        { resourceId: resourceId2 },
         "browse:annotations-result",
         "browse:annotations-failed"
       );
     });
-    this.annotationDetailCache = createCache(async (annotationId) => {
-      const resourceId = this.annotationResources.get(annotationId);
-      if (!resourceId) {
-        throw new Error(`Cannot fetch annotation ${annotationId}: no resourceId known`);
+    this.annotationDetailCache = createCache(async (annotationId2) => {
+      const resourceId2 = this.annotationResources.get(annotationId2);
+      if (!resourceId2) {
+        throw new Error(`Cannot fetch annotation ${annotationId2}: no resourceId known`);
       }
       const result = await busRequest(
         this.transport,
         "browse:annotation-requested",
-        { resourceId, annotationId },
+        { resourceId: resourceId2, annotationId: annotationId2 },
         "browse:annotation-result",
         "browse:annotation-failed"
       );
       return result.annotation;
     });
     this.entityTypesCache = createCache(async () => {
-      const serial = this.__serial__;
-      console.debug(`[diag] BrowseNamespace#${serial} entityTypes fetchFn START`);
       const result = await busRequest(
         this.transport,
         "browse:entity-types-requested",
@@ -166,24 +229,23 @@ var BrowseNamespace = class {
         "browse:entity-types-result",
         "browse:entity-types-failed"
       );
-      console.debug(`[diag] BrowseNamespace#${serial} entityTypes fetchFn RESOLVE`, JSON.stringify(result.entityTypes).slice(0, 200));
       return result.entityTypes;
     });
-    this.referencedByCache = createCache(async (resourceId) => {
+    this.referencedByCache = createCache(async (resourceId2) => {
       const result = await busRequest(
         this.transport,
         "browse:referenced-by-requested",
-        { resourceId },
+        { resourceId: resourceId2 },
         "browse:referenced-by-result",
         "browse:referenced-by-failed"
       );
       return result.referencedBy;
     });
-    this.resourceEventsCache = createCache(async (resourceId) => {
+    this.resourceEventsCache = createCache(async (resourceId2) => {
       const result = await busRequest(
         this.transport,
         "browse:events-requested",
-        { resourceId },
+        { resourceId: resourceId2 },
         "browse:events-result",
         "browse:events-failed"
       );
@@ -195,7 +257,7 @@ var BrowseNamespace = class {
   //
   // Each cache encapsulates the BehaviorSubject store, in-flight guard,
   // and per-key observable memoization that was previously open-coded
-  // here. Behavioral contract: `packages/api-client/docs/CACHE-SEMANTICS.md`.
+  // here. Behavioral contract: `packages/sdk/docs/CACHE-SEMANTICS.md`.
   //
   // Public surface (`resource()`, `annotations()`, etc.) is unchanged;
   // the caches are an implementation detail of this namespace.
@@ -227,71 +289,66 @@ var BrowseNamespace = class {
    */
   annotationListObs = /* @__PURE__ */ new Map();
   // ── Live queries ────────────────────────────────────────────────────────
-  resource(resourceId) {
-    return this.resourceCache.observe(resourceId);
+  //
+  // These return `CacheObservable<T>`: subscribers see `T | undefined`
+  // (with `undefined` during initial load), and `await` resolves to the
+  // first non-undefined value.
+  resource(resourceId2) {
+    return CacheObservable.from(this.resourceCache.observe(resourceId2));
   }
   resources(filters) {
     const key = JSON.stringify(filters ?? {});
     this.resourceListFilters.set(key, filters ?? {});
-    return this.resourceListCache.observe(key);
+    return CacheObservable.from(this.resourceListCache.observe(key));
   }
-  annotations(resourceId) {
-    let obs = this.annotationListObs.get(resourceId);
+  annotations(resourceId2) {
+    let obs = this.annotationListObs.get(resourceId2);
     if (!obs) {
-      obs = this.annotationListCache.observe(resourceId).pipe(map$1((r) => r?.annotations));
-      this.annotationListObs.set(resourceId, obs);
+      obs = this.annotationListCache.observe(resourceId2).pipe(map$1((r) => r?.annotations));
+      this.annotationListObs.set(resourceId2, obs);
     }
-    return obs;
+    return CacheObservable.from(obs);
   }
-  annotation(resourceId, annotationId) {
-    this.annotationResources.set(annotationId, resourceId);
-    return this.annotationDetailCache.observe(annotationId);
+  annotation(resourceId2, annotationId2) {
+    this.annotationResources.set(annotationId2, resourceId2);
+    return CacheObservable.from(this.annotationDetailCache.observe(annotationId2));
   }
   entityTypes() {
-    const serial = this.__serial__;
-    console.debug(`[diag] BrowseNamespace#${serial} entityTypes() called`);
-    const self = this;
-    if (!self.__entityTypesDiag__) {
-      self.__entityTypesDiag__ = this.entityTypesCache.observe(ENTITY_TYPES_KEY).pipe(map$1((v) => {
-        console.debug(`[diag] BrowseNamespace#${serial} entityTypes$ EMIT`, v === void 0 ? "undefined" : JSON.stringify(v).slice(0, 200));
-        return v;
-      }));
-    }
-    return self.__entityTypesDiag__;
+    return CacheObservable.from(this.entityTypesCache.observe(ENTITY_TYPES_KEY));
   }
-  referencedBy(resourceId) {
-    return this.referencedByCache.observe(resourceId);
+  referencedBy(resourceId2) {
+    return CacheObservable.from(this.referencedByCache.observe(resourceId2));
   }
-  events(resourceId) {
-    return this.resourceEventsCache.observe(resourceId);
+  events(resourceId2) {
+    return CacheObservable.from(this.resourceEventsCache.observe(resourceId2));
   }
   // ── One-shot reads ──────────────────────────────────────────────────────
-  async resourceContent(resourceId) {
-    const result = await this.content.getBinary(resourceId, { accept: "text/plain" });
+  async resourceContent(resourceId2) {
+    const result = await this.content.getBinary(resourceId2, { accept: "text/plain" });
     const decoder = new TextDecoder();
     return decoder.decode(result.data);
   }
-  async resourceRepresentation(resourceId, options) {
-    return this.content.getBinary(resourceId, options?.accept ? { accept: options.accept } : void 0);
+  async resourceRepresentation(resourceId2, options) {
+    return this.content.getBinary(resourceId2, options?.accept ? { accept: options.accept } : void 0);
   }
-  async resourceRepresentationStream(resourceId, options) {
-    return this.content.getBinaryStream(resourceId, options?.accept ? { accept: options.accept } : void 0);
+  async resourceRepresentationStream(resourceId2, options) {
+    return this.content.getBinaryStream(resourceId2, options?.accept ? { accept: options.accept } : void 0);
   }
-  async resourceEvents(resourceId) {
+  async resourceEvents(resourceId2) {
     const result = await busRequest(
       this.transport,
       "browse:events-requested",
-      { resourceId },
+      { resourceId: resourceId2 },
       "browse:events-result",
       "browse:events-failed"
     );
     return result.events;
   }
-  async annotationHistory(resourceId, annotationId) {
+  async annotationHistory(resourceId2, annotationId2) {
     return busRequest(
       this.transport,
       "browse:annotation-history-requested",
-      { resourceId, annotationId },
+      { resourceId: resourceId2, annotationId: annotationId2 },
       "browse:annotation-history-result",
       "browse:annotation-history-failed"
     );
@@ -315,11 +372,11 @@ var BrowseNamespace = class {
     );
   }
   // ── UI signals (local bus fan-out) ────────────────────────────────────
-  click(annotationId, motivation) {
-    this.bus.get("browse:click").next({ annotationId, motivation });
+  click(annotationId2, motivation) {
+    this.bus.get("browse:click").next({ annotationId: annotationId2, motivation });
   }
-  navigateReference(resourceId) {
-    this.bus.get("browse:reference-navigate").next({ resourceId });
+  navigateReference(resourceId2) {
+    this.bus.get("browse:reference-navigate").next({ resourceId: resourceId2 });
   }
   // ── Cache-mutation API (used by the bus-event subscribers below and by
   //    other namespaces that know about specific updates) ─────────────────
@@ -327,12 +384,12 @@ var BrowseNamespace = class {
   //  - `invalidate*`     — SWR refetch (B7). Keeps prior value visible.
   //  - `removeAnnotationDetail` — drops the entry (B13a: entity gone).
   //  - `updateAnnotationInPlace` — write-through (B13b: new value known).
-  invalidateAnnotationList(resourceId) {
-    this.annotationListCache.invalidate(resourceId);
+  invalidateAnnotationList(resourceId2) {
+    this.annotationListCache.invalidate(resourceId2);
   }
-  removeAnnotationDetail(annotationId) {
-    this.annotationDetailCache.remove(annotationId);
-    this.annotationResources.delete(annotationId);
+  removeAnnotationDetail(annotationId2) {
+    this.annotationDetailCache.remove(annotationId2);
+    this.annotationResources.delete(annotationId2);
   }
   invalidateResourceDetail(id) {
     this.resourceCache.invalidate(id);
@@ -343,21 +400,21 @@ var BrowseNamespace = class {
   invalidateEntityTypes() {
     this.entityTypesCache.invalidate(ENTITY_TYPES_KEY);
   }
-  invalidateReferencedBy(resourceId) {
-    this.referencedByCache.invalidate(resourceId);
+  invalidateReferencedBy(resourceId2) {
+    this.referencedByCache.invalidate(resourceId2);
   }
-  invalidateResourceEvents(resourceId) {
-    this.resourceEventsCache.invalidate(resourceId);
+  invalidateResourceEvents(resourceId2) {
+    this.resourceEventsCache.invalidate(resourceId2);
   }
-  updateAnnotationInPlace(resourceId, annotation) {
-    const currentList = this.annotationListCache.get(resourceId);
+  updateAnnotationInPlace(resourceId2, annotation) {
+    const currentList = this.annotationListCache.get(resourceId2);
     if (currentList) {
       const idx = currentList.annotations.findIndex((a) => a.id === annotation.id);
       const nextAnnotations = idx >= 0 ? currentList.annotations.map((a, i) => i === idx ? annotation : a) : [...currentList.annotations, annotation];
-      this.annotationListCache.set(resourceId, { ...currentList, annotations: nextAnnotations });
+      this.annotationListCache.set(resourceId2, { ...currentList, annotations: nextAnnotations });
     }
     const aId = annotationId(annotation.id);
-    this.annotationResources.set(aId, resourceId);
+    this.annotationResources.set(aId, resourceId2);
     this.annotationDetailCache.set(aId, annotation);
   }
   // ── EventBus subscriptions ──────────────────────────────────────────────
@@ -453,7 +510,7 @@ var BrowseNamespace = class {
     this.on("yield:update-ok", this.onYieldResourceMutated);
     this.on("mark:archived", this.onArchiveToggled);
     this.on("mark:unarchived", this.onArchiveToggled);
-    this.on("mark:entity-type-added", () => this.invalidateEntityTypes());
+    this.on("frame:entity-type-added", () => this.invalidateEntityTypes());
   }
 };
 var MarkNamespace = class {
@@ -461,34 +518,28 @@ var MarkNamespace = class {
     this.transport = transport;
     this.bus = bus;
   }
-  async annotation(resourceId, input) {
-    return busRequest(
+  async annotation(input) {
+    const resourceId2 = resourceId(input.target.source);
+    const result = await busRequest(
       this.transport,
       "mark:create-request",
-      { resourceId, request: input },
+      { resourceId: resourceId2, request: input },
       "mark:create-ok",
       "mark:create-failed"
     );
+    return { annotationId: annotationId(result.annotationId) };
   }
-  async delete(resourceId, annotationId) {
-    await this.transport.emit("mark:delete", { annotationId, resourceId });
-  }
-  async entityType(type) {
-    await this.transport.emit("mark:add-entity-type", { tag: type });
-  }
-  async entityTypes(types) {
-    for (const tag of types) {
-      await this.transport.emit("mark:add-entity-type", { tag });
-    }
+  async delete(resourceId2, annotationId2) {
+    await this.transport.emit("mark:delete", { annotationId: annotationId2, resourceId: resourceId2 });
   }
-  async archive(resourceId) {
-    await this.transport.emit("mark:archive", { resourceId });
+  async archive(resourceId2) {
+    await this.transport.emit("mark:archive", { resourceId: resourceId2 });
   }
-  async unarchive(resourceId) {
-    await this.transport.emit("mark:unarchive", { resourceId });
+  async unarchive(resourceId2) {
+    await this.transport.emit("mark:unarchive", { resourceId: resourceId2 });
   }
-  assist(resourceId, motivation, options) {
-    return new Observable((subscriber) => {
+  assist(resourceId2, motivation, options) {
+    return new StreamObservable((subscriber) => {
       let done = false;
       let pollTimer = null;
       let pollInterval = null;
@@ -528,7 +579,7 @@ var MarkNamespace = class {
                   data: {
                     jobId,
                     jobType: status.jobType ?? "annotation",
-                    resourceId,
+                    resourceId: resourceId2,
                     result: status.result
                   }
                 });
@@ -565,7 +616,7 @@ var MarkNamespace = class {
         cleanup();
         subscriber.error(new Error(e.error));
       });
-      this.dispatchAssist(resourceId, motivation, options).then(({ jobId }) => {
+      this.dispatchAssist(resourceId2, motivation, options).then(({ jobId }) => {
         if (jobId && !done) {
           activeJobId = jobId;
           resetPollTimer(jobId);
@@ -613,7 +664,7 @@ var MarkNamespace = class {
   toggleMode() {
     this.bus.get("mark:mode-toggled").next(void 0);
   }
-  async dispatchAssist(resourceId, motivation, options) {
+  async dispatchAssist(resourceId2, motivation, options) {
     const jobTypeMap = {
       tagging: "tag-annotation",
       linking: "reference-annotation",
@@ -635,12 +686,13 @@ var MarkNamespace = class {
     if (options.density !== void 0) params.density = options.density;
     if (options.tone !== void 0) params.tone = options.tone;
     if (options.language !== void 0) params.language = options.language;
+    if (options.sourceLanguage !== void 0) params.sourceLanguage = options.sourceLanguage;
     if (options.schemaId !== void 0) params.schemaId = options.schemaId;
     if (options.categories !== void 0) params.categories = options.categories;
     return busRequest(
       this.transport,
       "job:create",
-      { jobType, resourceId, params },
+      { jobType, resourceId: resourceId2, params },
       "job:created",
       "job:create-failed"
     );
@@ -653,11 +705,11 @@ var BindNamespace = class {
     this.transport = transport;
     this.bus = bus;
   }
-  async body(resourceId, annotationId, operations) {
+  async body(resourceId2, annotationId2, operations) {
     await this.transport.emit("bind:update-body", {
       correlationId: crypto.randomUUID(),
-      annotationId,
-      resourceId,
+      annotationId: annotationId2,
+      resourceId: resourceId2,
       operations
     });
   }
@@ -670,8 +722,8 @@ var GatherNamespace = class {
     this.transport = transport;
     this.bus = bus;
   }
-  annotation(annotationId, resourceId, options) {
-    return new Observable((subscriber) => {
+  annotation(resourceId2, annotationId2, options) {
+    return new StreamObservable((subscriber) => {
       const correlationId = crypto.randomUUID();
       const complete$ = this.bus.get("gather:complete").pipe(
         filter((e) => e.correlationId === correlationId)
@@ -681,7 +733,7 @@ var GatherNamespace = class {
       );
       const sub = merge(
         this.bus.get("gather:annotation-progress").pipe(
-          filter((e) => e.annotationId === annotationId),
+          filter((e) => e.annotationId === annotationId2),
           map((e) => e)
         ),
         complete$.pipe(map((e) => e))
@@ -698,8 +750,8 @@ var GatherNamespace = class {
       });
       this.transport.emit("gather:requested", {
         correlationId,
-        annotationId,
-        resourceId,
+        annotationId: annotationId2,
+        resourceId: resourceId2,
         options: { contextWindow: options?.contextWindow ?? 2e3 }
       }).catch((error) => {
         subscriber.error(error);
@@ -723,8 +775,8 @@ var MatchNamespace = class {
   requestSearch(input) {
     this.bus.get("match:search-requested").next(input);
   }
-  search(resourceId, referenceId, context, options) {
-    return new Observable((subscriber) => {
+  search(resourceId2, referenceId, context, options) {
+    return new StreamObservable((subscriber) => {
       const correlationId = crypto.randomUUID();
       const result$ = this.bus.get("match:search-results").pipe(
         filter((e) => e.correlationId === correlationId)
@@ -741,7 +793,7 @@ var MatchNamespace = class {
       });
       this.transport.emit("match:search-requested", {
         correlationId,
-        resourceId,
+        resourceId: resourceId2,
         referenceId,
         context,
         limit: options?.limit ?? 10,
@@ -762,25 +814,56 @@ var YieldNamespace = class {
     this.bus = bus;
     this.content = content;
   }
-  async resource(data) {
-    const result = await this.content.putBinary({
-      name: data.name,
-      file: data.file,
-      format: data.format,
-      storageUri: data.storageUri,
-      ...data.entityTypes ? { entityTypes: data.entityTypes } : {},
-      ...data.language ? { language: data.language } : {},
-      ...data.creationMethod ? { creationMethod: data.creationMethod } : {},
-      ...data.sourceAnnotationId ? { sourceAnnotationId: data.sourceAnnotationId } : {},
-      ...data.sourceResourceId ? { sourceResourceId: data.sourceResourceId } : {},
-      ...data.generationPrompt ? { generationPrompt: data.generationPrompt } : {},
-      ...data.generator ? { generator: data.generator } : {},
-      ...data.isDraft !== void 0 ? { isDraft: data.isDraft } : {}
+  resource(data) {
+    const totalBytes = typeof Buffer !== "undefined" && data.file instanceof Buffer ? data.file.length : data.file.size;
+    return new UploadObservable((subscriber) => {
+      subscriber.next({ phase: "started", totalBytes });
+      let cancelled = false;
+      const abortController = new AbortController();
+      this.content.putBinary(
+        {
+          name: data.name,
+          file: data.file,
+          format: data.format,
+          storageUri: data.storageUri,
+          ...data.entityTypes ? { entityTypes: data.entityTypes } : {},
+          ...data.language ? { language: data.language } : {},
+          ...data.creationMethod ? { creationMethod: data.creationMethod } : {},
+          ...data.sourceAnnotationId ? { sourceAnnotationId: data.sourceAnnotationId } : {},
+          ...data.sourceResourceId ? { sourceResourceId: data.sourceResourceId } : {},
+          ...data.generationPrompt ? { generationPrompt: data.generationPrompt } : {},
+          ...data.generator ? { generator: data.generator } : {},
+          ...data.isDraft !== void 0 ? { isDraft: data.isDraft } : {}
+        },
+        {
+          // Byte-progress hook. Honored by `HttpContentTransport`'s XHR
+          // path; ignored by ky-path uploads (no `onProgress` consumer)
+          // and by `LocalContentTransport` (no wire to observe).
+          onProgress: ({ bytesUploaded, totalBytes: txTotal }) => {
+            if (cancelled) return;
+            const total = txTotal > 0 ? txTotal : totalBytes;
+            subscriber.next({ phase: "progress", bytesUploaded, totalBytes: total });
+          },
+          signal: abortController.signal
+        }
+      ).then((result) => {
+        if (cancelled) return;
+        subscriber.next({
+          phase: "finished",
+          resourceId: resourceId(result.resourceId)
+        });
+        subscriber.complete();
+      }).catch((err) => {
+        if (!cancelled) subscriber.error(err);
+      });
+      return () => {
+        cancelled = true;
+        abortController.abort();
+      };
     });
-    return { resourceId: result.resourceId };
   }
-  fromAnnotation(resourceId, annotationId, options) {
-    return new Observable((subscriber) => {
+  fromAnnotation(resourceId2, annotationId2, options) {
+    return new StreamObservable((subscriber) => {
       let done = false;
       let pollTimer = null;
       let pollInterval = null;
@@ -820,7 +903,7 @@ var YieldNamespace = class {
                   data: {
                     jobId: jid,
                     jobType: status.jobType ?? "generation",
-                    resourceId,
+                    resourceId: resourceId2,
                     result: status.result
                   }
                 });
@@ -862,12 +945,13 @@ var YieldNamespace = class {
         "job:create",
         {
           jobType: "generation",
-          resourceId,
+          resourceId: resourceId2,
           params: {
-            referenceId: annotationId,
+            referenceId: annotationId2,
             title: options.title,
             prompt: options.prompt,
             language: options.language,
+            sourceLanguage: options.sourceLanguage,
             temperature: options.temperature,
             maxTokens: options.maxTokens,
             storageUri: options.storageUri,
@@ -893,11 +977,11 @@ var YieldNamespace = class {
       };
     });
   }
-  async cloneToken(resourceId) {
+  async cloneToken(resourceId2) {
     return busRequest(
       this.transport,
       "yield:clone-token-requested",
-      { resourceId },
+      { resourceId: resourceId2 },
       "yield:clone-token-generated",
       "yield:clone-token-failed"
     );
@@ -913,13 +997,14 @@ var YieldNamespace = class {
     return result.sourceResource;
   }
   async createFromToken(options) {
-    return busRequest(
+    const result = await busRequest(
       this.transport,
       "yield:clone-create",
       options,
       "yield:clone-created",
       "yield:clone-create-failed"
     );
+    return { resourceId: resourceId(result.resourceId) };
   }
   clone() {
     this.bus.get("yield:clone").next(void 0);
@@ -932,14 +1017,29 @@ var BeckonNamespace = class {
     this.transport = transport;
     this.bus = bus;
   }
-  attention(annotationId, resourceId) {
-    void this.transport.emit("beckon:focus", { annotationId, resourceId });
+  attention(resourceId2, annotationId2) {
+    void this.transport.emit("beckon:focus", { annotationId: annotationId2, resourceId: resourceId2 });
   }
-  hover(annotationId) {
-    this.bus.get("beckon:hover").next({ annotationId });
+  hover(annotationId2) {
+    this.bus.get("beckon:hover").next({ annotationId: annotationId2 });
   }
-  sparkle(annotationId) {
-    this.bus.get("beckon:sparkle").next({ annotationId });
+  sparkle(annotationId2) {
+    this.bus.get("beckon:sparkle").next({ annotationId: annotationId2 });
+  }
+};
+
+// src/namespaces/frame.ts
+var FrameNamespace = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  async addEntityType(type) {
+    await this.transport.emit("frame:add-entity-type", { tag: type });
+  }
+  async addEntityTypes(types) {
+    for (const tag of types) {
+      await this.transport.emit("frame:add-entity-type", { tag });
+    }
   }
 };
 
@@ -980,7 +1080,7 @@ var JobNamespace = class {
   }
   async pollUntilComplete(jobId, options) {
     const interval = options?.interval ?? 1e3;
-    const timeout7 = options?.timeout ?? 6e4;
+    const timeout6 = options?.timeout ?? 6e4;
     const startTime = Date.now();
     while (true) {
       const status = await this.status(jobId);
@@ -988,90 +1088,98 @@ var JobNamespace = class {
       if (status.status === "complete" || status.status === "failed" || status.status === "cancelled") {
         return status;
       }
-      if (Date.now() - startTime > timeout7) {
-        throw new Error(`Job polling timeout after ${timeout7}ms`);
+      if (Date.now() - startTime > timeout6) {
+        throw new Error(`Job polling timeout after ${timeout6}ms`);
       }
       await new Promise((resolve) => setTimeout(resolve, interval));
     }
   }
-  async cancel(_jobId, type) {
-    await this.transport.emit("job:cancel-requested", {
-      jobType: type === "generation" ? "generation" : "annotation"
-    });
+  async cancelByType(jobType) {
+    await this.transport.emit("job:cancel-requested", { jobType });
   }
   cancelRequest(jobType) {
     this.bus.get("job:cancel-requested").next({ jobType });
   }
 };
 var AuthNamespace = class {
-  constructor(transport) {
-    this.transport = transport;
+  constructor(backend) {
+    this.backend = backend;
   }
   async password(emailStr, passwordStr) {
-    return this.transport.authenticatePassword(email(emailStr), passwordStr);
+    return this.backend.authenticatePassword(email(emailStr), passwordStr);
   }
   async google(credential) {
-    return this.transport.authenticateGoogle(googleCredential(credential));
+    return this.backend.authenticateGoogle(googleCredential(credential));
   }
   async refresh(token) {
-    return this.transport.refreshAccessToken(refreshToken(token));
+    return this.backend.refreshAccessToken(refreshToken(token));
   }
   async logout() {
-    await this.transport.logout();
+    await this.backend.logout();
   }
   async me() {
-    return this.transport.getCurrentUser();
+    return this.backend.getCurrentUser();
   }
   async acceptTerms() {
-    await this.transport.acceptTerms();
+    await this.backend.acceptTerms();
   }
   async mcpToken() {
-    return this.transport.generateMcpToken();
+    return this.backend.generateMcpToken();
   }
-  async mediaToken(resourceId) {
-    return this.transport.getMediaToken(resourceId);
+  async mediaToken(resourceId2) {
+    return this.backend.getMediaToken(resourceId2);
   }
 };
 
 // src/namespaces/admin.ts
 var AdminNamespace = class {
-  constructor(transport) {
-    this.transport = transport;
+  constructor(backend) {
+    this.backend = backend;
   }
   async users() {
-    const result = await this.transport.listUsers();
+    const result = await this.backend.listUsers();
     return result.users;
   }
   async userStats() {
-    return this.transport.getUserStats();
+    return this.backend.getUserStats();
   }
-  async updateUser(userId, data) {
-    const result = await this.transport.updateUser(userId, data);
+  async updateUser(userId2, data) {
+    const result = await this.backend.updateUser(userId2, data);
     return result.user;
   }
   async oauthConfig() {
-    return this.transport.getOAuthConfig();
+    return this.backend.getOAuthConfig();
   }
   async healthCheck() {
-    return this.transport.healthCheck();
+    return this.backend.healthCheck();
   }
   async status() {
-    return this.transport.getStatus();
+    return this.backend.getStatus();
   }
   async backup() {
-    return this.transport.backupKnowledgeBase();
+    return this.backend.backupKnowledgeBase();
   }
-  async restore(file, onProgress) {
-    return this.transport.restoreKnowledgeBase(file, onProgress);
+  restore(file) {
+    return wrapAsStream(this.backend.restoreKnowledgeBase(file));
   }
   async exportKnowledgeBase(params) {
-    return this.transport.exportKnowledgeBase(params);
+    return this.backend.exportKnowledgeBase(params);
   }
-  async importKnowledgeBase(file, onProgress) {
-    return this.transport.importKnowledgeBase(file, onProgress);
+  importKnowledgeBase(file) {
+    return wrapAsStream(this.backend.importKnowledgeBase(file));
   }
 };
-var SemiontClient = class {
+function wrapAsStream(source) {
+  return new StreamObservable((subscriber) => {
+    const sub = source.subscribe({
+      next: (v) => subscriber.next(v),
+      error: (e) => subscriber.error(e),
+      complete: () => subscriber.complete()
+    });
+    return () => sub.unsubscribe();
+  });
+}
+var SemiontClient = class _SemiontClient {
   /**
    * The wire-facing transport. Owns bus actor, HTTP, auth, admin, exchange,
    * system. Exposed for advanced consumers (workers, custom job adapters)
@@ -1090,6 +1198,15 @@ var SemiontClient = class {
   bus;
   baseUrl;
   // ── Verb-oriented namespace API ──────────────────────────────────────────
+  //
+  // The first nine namespaces are bus-driven and always present. `frame`
+  // is the schema-layer flow's surface (eighth flow); the other eight are
+  // content-layer flows plus `job`. `auth` and `admin` are backend-ops
+  // namespaces — they're only constructed when the caller passes an
+  // `IBackendOperations` instance to the constructor. A `SemiontClient`
+  // over a transport-only setup (e.g. `LocalTransport`) has
+  // `auth === undefined` / `admin === undefined`.
+  frame;
   browse;
   mark;
   bind;
@@ -1112,13 +1229,20 @@ var SemiontClient = class {
    * 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, content) {
+  constructor(transport, content, backend) {
     this.transport = transport;
     this.content = content;
     this.baseUrl = transport.baseUrl;
     this.bus = new EventBus();
     this.transport.bridgeInto(this.bus);
+    this.frame = new FrameNamespace(this.transport);
     this.browse = new BrowseNamespace(this.transport, this.bus, this.content);
     this.mark = new MarkNamespace(this.transport, this.bus);
     this.bind = new BindNamespace(this.transport, this.bus);
@@ -1127,20 +1251,88 @@ var SemiontClient = class {
     this.yield = new YieldNamespace(this.transport, this.bus, this.content);
     this.beckon = new BeckonNamespace(this.transport, this.bus);
     this.job = new JobNamespace(this.transport, this.bus);
-    this.auth = new AuthNamespace(this.transport);
-    this.admin = new AdminNamespace(this.transport);
+    this.auth = backend ? new AuthNamespace(backend) : void 0;
+    this.admin = backend ? new AdminNamespace(backend) : void 0;
   }
   /** Transport-level connection state. HTTP reflects SSE health; local is always 'connected'. */
   get state$() {
     return this.transport.state$;
   }
-  subscribeToResource(resourceId) {
-    return this.transport.subscribeToResource(resourceId);
+  subscribeToResource(resourceId2) {
+    return this.transport.subscribeToResource(resourceId2);
   }
   dispose() {
     this.transport.dispose();
     this.content.dispose();
   }
+  /**
+   * 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) {
+    const url = typeof opts.baseUrl === "string" ? baseUrl(opts.baseUrl) : opts.baseUrl;
+    const tok = opts.token == null ? null : typeof opts.token === "string" ? accessToken(opts.token) : opts.token;
+    const token$ = new BehaviorSubject(tok);
+    const transport = new HttpTransport({ baseUrl: url, token$ });
+    const content = new HttpContentTransport(transport);
+    return new _SemiontClient(transport, content, transport);
+  }
+  /**
+   * 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 async signInHttp(opts) {
+    const url = typeof opts.baseUrl === "string" ? baseUrl(opts.baseUrl) : opts.baseUrl;
+    const token$ = new BehaviorSubject(null);
+    const transport = new HttpTransport({ baseUrl: url, token$ });
+    const content = new HttpContentTransport(transport);
+    const client = new _SemiontClient(transport, content, transport);
+    try {
+      const auth = await client.auth.password(opts.email, opts.password);
+      token$.next(accessToken(auth.token));
+      return client;
+    } catch (err) {
+      client.dispose();
+      throw err;
+    }
+  }
 };
 
 // src/session/storage.ts
@@ -1185,35 +1377,28 @@ function isJwtExpired(token) {
   if (!expiry) return true;
   return expiry.getTime() < Date.now();
 }
-function migrateLegacyEntry(entry) {
-  if (entry.host !== void 0) return entry;
-  try {
-    const url = new URL(entry.backendUrl);
-    return {
-      id: entry.id,
-      label: entry.label,
-      host: url.hostname,
-      port: parseInt(url.port, 10) || (url.protocol === "https:" ? 443 : 80),
-      protocol: url.protocol === "https:" ? "https" : "http",
-      email: ""
-    };
-  } catch {
-    return {
-      id: entry.id,
-      label: entry.label || "Unknown",
-      host: "localhost",
-      port: 4e3,
-      protocol: "http",
-      email: ""
-    };
+function isKnowledgeBase(entry) {
+  if (!entry || typeof entry !== "object") return false;
+  const e = entry;
+  if (typeof e.id !== "string" || typeof e.label !== "string" || typeof e.email !== "string") {
+    return false;
+  }
+  const ep = e.endpoint;
+  if (!ep || typeof ep !== "object") return false;
+  if (ep.kind === "http") {
+    return typeof ep.host === "string" && typeof ep.port === "number" && (ep.protocol === "http" || ep.protocol === "https");
+  }
+  if (ep.kind === "local") {
+    return typeof ep.kbId === "string";
   }
+  return false;
 }
 function loadKnowledgeBases(storage) {
   try {
     const raw = storage.get(STORAGE_KEY);
     if (!raw) return [];
     const entries = JSON.parse(raw);
-    return entries.map(migrateLegacyEntry);
+    return entries.filter(isKnowledgeBase);
   } catch {
     return [];
   }
@@ -1228,39 +1413,47 @@ var HOSTNAME_RE = /^(([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)*[a-zA-Z0-9]
 function isValidHostname(host) {
   return HOSTNAME_RE.test(host);
 }
-function kbBackendUrl(kb) {
-  if (!isValidHostname(kb.host)) {
-    throw new Error(`Invalid KB hostname: "${kb.host}"`);
+function kbBackendUrl(endpoint) {
+  if (!isValidHostname(endpoint.host)) {
+    throw new Error(`Invalid KB hostname: "${endpoint.host}"`);
   }
   const url = new URL("http://x");
-  url.protocol = kb.protocol + ":";
-  url.hostname = kb.host;
-  url.port = String(kb.port);
-  return `${kb.protocol}://${url.hostname}:${kb.port}`;
+  url.protocol = endpoint.protocol + ":";
+  url.hostname = endpoint.host;
+  url.port = String(endpoint.port);
+  return `${endpoint.protocol}://${url.hostname}:${endpoint.port}`;
 }
 function generateKbId() {
   return crypto.randomUUID();
 }
-
-// src/session/errors.ts
-var SemiontError = class extends Error {
-  code;
+var SemiontSessionError = class extends SemiontError {
   kbId;
   constructor(code, message, kbId = null) {
-    super(message);
-    this.name = "SemiontError";
-    this.code = code;
+    super(message, code, { kbId });
+    this.name = "SemiontSessionError";
     this.kbId = kbId;
   }
 };
 
 // src/session/semiont-session.ts
-var SemiontSession = class {
+var SemiontSession = class _SemiontSession {
   kb;
   client;
   token$;
   user$;
   streamState$;
+  /**
+   * 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.
+   */
+  errors$;
   /** Resolves after the initial validation round-trip completes (success or failure). */
   ready;
   storage;
@@ -1283,6 +1476,7 @@ var SemiontSession = class {
     this.client = config.client;
     this.token$ = config.token$;
     this.user$ = new BehaviorSubject(null);
+    this.errors$ = this.client.transport.errors$;
     const stored = getStoredSession(this.storage, this.kb.id);
     if (stored && !isJwtExpired(stored.access) && this.token$.getValue() === null) {
       this.token$.next(accessToken(stored.access));
@@ -1344,7 +1538,7 @@ var SemiontSession = class {
           this.onAuthFailed("Your session has expired. Please sign in again.");
         } else {
           this.onError(
-            new SemiontError(
+            new SemiontSessionError(
               "session.auth-failed",
               err instanceof Error ? err.message : String(err),
               this.kb.id
@@ -1377,7 +1571,7 @@ var SemiontSession = class {
     clearStoredSession(this.storage, this.kb.id);
     this.onAuthFailed("Your session has expired. Please sign in again.");
     this.onError(
-      new SemiontError("session.refresh-exhausted", "Token refresh failed", this.kb.id)
+      new SemiontSessionError("session.refresh-exhausted", "Token refresh failed", this.kb.id)
     );
     return null;
   }
@@ -1448,26 +1642,102 @@ var SemiontSession = class {
     this.token$.complete();
     this.user$.complete();
   }
+  /**
+   * 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) {
+    const url = typeof opts.baseUrl === "string" ? baseUrl(opts.baseUrl) : opts.baseUrl;
+    const tok = opts.token == null ? null : typeof opts.token === "string" ? accessToken(opts.token) : opts.token;
+    const token$ = new BehaviorSubject(tok);
+    const transport = new HttpTransport({ baseUrl: url, token$ });
+    const content = new HttpContentTransport(transport);
+    const client = new SemiontClient(transport, content, transport);
+    const config = { kb: opts.kb, storage: opts.storage, client, token$ };
+    if (opts.refresh) config.refresh = opts.refresh;
+    if (opts.validate) config.validate = opts.validate;
+    if (opts.onAuthFailed) config.onAuthFailed = opts.onAuthFailed;
+    if (opts.onError) config.onError = opts.onError;
+    return new _SemiontSession(config);
+  }
+  /**
+   * 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 async signInHttp(opts) {
+    const url = typeof opts.baseUrl === "string" ? baseUrl(opts.baseUrl) : opts.baseUrl;
+    const token$ = new BehaviorSubject(null);
+    const transport = new HttpTransport({ baseUrl: url, token$ });
+    const content = new HttpContentTransport(transport);
+    const client = new SemiontClient(transport, content, transport);
+    let auth;
+    try {
+      auth = await client.auth.password(opts.email, opts.password);
+    } catch (err) {
+      client.dispose();
+      throw err;
+    }
+    setStoredSession(opts.storage, opts.kb.id, { access: auth.token, refresh: auth.refreshToken });
+    token$.next(accessToken(auth.token));
+    const defaultRefresh = async () => {
+      const stored = getStoredSession(opts.storage, opts.kb.id);
+      if (!stored) return null;
+      try {
+        const response = await client.auth.refresh(stored.refresh);
+        return response.access_token;
+      } catch {
+        return null;
+      }
+    };
+    const config = {
+      kb: opts.kb,
+      storage: opts.storage,
+      client,
+      token$,
+      refresh: defaultRefresh
+    };
+    if (opts.validate) config.validate = opts.validate;
+    if (opts.onAuthFailed) config.onAuthFailed = opts.onAuthFailed;
+    if (opts.onError) config.onError = opts.onError;
+    const session = new _SemiontSession(config);
+    await session.ready;
+    return session;
+  }
 };
-
-// src/session/notify.ts
-var activeOnSessionExpired = null;
-var activeOnPermissionDenied = null;
-function notifySessionExpired(message) {
-  activeOnSessionExpired?.(message);
-}
-function notifyPermissionDenied(message) {
-  activeOnPermissionDenied?.(message);
-}
-function registerAuthNotifyHandlers(handlers) {
-  activeOnSessionExpired = handlers.onSessionExpired;
-  activeOnPermissionDenied = handlers.onPermissionDenied;
-  return () => {
-    activeOnSessionExpired = null;
-    activeOnPermissionDenied = null;
-  };
-}
-var FrontendSessionSignals = class {
+var SessionSignals = class {
   sessionExpiredAt$;
   sessionExpiredMessage$;
   permissionDeniedAt$;
@@ -1532,7 +1802,7 @@ var SemiontBrowser = class {
    * 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).
    */
   activeSignals$;
   /**
@@ -1548,6 +1818,7 @@ var SemiontBrowser = class {
   error$;
   identityToken$;
   storage;
+  sessionFactory;
   /**
    * App-scoped EventBus. Hosts UI-shell events that must work regardless
    * of whether a KB session is active: panel toggles, sidebar state,
@@ -1556,20 +1827,12 @@ var SemiontBrowser = class {
    * (mark:*, beckon:*, gather:*, match:*, bind:*, yield:*, browse:click).
    */
   eventBus = new EventBus();
-  unregisterNotify = null;
   unsubscribeStorage = null;
   disposed = false;
   activating = null;
-  /**
-   * 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.
-   */
-  inFlightRefreshes = /* @__PURE__ */ new Map();
   constructor(config) {
     this.storage = config.storage;
+    this.sessionFactory = config.sessionFactory;
     const kbs = loadKnowledgeBases(this.storage);
     const storedActive = this.storage.get(ACTIVE_KEY);
     const initialActive = storedActive && kbs.some((kb) => kb.id === storedActive) ? storedActive : kbs[0]?.id ?? null;
@@ -1596,14 +1859,6 @@ var SemiontBrowser = class {
       } catch {
       }
     }) ?? null;
-    this.unregisterNotify = registerAuthNotifyHandlers({
-      onSessionExpired: (message) => {
-        this.activeSignals$.getValue()?.notifySessionExpired(message ?? null);
-      },
-      onPermissionDenied: (message) => {
-        this.activeSignals$.getValue()?.notifyPermissionDenied(message ?? null);
-      }
-    });
     if (initialActive) {
       void this.setActiveKb(initialActive);
     }
@@ -1625,9 +1880,10 @@ var SemiontBrowser = class {
   }
   // ── Identity token (NextAuth bridge; D1) ──────────────────────────────
   /**
-   * 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) {
     if (this.disposed) return;
@@ -1649,6 +1905,12 @@ var SemiontBrowser = class {
       void this.setActiveKb(next[0]?.id ?? null);
     }
   }
+  /**
+   * 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, updates) {
     this.kbs$.next(
       this.kbs$.getValue().map((kb) => kb.id === id ? { ...kb, ...updates } : kb)
@@ -1704,31 +1966,38 @@ var SemiontBrowser = class {
       if (!id) return;
       const kb = this.kbs$.getValue().find((k) => k.id === id);
       if (!kb) return;
-      const signals = new FrontendSessionSignals();
-      const token$ = new BehaviorSubject(null);
+      const signals = new SessionSignals();
       let session;
-      const transport = new HttpTransport({
-        baseUrl: baseUrl(kbBackendUrl(kb)),
-        token$,
-        tokenRefresher: () => session.refresh().then((t) => t ?? null)
-      });
-      const content = new HttpContentTransport(transport);
-      const client = new SemiontClient(transport, content);
-      session = new SemiontSession({
-        kb,
-        storage: this.storage,
-        client,
-        token$,
-        refresh: () => this.performRefresh(kb),
-        validate: (token) => this.performValidate(kb, token),
-        onAuthFailed: (msg) => signals.notifySessionExpired(msg),
-        onError: (err) => this.error$.next(err)
+      try {
+        session = this.sessionFactory({
+          kb,
+          storage: this.storage,
+          signals,
+          onError: (err) => this.error$.next(err)
+        });
+      } catch (err) {
+        this.error$.next(
+          err instanceof SemiontSessionError ? err : new SemiontSessionError(
+            "session.construct-failed",
+            err instanceof Error ? err.message : String(err),
+            id
+          )
+        );
+        signals.dispose();
+        return;
+      }
+      session.errors$.subscribe((err) => {
+        if (err.code === "unauthorized") {
+          signals.notifySessionExpired(err.message);
+        } else if (err.code === "forbidden") {
+          signals.notifyPermissionDenied(err.message);
+        }
       });
       try {
         await session.ready;
       } catch (err) {
         this.error$.next(
-          new SemiontError(
+          new SemiontSessionError(
             "session.construct-failed",
             err instanceof Error ? err.message : String(err),
             id
@@ -1838,80 +2107,10 @@ var SemiontBrowser = class {
     if (moved) list.splice(newIndex, 0, moved);
     this.openResources$.next(list);
   }
-  // ── Auth callbacks bound per session ──────────────────────────────────
-  //
-  // These closures back the `refresh` and `validate` callbacks passed
-  // to `SemiontSession` in `setActiveKb`. Factored out as methods
-  // (rather than inline in the activation closure) so test-doubles
-  // can override them cleanly, and so the in-flight dedup map
-  // survives across activations of the same KB.
-  /**
-   * 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.
-   */
-  async performRefresh(kb) {
-    const existing = this.inFlightRefreshes.get(kb.id);
-    if (existing) return existing;
-    const promise = (async () => {
-      const stored = getStoredSession(this.storage, kb.id);
-      if (!stored) return null;
-      const throwawayTransport = new HttpTransport({ baseUrl: baseUrl(kbBackendUrl(kb)) });
-      const throwaway = new SemiontClient(throwawayTransport, new HttpContentTransport(throwawayTransport));
-      try {
-        const response = await throwaway.auth.refresh(stored.refresh);
-        const newAccess = response.access_token;
-        if (!newAccess) return null;
-        setStoredSession(this.storage, kb.id, { access: newAccess, refresh: stored.refresh });
-        return newAccess;
-      } catch {
-        return null;
-      } finally {
-        throwaway.dispose();
-      }
-    })();
-    this.inFlightRefreshes.set(kb.id, promise);
-    try {
-      return await promise;
-    } finally {
-      this.inFlightRefreshes.delete(kb.id);
-    }
-  }
-  /**
-   * 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$`).
-   */
-  async performValidate(kb, token) {
-    const tokenSubject = new BehaviorSubject(token);
-    const throwawayTransport = new HttpTransport({
-      baseUrl: baseUrl(kbBackendUrl(kb)),
-      token$: tokenSubject
-    });
-    const throwaway = new SemiontClient(throwawayTransport, new HttpContentTransport(throwawayTransport));
-    try {
-      const data = await throwaway.auth.me();
-      return data;
-    } finally {
-      throwaway.dispose();
-      tokenSubject.complete();
-    }
-  }
   // ── Lifecycle ─────────────────────────────────────────────────────────
   async dispose() {
     if (this.disposed) return;
     this.disposed = true;
-    this.unregisterNotify?.();
-    this.unregisterNotify = null;
     if (this.unsubscribeStorage) {
       this.unsubscribeStorage();
       this.unsubscribeStorage = null;
@@ -1932,12 +2131,91 @@ var SemiontBrowser = class {
     this.eventBus.destroy();
   }
 };
+function createHttpSessionFactory() {
+  const inFlightRefreshes = /* @__PURE__ */ new Map();
+  return (opts) => {
+    const { kb, storage, signals, onError } = opts;
+    if (kb.endpoint.kind !== "http") {
+      throw new SemiontSessionError(
+        "session.construct-failed",
+        `HTTP session factory cannot construct a session for endpoint kind "${kb.endpoint.kind}"`,
+        kb.id
+      );
+    }
+    const endpoint = kb.endpoint;
+    const performRefresh = async () => {
+      const existing = inFlightRefreshes.get(kb.id);
+      if (existing) return existing;
+      const promise = (async () => {
+        const stored = getStoredSession(storage, kb.id);
+        if (!stored) return null;
+        const throwawayTransport = new HttpTransport({ baseUrl: baseUrl(kbBackendUrl(endpoint)) });
+        const throwaway = new SemiontClient(throwawayTransport, new HttpContentTransport(throwawayTransport), throwawayTransport);
+        try {
+          const response = await throwaway.auth.refresh(stored.refresh);
+          const newAccess = response.access_token;
+          if (!newAccess) return null;
+          setStoredSession(storage, kb.id, { access: newAccess, refresh: stored.refresh });
+          return newAccess;
+        } catch {
+          return null;
+        } finally {
+          throwaway.dispose();
+        }
+      })();
+      inFlightRefreshes.set(kb.id, promise);
+      try {
+        return await promise;
+      } finally {
+        inFlightRefreshes.delete(kb.id);
+      }
+    };
+    const performValidate = async (token) => {
+      const tokenSubject = new BehaviorSubject(token);
+      const throwawayTransport = new HttpTransport({
+        baseUrl: baseUrl(kbBackendUrl(endpoint)),
+        token$: tokenSubject
+      });
+      const throwaway = new SemiontClient(throwawayTransport, new HttpContentTransport(throwawayTransport), throwawayTransport);
+      try {
+        const data = await throwaway.auth.me();
+        return data;
+      } finally {
+        throwaway.dispose();
+        tokenSubject.complete();
+      }
+    };
+    const token$ = new BehaviorSubject(null);
+    let session;
+    const transport = new HttpTransport({
+      baseUrl: baseUrl(kbBackendUrl(endpoint)),
+      token$,
+      tokenRefresher: () => session.refresh().then((t) => t ?? null)
+    });
+    const content = new HttpContentTransport(transport);
+    const client = new SemiontClient(transport, content, transport);
+    session = new SemiontSession({
+      kb,
+      storage,
+      client,
+      token$,
+      refresh: performRefresh,
+      validate: performValidate,
+      onAuthFailed: (msg) => signals.notifySessionExpired(msg),
+      onError
+    });
+    return session;
+  };
+}
 
 // src/session/registry.ts
 var instance = null;
 function getBrowser(options) {
   if (!instance) {
-    instance = new SemiontBrowser({ storage: options.storage });
+    instance = new SemiontBrowser({
+      storage: options.storage,
+      sessionFactory: options.sessionFactory
+    });
   }
   return instance;
 }
@@ -1955,6 +2233,18 @@ var InMemorySessionStorage = class {
     this.map.delete(key);
   }
 };
+
+// src/session/knowledge-base.ts
+function httpKb(opts) {
+  const { id, label, email, host, port, protocol, gitBranch } = opts;
+  return {
+    id,
+    label,
+    email,
+    ...gitBranch !== void 0 ? { gitBranch } : {},
+    endpoint: { kind: "http", host, port, protocol }
+  };
+}
 function createDisposer() {
   const sub = new Subscription();
   return {
@@ -1970,7 +2260,7 @@ function createSearchPipeline(fetch, options = {}) {
   const state$ = input$.pipe(
     startWith(initial),
     debounceTime(debounceMs),
-    distinctUntilChanged$1(),
+    distinctUntilChanged(),
     switchMap((q) => {
       const trimmed = q.trim();
       if (!trimmed) {
@@ -1992,23 +2282,23 @@ function createSearchPipeline(fetch, options = {}) {
     dispose: () => input$.complete()
   };
 }
-function createBeckonVM(client) {
+function createBeckonStateUnit(client) {
   const subs = [];
   const hovered$ = new BehaviorSubject(null);
-  subs.push(client.bus.get("beckon:hover").subscribe(({ annotationId }) => {
-    hovered$.next(annotationId);
-    if (annotationId) {
-      client.bus.get("beckon:sparkle").next({ annotationId });
+  subs.push(client.bus.get("beckon:hover").subscribe(({ annotationId: annotationId2 }) => {
+    hovered$.next(annotationId2);
+    if (annotationId2) {
+      client.bus.get("beckon:sparkle").next({ annotationId: annotationId2 });
     }
   }));
-  subs.push(client.bus.get("browse:click").subscribe(({ annotationId }) => {
-    client.bus.get("beckon:focus").next({ annotationId });
+  subs.push(client.bus.get("browse:click").subscribe(({ annotationId: annotationId2 }) => {
+    client.bus.get("beckon:focus").next({ annotationId: annotationId2 });
   }));
   return {
     hoveredAnnotationId$: hovered$.asObservable(),
-    hover: (annotationId) => client.bus.get("beckon:hover").next({ annotationId }),
-    focus: (annotationId) => client.bus.get("beckon:focus").next({ annotationId }),
-    sparkle: (annotationId) => client.bus.get("beckon:sparkle").next({ annotationId }),
+    hover: (annotationId2) => client.bus.get("beckon:hover").next({ annotationId: annotationId2 }),
+    focus: (annotationId2) => client.bus.get("beckon:focus").next({ annotationId: annotationId2 }),
+    sparkle: (annotationId2) => client.bus.get("beckon:sparkle").next({ annotationId: annotationId2 }),
     dispose() {
       subs.forEach((s) => s.unsubscribe());
       hovered$.complete();
@@ -2025,13 +2315,13 @@ function createHoverHandlers(emit, delayMs) {
       timer = null;
     }
   };
-  const handleMouseEnter = (annotationId) => {
-    if (currentHover === annotationId) return;
+  const handleMouseEnter = (annotationId2) => {
+    if (currentHover === annotationId2) return;
     cancelTimer();
     timer = setTimeout(() => {
       timer = null;
-      currentHover = annotationId;
-      emit(annotationId);
+      currentHover = annotationId2;
+      emit(annotationId2);
     }, delayMs);
   };
   const handleMouseLeave = () => {
@@ -2043,59 +2333,7 @@ function createHoverHandlers(emit, delayMs) {
   };
   return { handleMouseEnter, handleMouseLeave, cleanup: cancelTimer };
 }
-var COMMON_PANELS = ["knowledge-base", "user", "settings"];
-var RESOURCE_PANELS = ["history", "info", "annotations", "collaboration", "jsonld"];
-var MOTIVATION_TO_TAB = {
-  "linking": "reference",
-  "commenting": "comment",
-  "tagging": "tag",
-  "highlighting": "highlight",
-  "assessing": "assessment"
-};
-var tabGenerationCounter = 0;
-function createShellVM(browser, options) {
-  const subs = [];
-  const activePanel$ = new BehaviorSubject(options?.initialPanel ?? null);
-  const scrollToAnnotationId$ = new BehaviorSubject(null);
-  const panelInitialTab$ = new BehaviorSubject(null);
-  if (options?.onPanelChange) {
-    const cb = options.onPanelChange;
-    subs.push(activePanel$.subscribe(cb));
-  }
-  subs.push(browser.stream("panel:toggle").subscribe(({ panel }) => {
-    const current = activePanel$.getValue();
-    activePanel$.next(current === panel ? null : panel);
-  }));
-  subs.push(browser.stream("panel:open").subscribe(({ panel, scrollToAnnotationId, motivation }) => {
-    if (scrollToAnnotationId) {
-      scrollToAnnotationId$.next(scrollToAnnotationId);
-    }
-    if (motivation) {
-      const tab = MOTIVATION_TO_TAB[motivation] || "highlight";
-      panelInitialTab$.next({ tab, generation: ++tabGenerationCounter });
-    }
-    activePanel$.next(panel);
-  }));
-  subs.push(browser.stream("panel:close").subscribe(() => {
-    activePanel$.next(null);
-  }));
-  return {
-    activePanel$: activePanel$.asObservable(),
-    scrollToAnnotationId$: scrollToAnnotationId$.asObservable(),
-    panelInitialTab$: panelInitialTab$.asObservable(),
-    openPanel: (panel) => browser.emit("panel:open", { panel }),
-    closePanel: () => browser.emit("panel:close", void 0),
-    togglePanel: (panel) => browser.emit("panel:toggle", { panel }),
-    onScrollCompleted: () => scrollToAnnotationId$.next(null),
-    dispose() {
-      subs.forEach((s) => s.unsubscribe());
-      activePanel$.complete();
-      scrollToAnnotationId$.complete();
-      panelInitialTab$.complete();
-    }
-  };
-}
-function createGatherVM(client, resourceId) {
+function createGatherStateUnit(client, resourceId2) {
   const subs = [];
   const context$ = new BehaviorSubject(null);
   const loading$ = new BehaviorSubject(false);
@@ -2107,8 +2345,8 @@ function createGatherVM(client, resourceId) {
     context$.next(null);
     annotationId$.next(annotationId(event.annotationId));
     const gatherSub = client.gather.annotation(
+      resourceId2,
       annotationId(event.annotationId),
-      resourceId,
       { contextWindow: event.options?.contextWindow ?? 2e3 }
     ).pipe(
       timeout(6e4)
@@ -2145,12 +2383,12 @@ function createGatherVM(client, resourceId) {
     }
   };
 }
-function createMatchVM(client, _resourceId) {
+function createMatchStateUnit(client, _resourceId) {
   const subs = [];
   subs.push(client.bus.get("match:search-requested").subscribe((event) => {
     const searchSub = client.match.search(
       resourceId(event.resourceId),
-      event.referenceId,
+      annotationId(event.referenceId),
       event.context,
       { limit: event.limit, useSemanticScoring: event.useSemanticScoring }
     ).pipe(
@@ -2171,14 +2409,14 @@ function createMatchVM(client, _resourceId) {
     }
   };
 }
-function createYieldVM(client, resourceId$1, locale) {
+function createYieldStateUnit(client, resourceId2, locale) {
   const subs = [];
   const isGenerating$ = new BehaviorSubject(false);
   const progress$ = new BehaviorSubject(null);
   let clearTimer = null;
   const generate = (referenceId, options) => {
     const genSub = client.yield.fromAnnotation(
-      resourceId(resourceId$1),
+      resourceId(resourceId2),
       annotationId(referenceId),
       { ...options, language: options.language || locale }
     ).pipe(
@@ -2226,7 +2464,7 @@ function selectionToSelector(selection) {
   }
   return { type: "TextQuoteSelector", exact: selection.exact, ...selection.prefix && { prefix: selection.prefix }, ...selection.suffix && { suffix: selection.suffix } };
 }
-function createMarkVM(client, resourceId) {
+function createMarkStateUnit(client, resourceId2) {
   const subs = [];
   const pendingAnnotation$ = new BehaviorSubject(null);
   const assistingMotivation$ = new BehaviorSubject(null);
@@ -2250,9 +2488,9 @@ function createMarkVM(client, resourceId) {
   subs.push(client.bus.get("mark:create-ok").subscribe(() => pendingAnnotation$.next(null)));
   subs.push(client.bus.get("mark:submit").subscribe(async (event) => {
     try {
-      const result = await client.mark.annotation(resourceId, {
+      const result = await client.mark.annotation({
         motivation: event.motivation,
-        target: { source: resourceId, selector: event.selector },
+        target: { source: resourceId2, selector: event.selector },
         body: event.body
       });
       client.bus.get("mark:create-ok").next({ annotationId: result.annotationId });
@@ -2262,7 +2500,7 @@ function createMarkVM(client, resourceId) {
   }));
   subs.push(client.bus.get("mark:delete").subscribe(async (event) => {
     try {
-      await client.mark.delete(resourceId, event.annotationId);
+      await client.mark.delete(resourceId2, event.annotationId);
       client.bus.get("mark:delete-ok").next({ annotationId: event.annotationId });
     } catch (error) {
       client.bus.get("mark:delete-failed").next({ message: error instanceof Error ? error.message : String(error) });
@@ -2272,7 +2510,7 @@ function createMarkVM(client, resourceId) {
     clearProgressTimer();
     assistingMotivation$.next(event.motivation);
     progress$.next(null);
-    const assistSub = client.mark.assist(resourceId, event.motivation, event.options).pipe(
+    const assistSub = client.mark.assist(resourceId2, event.motivation, event.options).pipe(
       timeout({ each: 18e4 })
     ).subscribe({
       next: (e) => {
@@ -2311,720 +2549,7 @@ function createMarkVM(client, resourceId) {
     }
   };
 }
-var RECENT_LIMIT = 10;
-var SEARCH_LIMIT = 20;
-function createDiscoverVM(client, browse) {
-  const disposer = createDisposer();
-  const search = createSearchPipeline(
-    (q) => client.browse.resources({ search: q, limit: SEARCH_LIMIT })
-  );
-  disposer.add(search);
-  disposer.add(browse);
-  const recent$ = client.browse.resources({ limit: RECENT_LIMIT, archived: false });
-  const recentResources$ = recent$.pipe(
-    map$1((r) => r ?? [])
-  );
-  const isLoadingRecent$ = recent$.pipe(
-    map$1((r) => r === void 0)
-  );
-  const entityTypes$ = client.browse.entityTypes().pipe(
-    map$1((e) => e ?? [])
-  );
-  return {
-    browse,
-    search,
-    recentResources$,
-    entityTypes$,
-    isLoadingRecent$,
-    dispose: () => disposer.dispose()
-  };
-}
-function createEntityTagsVM(client, browse) {
-  const disposer = createDisposer();
-  disposer.add(browse);
-  const newTag$ = new BehaviorSubject("");
-  const error$ = new BehaviorSubject("");
-  const isAdding$ = new BehaviorSubject(false);
-  const raw$ = client.browse.entityTypes();
-  const entityTypes$ = raw$.pipe(map$1((e) => e ?? []));
-  const isLoading$ = raw$.pipe(map$1((e) => e === void 0));
-  const addTag = async () => {
-    const tag = newTag$.getValue().trim();
-    if (!tag) return;
-    error$.next("");
-    isAdding$.next(true);
-    try {
-      await client.mark.entityType(tag);
-      newTag$.next("");
-    } catch (err) {
-      error$.next(err instanceof Error ? err.message : "Failed to add entity type");
-    } finally {
-      isAdding$.next(false);
-    }
-  };
-  return {
-    browse,
-    entityTypes$,
-    isLoading$,
-    newTag$: newTag$.asObservable(),
-    error$: error$.asObservable(),
-    isAdding$: isAdding$.asObservable(),
-    setNewTag: (v) => newTag$.next(v),
-    addTag,
-    dispose: () => {
-      newTag$.complete();
-      error$.complete();
-      isAdding$.complete();
-      disposer.dispose();
-    }
-  };
-}
-function createExchangeVM(browse, exportFn, importFn) {
-  const disposer = createDisposer();
-  disposer.add(browse);
-  const selectedFile$ = new BehaviorSubject(null);
-  const preview$ = new BehaviorSubject(null);
-  const importPhase$ = new BehaviorSubject(null);
-  const importMessage$ = new BehaviorSubject(void 0);
-  const importResult$ = new BehaviorSubject(void 0);
-  const isExporting$ = new BehaviorSubject(false);
-  const isImporting$ = new BehaviorSubject(false);
-  const selectFile = (file) => {
-    selectedFile$.next(file);
-    importPhase$.next(null);
-    importMessage$.next(void 0);
-    importResult$.next(void 0);
-    preview$.next({
-      format: file.name.endsWith(".tar.gz") || file.name.endsWith(".gz") ? "semiont-linked-data" : "unknown",
-      version: 1,
-      sourceUrl: "",
-      stats: {}
-    });
-  };
-  const cancelImport = () => {
-    selectedFile$.next(null);
-    preview$.next(null);
-    importPhase$.next(null);
-    importMessage$.next(void 0);
-    importResult$.next(void 0);
-  };
-  const doExport = async () => {
-    isExporting$.next(true);
-    try {
-      const response = await exportFn();
-      if (!response.ok) throw new Error(`Export failed: ${response.status} ${response.statusText}`);
-      const blob = await response.blob();
-      const contentDisposition = response.headers.get("Content-Disposition");
-      const filename = contentDisposition?.match(/filename="(.+?)"/)?.[1] ?? `semiont-export-${Date.now()}.tar.gz`;
-      return { blob, filename };
-    } finally {
-      isExporting$.next(false);
-    }
-  };
-  const doImport = async () => {
-    const file = selectedFile$.getValue();
-    if (!file) return;
-    isImporting$.next(true);
-    importPhase$.next("started");
-    importMessage$.next(void 0);
-    importResult$.next(void 0);
-    try {
-      await importFn(file, {
-        onProgress: (event) => {
-          importPhase$.next(event.phase);
-          importMessage$.next(event.message);
-          if (event.result) importResult$.next(event.result);
-        }
-      });
-    } finally {
-      isImporting$.next(false);
-    }
-  };
-  return {
-    browse,
-    selectedFile$: selectedFile$.asObservable(),
-    preview$: preview$.asObservable(),
-    importPhase$: importPhase$.asObservable(),
-    importMessage$: importMessage$.asObservable(),
-    importResult$: importResult$.asObservable(),
-    isExporting$: isExporting$.asObservable(),
-    isImporting$: isImporting$.asObservable(),
-    selectFile,
-    cancelImport,
-    doExport,
-    doImport,
-    dispose: () => {
-      selectedFile$.complete();
-      preview$.complete();
-      importPhase$.complete();
-      importMessage$.complete();
-      importResult$.complete();
-      isExporting$.complete();
-      isImporting$.complete();
-      disposer.dispose();
-    }
-  };
-}
-function createAdminUsersVM(client, browse) {
-  const disposer = createDisposer();
-  disposer.add(browse);
-  const users$ = new BehaviorSubject([]);
-  const stats$ = new BehaviorSubject(null);
-  const usersLoading$ = new BehaviorSubject(true);
-  const statsLoading$ = new BehaviorSubject(true);
-  const fetchUsers = () => {
-    usersLoading$.next(true);
-    client.admin.users().then((data) => {
-      users$.next(data.users ?? []);
-      usersLoading$.next(false);
-    }).catch(() => usersLoading$.next(false));
-  };
-  const fetchStats = () => {
-    statsLoading$.next(true);
-    client.admin.userStats().then((data) => {
-      stats$.next(data.stats ?? null);
-      statsLoading$.next(false);
-    }).catch(() => statsLoading$.next(false));
-  };
-  fetchUsers();
-  fetchStats();
-  const updateUser = async (id, data) => {
-    await client.admin.updateUser(userDID(id), data);
-    fetchUsers();
-    fetchStats();
-  };
-  return {
-    browse,
-    users$: users$.asObservable(),
-    stats$: stats$.asObservable(),
-    usersLoading$: usersLoading$.asObservable(),
-    statsLoading$: statsLoading$.asObservable(),
-    updateUser,
-    dispose: () => {
-      users$.complete();
-      stats$.complete();
-      usersLoading$.complete();
-      statsLoading$.complete();
-      disposer.dispose();
-    }
-  };
-}
-function createAdminSecurityVM(client, browse) {
-  const disposer = createDisposer();
-  disposer.add(browse);
-  const providers$ = new BehaviorSubject([]);
-  const allowedDomains$ = new BehaviorSubject([]);
-  const isLoading$ = new BehaviorSubject(true);
-  client.admin.oauthConfig().then((data) => {
-    const config = data;
-    providers$.next(config.providers ?? []);
-    allowedDomains$.next(config.allowedDomains ?? []);
-    isLoading$.next(false);
-  }).catch(() => isLoading$.next(false));
-  return {
-    browse,
-    providers$: providers$.asObservable(),
-    allowedDomains$: allowedDomains$.asObservable(),
-    isLoading$: isLoading$.asObservable(),
-    dispose: () => {
-      providers$.complete();
-      allowedDomains$.complete();
-      isLoading$.complete();
-      disposer.dispose();
-    }
-  };
-}
-function createWelcomeVM(client) {
-  const disposer = createDisposer();
-  const userData$ = new BehaviorSubject(null);
-  const isProcessing$ = new BehaviorSubject(false);
-  client.auth.me().then((data) => userData$.next(data)).catch(() => {
-  });
-  const acceptTerms = async () => {
-    isProcessing$.next(true);
-    try {
-      await client.auth.acceptTerms();
-      userData$.next({ ...userData$.getValue(), termsAcceptedAt: (/* @__PURE__ */ new Date()).toISOString() });
-    } finally {
-      isProcessing$.next(false);
-    }
-  };
-  return {
-    userData$: userData$.asObservable(),
-    isProcessing$: isProcessing$.asObservable(),
-    acceptTerms,
-    dispose: () => {
-      userData$.complete();
-      isProcessing$.complete();
-      disposer.dispose();
-    }
-  };
-}
-function createResourceLoaderVM(client, resourceId) {
-  const raw$ = client.browse.resource(resourceId);
-  const resource$ = raw$;
-  const isLoading$ = raw$.pipe(map$1((r) => r === void 0));
-  return {
-    resource$,
-    isLoading$,
-    invalidate: () => client.browse.invalidateResourceDetail(resourceId),
-    dispose: () => {
-    }
-  };
-}
-function createSessionVM(client) {
-  const isLoggingOut$ = new BehaviorSubject(false);
-  const logout = async () => {
-    isLoggingOut$.next(true);
-    try {
-      await client.auth.logout();
-    } catch {
-    } finally {
-      isLoggingOut$.next(false);
-    }
-  };
-  return {
-    isLoggingOut$: isLoggingOut$.asObservable(),
-    logout,
-    dispose: () => {
-      isLoggingOut$.complete();
-    }
-  };
-}
-var SMELTER_CHANNELS = [
-  "yield:created",
-  "yield:updated",
-  "yield:representation-added",
-  "mark:archived",
-  "mark:added",
-  "mark:removed"
-];
-function createSmelterActorVM(options) {
-  const actor = createActorVM({
-    baseUrl: options.baseUrl,
-    token: options.token,
-    channels: [...SMELTER_CHANNELS],
-    reconnectMs: options.reconnectMs
-  });
-  const events$ = merge(
-    ...SMELTER_CHANNELS.map(
-      (channel) => actor.on$(channel).pipe(
-        map((payload) => ({
-          type: channel,
-          resourceId: payload.resourceId,
-          payload
-        }))
-      )
-    )
-  );
-  return {
-    events$,
-    state$: actor.state$,
-    emit: (channel, payload) => actor.emit(channel, payload),
-    start: () => actor.start(),
-    stop: () => actor.stop(),
-    dispose: () => actor.dispose()
-  };
-}
-function createJobClaimAdapter(options) {
-  const { actor, jobTypes } = options;
-  const activeJob$ = new BehaviorSubject(null);
-  const isProcessing$ = new BehaviorSubject(false);
-  const jobsCompleted$ = new BehaviorSubject(0);
-  const errors$ = new Subject();
-  let jobSubscription = null;
-  let started = false;
-  const claimJob = async (assignment) => {
-    try {
-      const correlationId = crypto.randomUUID();
-      const result$ = merge(
-        actor.on$("job:claimed").pipe(
-          filter$1((e) => e.correlationId === correlationId),
-          map$1((e) => ({ ok: true, response: e.response }))
-        ),
-        actor.on$("job:claim-failed").pipe(
-          filter$1((e) => e.correlationId === correlationId),
-          map$1(() => ({ ok: false }))
-        )
-      ).pipe(take$1(1), timeout$1(1e4));
-      const resultPromise = firstValueFrom(result$);
-      await actor.emit("job:claim", { correlationId, jobId: assignment.jobId });
-      const result = await resultPromise;
-      if (!result.ok) return null;
-      const job = result.response;
-      return {
-        jobId: assignment.jobId,
-        type: assignment.type,
-        resourceId: assignment.resourceId,
-        userId: job.metadata?.userId ?? "",
-        params: job.params ?? {}
-      };
-    } catch {
-      return null;
-    }
-  };
-  return {
-    activeJob$: activeJob$.asObservable(),
-    isProcessing$: isProcessing$.asObservable(),
-    jobsCompleted$: jobsCompleted$.asObservable(),
-    errors$: errors$.asObservable(),
-    start: () => {
-      if (started) return;
-      started = true;
-      actor.addChannels(["job:queued"]);
-      jobSubscription = actor.on$("job:queued").subscribe((event) => {
-        const jobType = event.jobType;
-        if (jobTypes.length > 0 && !jobTypes.includes(jobType)) return;
-        if (isProcessing$.getValue()) return;
-        isProcessing$.next(true);
-        claimJob({ jobId: event.jobId, type: jobType, resourceId: event.resourceId }).then((job) => {
-          if (job) {
-            activeJob$.next(job);
-          } else {
-            isProcessing$.next(false);
-          }
-        }).catch(() => {
-          isProcessing$.next(false);
-        });
-      });
-    },
-    stop: () => {
-      jobSubscription?.unsubscribe();
-      jobSubscription = null;
-      started = false;
-    },
-    completeJob: () => {
-      activeJob$.next(null);
-      isProcessing$.next(false);
-      jobsCompleted$.next(jobsCompleted$.getValue() + 1);
-    },
-    failJob: (jid, error) => {
-      activeJob$.next(null);
-      isProcessing$.next(false);
-      errors$.next({ jobId: jid, error });
-    },
-    dispose: () => {
-      jobSubscription?.unsubscribe();
-      jobSubscription = null;
-      started = false;
-      activeJob$.complete();
-      isProcessing$.complete();
-      jobsCompleted$.complete();
-      errors$.complete();
-    }
-  };
-}
-function createJobQueueVM(client) {
-  const jobs$ = new BehaviorSubject([]);
-  const jobCreated$ = new Subject();
-  const jobCompleted$ = new Subject();
-  const jobFailed$ = new Subject();
-  const pendingByType$ = jobs$.pipe(
-    map$1((all) => {
-      const counts = /* @__PURE__ */ new Map();
-      for (const j of all) {
-        if (j.status === "pending") {
-          counts.set(j.type, (counts.get(j.type) ?? 0) + 1);
-        }
-      }
-      return counts;
-    })
-  );
-  const runningJobs$ = jobs$.pipe(
-    map$1((all) => all.filter((j) => j.status === "running"))
-  );
-  const addOrUpdate = (job) => {
-    const current = jobs$.getValue();
-    const idx = current.findIndex((j) => j.jobId === job.jobId);
-    if (idx >= 0) {
-      const next = [...current];
-      next[idx] = job;
-      jobs$.next(next);
-    } else {
-      jobs$.next([...current, job]);
-    }
-  };
-  const subs = [
-    client.bus.get("job:queued").subscribe((event) => {
-      const job = {
-        jobId: event.jobId,
-        type: event.jobType,
-        status: "pending",
-        resourceId: event.resourceId,
-        userId: event.userId,
-        created: (/* @__PURE__ */ new Date()).toISOString()
-      };
-      addOrUpdate(job);
-      jobCreated$.next(job);
-    }),
-    client.bus.get("job:complete").subscribe((event) => {
-      if (!event._userId) {
-        throw new Error("job:complete missing _userId (gateway injection)");
-      }
-      const job = {
-        jobId: event.jobId,
-        type: event.jobType,
-        status: "complete",
-        resourceId: event.resourceId,
-        userId: event._userId,
-        created: "",
-        completedAt: (/* @__PURE__ */ new Date()).toISOString(),
-        result: event.result
-      };
-      addOrUpdate(job);
-      jobCompleted$.next(job);
-    }),
-    client.bus.get("job:fail").subscribe((event) => {
-      if (!event._userId) {
-        throw new Error("job:fail missing _userId (gateway injection)");
-      }
-      const job = {
-        jobId: event.jobId,
-        type: event.jobType,
-        status: "failed",
-        resourceId: event.resourceId,
-        userId: event._userId,
-        created: "",
-        completedAt: (/* @__PURE__ */ new Date()).toISOString(),
-        error: event.error
-      };
-      addOrUpdate(job);
-      jobFailed$.next(job);
-    })
-  ];
-  return {
-    jobs$: jobs$.asObservable(),
-    pendingByType$,
-    runningJobs$,
-    jobCreated$: jobCreated$.asObservable(),
-    jobCompleted$: jobCompleted$.asObservable(),
-    jobFailed$: jobFailed$.asObservable(),
-    dispose: () => {
-      subs.forEach((s) => s.unsubscribe());
-      jobs$.complete();
-      jobCreated$.complete();
-      jobCompleted$.complete();
-      jobFailed$.complete();
-    }
-  };
-}
-var WIZARD_CLOSED = {
-  open: false,
-  annotationId: null,
-  resourceId: null,
-  defaultTitle: "",
-  entityTypes: []
-};
-function createResourceViewerPageVM(client, resourceId, locale, browse, options) {
-  const disposer = createDisposer();
-  const beckon = createBeckonVM(client);
-  const mark = createMarkVM(client, resourceId);
-  const gather = createGatherVM(client, resourceId);
-  const matchVM = createMatchVM(client);
-  const yieldVM = createYieldVM(client, resourceId, locale);
-  disposer.add(beckon);
-  disposer.add(browse);
-  disposer.add(mark);
-  disposer.add(gather);
-  disposer.add(matchVM);
-  disposer.add(yieldVM);
-  const annotations$ = client.browse.annotations(resourceId).pipe(
-    map$1((a) => a ?? [])
-  );
-  const annotationGroups$ = annotations$.pipe(
-    map$1((anns) => {
-      const groups = { highlights: [], comments: [], assessments: [], references: [], tags: [] };
-      for (const ann of anns) {
-        if (isHighlight(ann)) groups.highlights.push(ann);
-        else if (isComment(ann)) groups.comments.push(ann);
-        else if (isAssessment(ann)) groups.assessments.push(ann);
-        else if (isReference(ann)) groups.references.push(ann);
-        else if (isTag(ann)) groups.tags.push(ann);
-      }
-      return groups;
-    })
-  );
-  const entityTypes$ = client.browse.entityTypes().pipe(
-    map$1((e) => e ?? [])
-  );
-  const events$ = client.browse.events(resourceId).pipe(
-    map$1((e) => e ?? [])
-  );
-  const referencedBy$ = client.browse.referencedBy(resourceId).pipe(
-    map$1((r) => r ?? [])
-  );
-  const content$ = new BehaviorSubject("");
-  const contentLoading$ = new BehaviorSubject(false);
-  const mediaToken$ = new BehaviorSubject(null);
-  const mediaType = options?.mediaType || "text/plain";
-  const isBinaryType = mediaType.startsWith("image/") || mediaType === "application/pdf";
-  if (!isBinaryType && mediaType) {
-    contentLoading$.next(true);
-    client.browse.resourceRepresentation(resourceId, { accept: mediaType }).then(({ data }) => {
-      content$.next(decodeWithCharset(data, mediaType));
-      contentLoading$.next(false);
-    }).catch(() => {
-      contentLoading$.next(false);
-    });
-  }
-  if (isBinaryType) {
-    client.auth.mediaToken(resourceId).then(({ token }) => mediaToken$.next(token)).catch(() => {
-    });
-  }
-  const wizard$ = new BehaviorSubject(WIZARD_CLOSED);
-  const unsubscribeResource = client.subscribeToResource(resourceId);
-  disposer.add(unsubscribeResource);
-  const bindInitiateSub = client.bus.get("bind:initiate").subscribe((event) => {
-    wizard$.next({
-      open: true,
-      annotationId: event.annotationId,
-      resourceId: event.resourceId,
-      defaultTitle: event.defaultTitle,
-      entityTypes: event.entityTypes
-    });
-    client.bus.get("gather:requested").next({
-      correlationId: crypto.randomUUID(),
-      annotationId: event.annotationId,
-      resourceId: event.resourceId,
-      options: { contextWindow: 2e3 }
-    });
-  });
-  disposer.add(() => bindInitiateSub.unsubscribe());
-  return {
-    beckon,
-    browse,
-    mark,
-    gather,
-    yield: yieldVM,
-    annotations$,
-    annotationGroups$,
-    entityTypes$,
-    events$,
-    referencedBy$,
-    content$: content$.asObservable(),
-    contentLoading$: contentLoading$.asObservable(),
-    mediaToken$: mediaToken$.asObservable(),
-    wizard$: wizard$.asObservable(),
-    closeWizard: () => wizard$.next(WIZARD_CLOSED),
-    dispose: () => {
-      wizard$.complete();
-      content$.complete();
-      contentLoading$.complete();
-      mediaToken$.complete();
-      disposer.dispose();
-    }
-  };
-}
-function createComposePageVM(client, browse, params, auth) {
-  const disposer = createDisposer();
-  disposer.add(browse);
-  const isReferenceMode = Boolean(params.annotationUri && params.sourceDocumentId && params.name);
-  const isCloneMode = params.mode === "clone" && Boolean(params.token);
-  const pageMode = isCloneMode ? "clone" : isReferenceMode ? "reference" : "new";
-  const mode$ = new BehaviorSubject(pageMode);
-  const loading$ = new BehaviorSubject(true);
-  const cloneData$ = new BehaviorSubject(null);
-  const referenceData$ = new BehaviorSubject(null);
-  const gatheredContext$ = new BehaviorSubject(null);
-  const entityTypes$ = client.browse.entityTypes().pipe(
-    map$1((e) => e ?? [])
-  );
-  if (isReferenceMode) {
-    const entityTypes = params.entityTypes ? params.entityTypes.split(",") : [];
-    referenceData$.next({
-      annotationUri: params.annotationUri,
-      sourceDocumentId: params.sourceDocumentId,
-      name: params.name,
-      entityTypes
-    });
-    if (params.storedContext) {
-      try {
-        gatheredContext$.next(JSON.parse(params.storedContext));
-      } catch {
-      }
-    }
-    loading$.next(false);
-  } else if (isCloneMode) {
-    void (async () => {
-      try {
-        const tokenResult = await client.yield.fromToken(params.token);
-        if (tokenResult && auth) {
-          const rId = resourceId(tokenResult["@id"]);
-          const mediaType = getPrimaryMediaType(tokenResult) || "text/plain";
-          const { data } = await client.browse.resourceRepresentation(rId, {
-            accept: mediaType
-          });
-          const content = decodeWithCharset(data, mediaType);
-          cloneData$.next({ sourceResource: tokenResult, sourceContent: content });
-        }
-      } catch {
-      }
-      loading$.next(false);
-    })();
-  } else {
-    loading$.next(false);
-  }
-  const save = async (saveParams) => {
-    if (saveParams.mode === "clone") {
-      const response2 = await client.yield.createFromToken({
-        token: params.token,
-        name: saveParams.name,
-        content: saveParams.content,
-        archiveOriginal: saveParams.archiveOriginal ?? true
-      });
-      return response2.resourceId;
-    }
-    let fileToUpload;
-    let mimeType;
-    if (saveParams.file) {
-      fileToUpload = saveParams.file;
-      mimeType = saveParams.format ?? "application/octet-stream";
-    } else {
-      const blob = new Blob([saveParams.content || ""], { type: saveParams.format ?? "application/octet-stream" });
-      const extension = saveParams.format === "text/plain" ? ".txt" : saveParams.format === "text/html" ? ".html" : ".md";
-      fileToUpload = new File([blob], saveParams.name + extension, { type: saveParams.format ?? "application/octet-stream" });
-      mimeType = saveParams.format ?? "application/octet-stream";
-    }
-    const format = saveParams.charset && !saveParams.file ? `${mimeType}; charset=${saveParams.charset}` : mimeType;
-    const response = await client.yield.resource({
-      name: saveParams.name,
-      file: fileToUpload,
-      format,
-      entityTypes: saveParams.entityTypes || [],
-      language: saveParams.language,
-      creationMethod: "ui",
-      storageUri: saveParams.storageUri
-    });
-    const newResourceId = response.resourceId;
-    if (saveParams.mode === "reference" && saveParams.annotationUri && saveParams.sourceDocumentId) {
-      await client.bind.body(
-        resourceId(saveParams.sourceDocumentId),
-        annotationId(saveParams.annotationUri),
-        [{ op: "add", item: { type: "SpecificResource", source: newResourceId, purpose: "linking" } }]
-      );
-    }
-    return newResourceId;
-  };
-  return {
-    browse,
-    mode$: mode$.asObservable(),
-    loading$: loading$.asObservable(),
-    cloneData$: cloneData$.asObservable(),
-    referenceData$: referenceData$.asObservable(),
-    gatheredContext$: gatheredContext$.asObservable(),
-    entityTypes$,
-    save,
-    dispose: () => {
-      mode$.complete();
-      loading$.complete();
-      cloneData$.complete();
-      referenceData$.complete();
-      gatheredContext$.complete();
-      disposer.dispose();
-    }
-  };
-}
 
-export { AdminNamespace, AuthNamespace, BeckonNamespace, BindNamespace, BrowseNamespace, BusRequestError, COMMON_PANELS, FrontendSessionSignals, GatherNamespace, HOVER_DELAY_MS, InMemorySessionStorage, JobNamespace, MarkNamespace, MatchNamespace, RESOURCE_PANELS, SemiontBrowser, SemiontClient, SemiontError, SemiontSession, YieldNamespace, 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, AuthNamespace, BeckonNamespace, BindNamespace, BrowseNamespace, BusRequestError, CacheObservable, FrameNamespace, GatherNamespace, HOVER_DELAY_MS, InMemorySessionStorage, JobNamespace, MarkNamespace, MatchNamespace, SemiontBrowser, SemiontClient, SemiontSession, SemiontSessionError, SessionSignals, StreamObservable, UploadObservable, YieldNamespace, busRequest, createBeckonStateUnit, createDisposer, createGatherStateUnit, createHoverHandlers, createHttpSessionFactory, createMarkStateUnit, createMatchStateUnit, createSearchPipeline, createYieldStateUnit, defaultProtocol, getBrowser, httpKb, isValidHostname, kbBackendUrl, setStoredSession };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map