@semiont/sdk 0.5.0 → 0.5.1

package/dist/index.js

@@ -1,13 +1,50 @@
-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 { SemiontError, annotationId, resourceId, email, googleCredential, refreshToken, EventBus, baseUrl, accessToken, isHighlight, isComment, isAssessment, isReference, isTag, decodeWithCharset, getPrimaryMediaType, userDID, searchQuery } from '@semiont/core';
+export { SemiontError, accessToken, annotationId, baseUrl, entityType, refreshToken, resourceId, userId } from '@semiont/core';
+import { Observable, lastValueFrom, firstValueFrom, merge, TimeoutError, throwError, BehaviorSubject, map as map$1, distinctUntilChanged, Subject, Subscription, of, filter as filter$1, take as take$1, timeout as timeout$1 } from 'rxjs';
+export { firstValueFrom, lastValueFrom } from 'rxjs';
+import { filter, map, take, timeout, catchError, 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';
 
 // 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 React-side 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 BusRequestError = class extends SemiontError {
+  constructor(message, code, details) {
+    super(message, code, details);
     this.name = "BusRequestError";
   }
 };
@@ -21,9 +58,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;
@@ -106,11 +165,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 +187,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 +218,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 +246,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 +278,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 +361,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 +373,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 +389,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 ──────────────────────────────────────────────
@@ -461,17 +507,18 @@ var MarkNamespace = class {
     this.transport = transport;
     this.bus = bus;
   }
-  async annotation(resourceId, input) {
-    return busRequest(
+  async annotation(resourceId2, input) {
+    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 delete(resourceId2, annotationId2) {
+    await this.transport.emit("mark:delete", { annotationId: annotationId2, resourceId: resourceId2 });
   }
   async entityType(type) {
     await this.transport.emit("mark:add-entity-type", { tag: type });
@@ -481,14 +528,14 @@ var MarkNamespace = class {
       await this.transport.emit("mark:add-entity-type", { tag });
     }
   }
-  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 +575,7 @@ var MarkNamespace = class {
                   data: {
                     jobId,
                     jobType: status.jobType ?? "annotation",
-                    resourceId,
+                    resourceId: resourceId2,
                     result: status.result
                   }
                 });
@@ -565,7 +612,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 +660,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",
@@ -640,7 +687,7 @@ var MarkNamespace = class {
     return busRequest(
       this.transport,
       "job:create",
-      { jobType, resourceId, params },
+      { jobType, resourceId: resourceId2, params },
       "job:created",
       "job:create-failed"
     );
@@ -653,11 +700,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 +717,8 @@ var GatherNamespace = class {
     this.transport = transport;
     this.bus = bus;
   }
-  annotation(annotationId, resourceId, options) {
-    return new Observable((subscriber) => {
+  annotation(annotationId2, resourceId2, options) {
+    return new StreamObservable((subscriber) => {
       const correlationId = crypto.randomUUID();
       const complete$ = this.bus.get("gather:complete").pipe(
         filter((e) => e.correlationId === correlationId)
@@ -681,7 +728,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 +745,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 +770,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 +788,7 @@ var MatchNamespace = class {
       });
       this.transport.emit("match:search-requested", {
         correlationId,
-        resourceId,
+        resourceId: resourceId2,
         referenceId,
         context,
         limit: options?.limit ?? 10,
@@ -779,8 +826,8 @@ var YieldNamespace = class {
     });
     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 +867,7 @@ var YieldNamespace = class {
                   data: {
                     jobId: jid,
                     jobType: status.jobType ?? "generation",
-                    resourceId,
+                    resourceId: resourceId2,
                     result: status.result
                   }
                 });
@@ -862,9 +909,9 @@ var YieldNamespace = class {
         "job:create",
         {
           jobType: "generation",
-          resourceId,
+          resourceId: resourceId2,
           params: {
-            referenceId: annotationId,
+            referenceId: annotationId2,
             title: options.title,
             prompt: options.prompt,
             language: options.language,
@@ -893,11 +940,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"
     );
@@ -932,14 +979,14 @@ var BeckonNamespace = class {
     this.transport = transport;
     this.bus = bus;
   }
-  attention(annotationId, resourceId) {
-    void this.transport.emit("beckon:focus", { annotationId, resourceId });
+  attention(annotationId2, resourceId2) {
+    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 });
   }
 };
 
@@ -1028,8 +1075,8 @@ var AuthNamespace = class {
   async mcpToken() {
     return this.transport.generateMcpToken();
   }
-  async mediaToken(resourceId) {
-    return this.transport.getMediaToken(resourceId);
+  async mediaToken(resourceId2) {
+    return this.transport.getMediaToken(resourceId2);
   }
 };
 
@@ -1045,8 +1092,8 @@ var AdminNamespace = class {
   async userStats() {
     return this.transport.getUserStats();
   }
-  async updateUser(userId, data) {
-    const result = await this.transport.updateUser(userId, data);
+  async updateUser(userId2, data) {
+    const result = await this.transport.updateUser(userId2, data);
     return result.user;
   }
   async oauthConfig() {
@@ -1071,7 +1118,7 @@ var AdminNamespace = class {
     return this.transport.importKnowledgeBase(file, onProgress);
   }
 };
-var SemiontClient = class {
+var SemiontClient = class _SemiontClient {
   /**
    * The wire-facing transport. Owns bus actor, HTTP, auth, admin, exchange,
    * system. Exposed for advanced consumers (workers, custom job adapters)
@@ -1134,13 +1181,74 @@ var SemiontClient = class {
   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(...)` instead — it 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);
+  }
+  /**
+   * Async factory for the credentials-first script case. Builds a
+   * transient 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.signIn(...)` — same credentials shape, plus the
+   * session machinery for proactive refresh and persistence.
+   *
+   * Throws if authentication fails. The transient client is disposed
+   * before the throw, so no resources leak on failure.
+   */
+  static async signIn(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);
+    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
@@ -1241,21 +1349,17 @@ function kbBackendUrl(kb) {
 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$;
@@ -1344,7 +1448,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 +1481,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,6 +1552,94 @@ 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);
+    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 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.
+   *
+   * Throws on auth failure with no resources leaked. On success, the
+   * returned session's `ready` promise has already resolved.
+   */
+  static async signIn(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);
+    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
@@ -1728,7 +1920,7 @@ var SemiontBrowser = class {
         await session.ready;
       } catch (err) {
         this.error$.next(
-          new SemiontError(
+          new SemiontSessionError(
             "session.construct-failed",
             err instanceof Error ? err.message : String(err),
             id
@@ -1995,20 +2187,20 @@ function createSearchPipeline(fetch, options = {}) {
 function createBeckonVM(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 +2217,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 = () => {
@@ -2095,7 +2287,7 @@ function createShellVM(browser, options) {
     }
   };
 }
-function createGatherVM(client, resourceId) {
+function createGatherVM(client, resourceId2) {
   const subs = [];
   const context$ = new BehaviorSubject(null);
   const loading$ = new BehaviorSubject(false);
@@ -2108,7 +2300,7 @@ function createGatherVM(client, resourceId) {
     annotationId$.next(annotationId(event.annotationId));
     const gatherSub = client.gather.annotation(
       annotationId(event.annotationId),
-      resourceId,
+      resourceId2,
       { contextWindow: event.options?.contextWindow ?? 2e3 }
     ).pipe(
       timeout(6e4)
@@ -2150,7 +2342,7 @@ function createMatchVM(client, _resourceId) {
   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 +2363,14 @@ function createMatchVM(client, _resourceId) {
     }
   };
 }
-function createYieldVM(client, resourceId$1, locale) {
+function createYieldVM(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 +2418,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 createMarkVM(client, resourceId2) {
   const subs = [];
   const pendingAnnotation$ = new BehaviorSubject(null);
   const assistingMotivation$ = new BehaviorSubject(null);
@@ -2250,9 +2442,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(resourceId2, {
         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 +2454,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 +2464,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) => {
@@ -2560,14 +2752,14 @@ function createWelcomeVM(client) {
     }
   };
 }
-function createResourceLoaderVM(client, resourceId) {
-  const raw$ = client.browse.resource(resourceId);
+function createResourceLoaderVM(client, resourceId2) {
+  const raw$ = client.browse.resource(resourceId2);
   const resource$ = raw$;
   const isLoading$ = raw$.pipe(map$1((r) => r === void 0));
   return {
     resource$,
     isLoading$,
-    invalidate: () => client.browse.invalidateResourceDetail(resourceId),
+    invalidate: () => client.browse.invalidateResourceDetail(resourceId2),
     dispose: () => {
     }
   };
@@ -2815,20 +3007,20 @@ var WIZARD_CLOSED = {
   defaultTitle: "",
   entityTypes: []
 };
-function createResourceViewerPageVM(client, resourceId, locale, browse, options) {
+function createResourceViewerPageVM(client, resourceId2, locale, browse, options) {
   const disposer = createDisposer();
   const beckon = createBeckonVM(client);
-  const mark = createMarkVM(client, resourceId);
-  const gather = createGatherVM(client, resourceId);
+  const mark = createMarkVM(client, resourceId2);
+  const gather = createGatherVM(client, resourceId2);
   const matchVM = createMatchVM(client);
-  const yieldVM = createYieldVM(client, resourceId, locale);
+  const yieldVM = createYieldVM(client, resourceId2, 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(
+  const annotations$ = client.browse.annotations(resourceId2).pipe(
     map$1((a) => a ?? [])
   );
   const annotationGroups$ = annotations$.pipe(
@@ -2847,10 +3039,10 @@ function createResourceViewerPageVM(client, resourceId, locale, browse, options)
   const entityTypes$ = client.browse.entityTypes().pipe(
     map$1((e) => e ?? [])
   );
-  const events$ = client.browse.events(resourceId).pipe(
+  const events$ = client.browse.events(resourceId2).pipe(
     map$1((e) => e ?? [])
   );
-  const referencedBy$ = client.browse.referencedBy(resourceId).pipe(
+  const referencedBy$ = client.browse.referencedBy(resourceId2).pipe(
     map$1((r) => r ?? [])
   );
   const content$ = new BehaviorSubject("");
@@ -2860,7 +3052,7 @@ function createResourceViewerPageVM(client, resourceId, locale, browse, options)
   const isBinaryType = mediaType.startsWith("image/") || mediaType === "application/pdf";
   if (!isBinaryType && mediaType) {
     contentLoading$.next(true);
-    client.browse.resourceRepresentation(resourceId, { accept: mediaType }).then(({ data }) => {
+    client.browse.resourceRepresentation(resourceId2, { accept: mediaType }).then(({ data }) => {
       content$.next(decodeWithCharset(data, mediaType));
       contentLoading$.next(false);
     }).catch(() => {
@@ -2868,11 +3060,11 @@ function createResourceViewerPageVM(client, resourceId, locale, browse, options)
     });
   }
   if (isBinaryType) {
-    client.auth.mediaToken(resourceId).then(({ token }) => mediaToken$.next(token)).catch(() => {
+    client.auth.mediaToken(resourceId2).then(({ token }) => mediaToken$.next(token)).catch(() => {
     });
   }
   const wizard$ = new BehaviorSubject(WIZARD_CLOSED);
-  const unsubscribeResource = client.subscribeToResource(resourceId);
+  const unsubscribeResource = client.subscribeToResource(resourceId2);
   disposer.add(unsubscribeResource);
   const bindInitiateSub = client.bus.get("bind:initiate").subscribe((event) => {
     wizard$.next({
@@ -3025,6 +3217,6 @@ function createComposePageVM(client, browse, params, auth) {
   };
 }
 
-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, COMMON_PANELS, CacheObservable, FrontendSessionSignals, GatherNamespace, HOVER_DELAY_MS, InMemorySessionStorage, JobNamespace, MarkNamespace, MatchNamespace, RESOURCE_PANELS, SemiontBrowser, SemiontClient, SemiontSession, SemiontSessionError, StreamObservable, 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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map