@semiont/api-client 0.4.20 → 0.4.21

package/dist/index.js

@@ -1,448 +1,522 @@
 import ky, { HTTPError } from 'ky';
-import { BehaviorSubject, Observable, merge } from 'rxjs';
-import { map, distinctUntilChanged, filter, takeUntil } from 'rxjs/operators';
-import { annotationId, resourceId, searchQuery, email, googleCredential, refreshToken } from '@semiont/core';
+import { RESOURCE_BROADCAST_TYPES, PERSISTED_EVENT_TYPES, annotationId, resourceId, email, googleCredential, refreshToken, EventBus, accessToken, baseUrl, userDID, searchQuery } from '@semiont/core';
 export { getFragmentSelector, getSvgSelector, getTextPositionSelector, validateSvgMarkup } from '@semiont/core';
+import { Subject, BehaviorSubject, merge, firstValueFrom, map as map$1, distinctUntilChanged, Observable, Subscription, of, filter as filter$1, take as take$1, timeout as timeout$1 } from 'rxjs';
+import { share, filter, map, take, timeout, takeUntil, startWith, debounceTime, distinctUntilChanged as distinctUntilChanged$1, switchMap } from 'rxjs/operators';
 
 // src/client.ts
-
-// src/sse/stream.ts
-function createSSEStream(url, fetchOptions, config, logger) {
-  let abortController = new AbortController();
-  let closed = false;
+function busLog(direction, channel, payload, scope) {
+  if (typeof globalThis === "undefined") return;
+  const g = globalThis;
+  if (!g.__SEMIONT_BUS_LOG__) return;
+  const cid = payload?.correlationId;
+  const tag = `[bus ${direction}] ${channel}` + (scope ? ` scope=${scope}` : "") + (cid ? ` cid=${String(cid).slice(0, 8)}` : "");
+  console.debug(tag, payload);
+}
+var DEGRADED_THRESHOLD_MS = 3e3;
+var ALLOWED_TRANSITIONS = {
+  initial: ["connecting", "closed"],
+  connecting: ["open", "reconnecting", "closed"],
+  open: ["reconnecting", "closed"],
+  reconnecting: ["connecting", "degraded", "closed"],
+  degraded: ["connecting", "closed"],
+  closed: []
+};
+function createActorVM(options) {
+  const { baseUrl: baseUrl3, token: tokenOrGetter, channels: initialChannels, scope: initialScope, reconnectMs = 5e3 } = options;
+  const getToken = typeof tokenOrGetter === "function" ? tokenOrGetter : () => tokenOrGetter;
+  const g = globalThis;
+  g.__SEMIONT_ACTOR_INSTANCES__ = (g.__SEMIONT_ACTOR_INSTANCES__ ?? 0) + 1;
+  const actorSerial = g.__SEMIONT_ACTOR_INSTANCES__;
+  console.debug(`[diag] ActorVM #${actorSerial} constructed (baseUrl=${baseUrl3})`);
+  const globalChannels = new Set(initialChannels);
+  const scopedChannels = /* @__PURE__ */ new Set();
+  let activeScope = initialScope;
+  const events$ = new Subject();
+  const state$ = new BehaviorSubject("initial");
+  let currentState = "initial";
+  let degradedTimer = null;
+  const transition = (next) => {
+    if (currentState === next) return;
+    const allowed = ALLOWED_TRANSITIONS[currentState];
+    if (!allowed.includes(next)) {
+      throw new Error(`Invalid connection state transition: ${currentState} \u2192 ${next}`);
+    }
+    const prev = currentState;
+    currentState = next;
+    if (next === "reconnecting" && prev !== "reconnecting") {
+      if (degradedTimer) clearTimeout(degradedTimer);
+      degradedTimer = setTimeout(() => {
+        if (currentState === "reconnecting") transition("degraded");
+      }, DEGRADED_THRESHOLD_MS);
+    }
+    if (prev === "reconnecting" && next !== "reconnecting") {
+      if (degradedTimer) {
+        clearTimeout(degradedTimer);
+        degradedTimer = null;
+      }
+    }
+    state$.next(next);
+  };
+  let running = false;
+  const inflightControllers = /* @__PURE__ */ new Set();
+  let reconnectTimer = null;
   let lastEventId = null;
-  const RECONNECT_INITIAL_MS = 1e3;
-  const RECONNECT_MAX_MS = 3e4;
-  let reconnectDelayMs = RECONNECT_INITIAL_MS;
+  const shared$ = events$.pipe(share());
+  const disconnect = () => {
+    for (const c of inflightControllers) {
+      try {
+        c.abort();
+      } catch {
+      }
+    }
+    inflightControllers.clear();
+    if (reconnectTimer) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+  };
   const connect = async () => {
-    try {
-      logger?.debug("SSE Stream Request", {
-        type: "sse_request",
-        url,
-        method: fetchOptions.method || "GET",
-        timestamp: Date.now()
-      });
-      const headers = {
-        ...fetchOptions.headers,
-        "Accept": "text/event-stream"
-      };
-      if (lastEventId !== null) {
-        headers["Last-Event-ID"] = lastEventId;
+    transition("connecting");
+    for (const c of inflightControllers) {
+      try {
+        c.abort();
+      } catch {
       }
-      const response = await fetch(url, {
-        ...fetchOptions,
-        signal: abortController.signal,
-        headers
-      });
-      if (!response.ok) {
-        const errorData = await response.json().catch(() => ({}));
-        const error = new Error(errorData.message || `HTTP ${response.status}: ${response.statusText}`);
-        logger?.error("SSE Stream Error", {
-          type: "sse_error",
-          url,
-          error: error.message,
-          status: response.status,
-          phase: "connect"
-        });
-        throw error;
+    }
+    inflightControllers.clear();
+    const params = new URLSearchParams();
+    for (const ch of globalChannels) {
+      params.append("channel", ch);
+    }
+    if (activeScope && scopedChannels.size > 0) {
+      params.append("scope", activeScope);
+      for (const ch of scopedChannels) {
+        params.append("scoped", ch);
       }
-      if (!response.body) {
-        const error = new Error("Response body is null - server did not return a stream");
-        logger?.error("SSE Stream Error", {
-          type: "sse_error",
-          url,
-          error: error.message,
-          phase: "connect"
-        });
-        throw error;
+    }
+    const url = `${baseUrl3}/bus/subscribe?${params.toString()}`;
+    const controller = new AbortController();
+    inflightControllers.add(controller);
+    try {
+      const headers = { Authorization: `Bearer ${getToken()}` };
+      if (lastEventId) headers["Last-Event-ID"] = lastEventId;
+      const response = await fetch(url, { headers, signal: controller.signal });
+      if (!response.ok || !response.body) {
+        throw new Error(`SSE connect failed: ${response.status}`);
       }
-      logger?.info("SSE Stream Connected", {
-        type: "sse_connected",
-        url,
-        status: response.status,
-        contentType: response.headers.get("content-type") || "unknown"
-      });
+      transition("open");
       const reader = response.body.getReader();
       const decoder = new TextDecoder();
       let buffer = "";
-      let eventType = "";
-      let eventData = "";
-      let eventId = "";
-      while (true) {
+      let currentEvent = "";
+      let currentData = "";
+      let currentId;
+      while (running && inflightControllers.has(controller)) {
         const { done, value } = await reader.read();
-        if (done || closed) break;
-        const chunk = decoder.decode(value, { stream: true });
-        buffer += chunk;
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
         const lines = buffer.split("\n");
-        buffer = lines.pop() || "";
+        buffer = lines.pop() ?? "";
         for (const line of lines) {
-          if (line.startsWith("event:")) {
-            eventType = line.slice(6).trim();
-          } else if (line.startsWith("data:")) {
-            eventData = line.slice(5).trim();
-          } else if (line.startsWith("id:")) {
-            eventId = line.slice(3).trim();
+          if (line.startsWith("event: ")) {
+            currentEvent = line.slice(7);
+          } else if (line.startsWith("data: ")) {
+            currentData = line.slice(6);
+          } else if (line.startsWith("id: ")) {
+            currentId = line.slice(4);
           } else if (line === "") {
-            if (eventData && !closed) {
-              handleEvent(eventType, eventData, eventId);
-              if (closed) break;
-              eventType = "";
-              eventData = "";
-              eventId = "";
+            if (currentEvent === "bus-event" && currentData) {
+              if (currentId !== void 0) lastEventId = currentId;
+              const parsed = JSON.parse(currentData);
+              busLog("RECV", parsed.channel, parsed.payload, parsed.scope);
+              events$.next(parsed);
             }
+            currentEvent = "";
+            currentData = "";
+            currentId = void 0;
           }
         }
-        if (closed) break;
-      }
-      logger?.info("SSE Stream Closed", {
-        type: "sse_closed",
-        url,
-        reason: "complete"
-      });
-    } catch (error) {
-      if (error instanceof Error && error.name !== "AbortError") {
-        logger?.error("SSE Stream Error", {
-          type: "sse_error",
-          url,
-          error: error.message,
-          phase: "stream"
-        });
-      } else if (error instanceof Error && error.name === "AbortError") {
-        logger?.info("SSE Stream Closed", {
-          type: "sse_closed",
-          url,
-          reason: "abort"
-        });
       }
+    } catch (err) {
+      if (err.name === "AbortError") return;
+    } finally {
+      inflightControllers.delete(controller);
     }
-  };
-  const handleEvent = (eventType, data, id) => {
-    if (data.startsWith(":")) {
-      return;
+    if (running) {
+      transition("reconnecting");
+      reconnectTimer = setTimeout(() => {
+        if (running) connect();
+      }, reconnectMs);
     }
-    if (id) {
-      lastEventId = id;
+  };
+  const reconnect = () => {
+    if (!running) return;
+    if (currentState === "open" || currentState === "connecting" || currentState === "degraded") {
+      transition("reconnecting");
     }
-    try {
-      const parsed = JSON.parse(data);
-      logger?.debug("SSE Event Received", {
-        type: "sse_event",
-        url,
-        event: eventType || "message",
-        hasData: !!data
+    disconnect();
+    connect();
+  };
+  let reconnectTimer2 = null;
+  const RECONNECT_DEBOUNCE_MS = 100;
+  const scheduleReconnect = () => {
+    if (reconnectTimer2) clearTimeout(reconnectTimer2);
+    reconnectTimer2 = setTimeout(() => {
+      reconnectTimer2 = null;
+      reconnect();
+    }, RECONNECT_DEBOUNCE_MS);
+  };
+  return {
+    on$(channel) {
+      return shared$.pipe(
+        filter((e) => e.channel === channel),
+        map((e) => e.payload)
+      );
+    },
+    emit: async (channel, payload, emitScope) => {
+      busLog("EMIT", channel, payload, emitScope);
+      const body = { channel, payload };
+      if (emitScope) body.scope = emitScope;
+      await fetch(`${baseUrl3}/bus/emit`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${getToken()}`
+        },
+        body: JSON.stringify(body)
       });
-      if (typeof parsed === "object" && parsed !== null && "metadata" in parsed) {
-        config.eventBus.get(eventType).next(parsed);
-        return;
+    },
+    state$: state$.asObservable(),
+    addChannels: (channels, scope) => {
+      let changed = false;
+      if (scope !== void 0) {
+        for (const ch of channels) {
+          if (!scopedChannels.has(ch)) {
+            scopedChannels.add(ch);
+            changed = true;
+          }
+        }
+        if (scope !== activeScope) {
+          activeScope = scope;
+          changed = true;
+        }
+      } else {
+        for (const ch of channels) {
+          if (!globalChannels.has(ch)) {
+            globalChannels.add(ch);
+            changed = true;
+          }
+        }
       }
-      config.eventBus.get(eventType).next(parsed);
-      if (config.completeEvent && eventType === config.completeEvent) {
-        closed = true;
-        abortController.abort();
-      } else if (config.errorEvent && eventType === config.errorEvent) {
-        closed = true;
-        abortController.abort();
+      if (changed) scheduleReconnect();
+    },
+    removeChannels: (channels) => {
+      let changed = false;
+      for (const ch of channels) {
+        if (scopedChannels.delete(ch)) changed = true;
+        if (globalChannels.delete(ch)) changed = true;
       }
-    } catch (error) {
-      logger?.error("SSE Failed to parse event data", { error, eventType, data });
+      if (scopedChannels.size === 0) activeScope = void 0;
+      if (changed) scheduleReconnect();
+    },
+    start: () => {
+      if (running) return;
+      running = true;
+      connect();
+    },
+    stop: () => {
+      running = false;
+      if (currentState !== "closed") transition("closed");
+      if (reconnectTimer2) {
+        clearTimeout(reconnectTimer2);
+        reconnectTimer2 = null;
+      }
+      if (degradedTimer) {
+        clearTimeout(degradedTimer);
+        degradedTimer = null;
+      }
+      disconnect();
+    },
+    dispose: () => {
+      running = false;
+      if (currentState !== "closed") transition("closed");
+      if (reconnectTimer2) {
+        clearTimeout(reconnectTimer2);
+        reconnectTimer2 = null;
+      }
+      if (degradedTimer) {
+        clearTimeout(degradedTimer);
+        degradedTimer = null;
+      }
+      disconnect();
+      events$.complete();
+      state$.complete();
     }
   };
-  const runConnect = async () => {
-    if (!config.reconnect) {
-      return connect();
-    }
-    while (!closed) {
-      abortController = new AbortController();
-      try {
-        await connect();
-        if (closed) return;
-        logger?.info("SSE Stream ended cleanly; reconnecting", { url });
-      } catch (error) {
-        if (closed) return;
-        if (error instanceof Error && error.name === "AbortError") return;
-        logger?.warn("SSE Stream errored; reconnecting", {
-          url,
-          error: error instanceof Error ? error.message : String(error),
-          delayMs: reconnectDelayMs
-        });
-      }
-      await new Promise((resolve) => setTimeout(resolve, reconnectDelayMs));
-      reconnectDelayMs = Math.min(reconnectDelayMs * 2, RECONNECT_MAX_MS);
+}
+var BusRequestError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BusRequestError";
+  }
+};
+async function busRequest(actor, emitChannel, payload, resultChannel, failureChannel, timeoutMs = 3e4) {
+  const correlationId = crypto.randomUUID();
+  const fullPayload = { ...payload, correlationId };
+  const result$ = merge(
+    actor.on$(resultChannel).pipe(
+      filter((e) => e.correlationId === correlationId),
+      map((e) => ({ ok: true, response: e.response }))
+    ),
+    actor.on$(failureChannel).pipe(
+      filter((e) => e.correlationId === correlationId),
+      map((e) => ({ ok: false, error: new BusRequestError(e.message) }))
+    )
+  ).pipe(take(1), timeout(timeoutMs));
+  const resultPromise = firstValueFrom(result$);
+  await actor.emit(emitChannel, fullPayload);
+  const result = await resultPromise;
+  if (!result.ok) {
+    throw result.error;
+  }
+  return result.response;
+}
+function createCache(fetchFn) {
+  const store$ = new BehaviorSubject(/* @__PURE__ */ new Map());
+  const inflight = /* @__PURE__ */ new Set();
+  const obsCache = /* @__PURE__ */ new Map();
+  const doFetch = async (key) => {
+    if (inflight.has(key)) return;
+    inflight.add(key);
+    try {
+      const value = await fetchFn(key);
+      const next = new Map(store$.value);
+      next.set(key, value);
+      store$.next(next);
+    } catch {
+    } finally {
+      inflight.delete(key);
     }
   };
-  void runConnect();
   return {
-    close() {
-      closed = true;
-      abortController.abort();
+    observe(key) {
+      if (!store$.value.has(key) && !inflight.has(key)) {
+        void doFetch(key);
+      }
+      let obs = obsCache.get(key);
+      if (!obs) {
+        obs = store$.pipe(
+          map$1((m) => m.get(key)),
+          distinctUntilChanged()
+        );
+        obsCache.set(key, obs);
+      }
+      return obs;
+    },
+    get(key) {
+      return store$.value.get(key);
+    },
+    keys() {
+      return [...store$.value.keys()];
+    },
+    invalidate(key) {
+      inflight.delete(key);
+      void doFetch(key);
+    },
+    remove(key) {
+      const next = new Map(store$.value);
+      next.delete(key);
+      store$.next(next);
+      inflight.delete(key);
+    },
+    set(key, value) {
+      const next = new Map(store$.value);
+      next.set(key, value);
+      store$.next(next);
+    },
+    invalidateAll() {
+      for (const key of store$.value.keys()) {
+        inflight.delete(key);
+        void doFetch(key);
+      }
+    },
+    dispose() {
+      store$.complete();
+      obsCache.clear();
+      inflight.clear();
     }
   };
 }
 
-// src/sse/index.ts
-var SSE_STREAM_CONNECTED = "stream-connected";
-var SSEClient = class {
-  baseUrl;
-  logger;
-  constructor(config) {
-    this.baseUrl = config.baseUrl.endsWith("/") ? config.baseUrl.slice(0, -1) : config.baseUrl;
-    this.logger = config.logger;
-  }
-  /**
-   * Get common headers for SSE requests
-   */
-  getHeaders(auth) {
-    const headers = {
-      "Content-Type": "application/json"
-    };
-    if (auth) {
-      headers["Authorization"] = `Bearer ${auth}`;
-    }
-    return headers;
-  }
-  /**
-   * Subscribe to resource events (long-lived stream)
-   *
-   * Opens a long-lived SSE connection to receive real-time events for a resource.
-   * Used for collaborative editing - see events from other users as they happen.
-   *
-   * This stream does NOT have a complete event - it stays open until explicitly closed.
-   *
-   * @param resourceId - Resource URI or ID to subscribe to
-   * @param options - Request options (auth token)
-   * @returns SSE stream controller with event callback
-   *
-   * @example
-   * ```typescript
-   * const stream = sseClient.resourceEvents(
-   *   'http://localhost:4000/resources/doc-123',
-   *   { auth: 'your-token' }
-   * );
-   *
-   * stream.onProgress((event) => {
-   *   console.log(`Event: ${event.type}`);
-   *   console.log(`User: ${event.userId}`);
-   *   console.log(`Sequence: ${event.metadata.sequenceNumber}`);
-   *   console.log(`Payload:`, event.payload);
-   * });
-   *
-   * stream.onError((error) => {
-   *   console.error('Stream error:', error.message);
-   * });
-   *
-   * // Close when no longer needed (e.g., component unmount)
-   * stream.close();
-   * ```
-   */
-  resourceEvents(resourceId, options) {
-    const url = `${this.baseUrl}/resources/${resourceId}/events/stream`;
-    const stream = createSSEStream(
-      url,
-      {
-        method: "GET",
-        headers: this.getHeaders(options.auth)
-      },
-      {
-        progressEvents: ["*"],
-        // Accept all event types (long-lived stream)
-        completeEvent: null,
-        // Never completes (long-lived)
-        errorEvent: null,
-        // No error event (errors throw)
-        eventBus: options.eventBus,
-        reconnect: true
-      },
-      this.logger
-    );
-    if (options.onConnected) {
-      const sub = options.eventBus.get(SSE_STREAM_CONNECTED).subscribe(() => {
-        options.onConnected();
-        sub.unsubscribe();
-      });
-    }
-    return stream;
-  }
-  /**
-   * Subscribe to global system events (long-lived stream)
-   *
-   * Opens a long-lived SSE connection to receive system-level domain events
-   * (entity type additions, etc.) that are not scoped to a specific resource.
-   *
-   * @param options - Request options (auth token, eventBus)
-   * @returns SSE stream controller
-   *
-   * @example
-   * ```typescript
-   * const stream = sseClient.globalEvents({ auth: 'your-token', eventBus });
-   *
-   * // Events auto-emit to EventBus typed channels — subscribe there
-   * eventBus.get('mark:entity-type-added').subscribe((stored) => {
-   *   // Invalidate entity types query
-   * });
-   *
-   * // Close when no longer needed
-   * stream.close();
-   * ```
-   */
-  globalEvents(options) {
-    const url = `${this.baseUrl}/api/events/stream`;
-    const stream = createSSEStream(
-      url,
-      {
-        method: "GET",
-        headers: this.getHeaders(options.auth)
-      },
-      {
-        progressEvents: ["*"],
-        completeEvent: null,
-        errorEvent: null,
-        eventBus: options.eventBus,
-        reconnect: true
-      },
-      this.logger
-    );
-    if (options.onConnected) {
-      const sub = options.eventBus.get(SSE_STREAM_CONNECTED).subscribe(() => {
-        options.onConnected();
-        sub.unsubscribe();
-      });
-    }
-    return stream;
-  }
-  /**
-   * Subscribe to participant attention stream (long-lived stream)
-   *
-   * Opens a participant-scoped SSE connection to receive cross-participant
-   * beckon signals. Signals are delivered as 'beckon:focus' events routed
-   * to the EventBus — the existing scroll/highlight machinery handles them.
-   *
-   * Signals are ephemeral — delivered if connected, dropped if not.
-   *
-   * @param options - Request options (auth token, eventBus)
-   * @returns SSE stream controller
-   */
-  attentionStream(options) {
-    const url = `${this.baseUrl}/api/participants/me/attention-stream`;
-    const stream = createSSEStream(
-      url,
-      {
-        method: "GET",
-        headers: this.getHeaders(options.auth)
-      },
-      {
-        progressEvents: ["*"],
-        completeEvent: null,
-        errorEvent: null,
-        eventBus: options.eventBus,
-        reconnect: true
-      },
-      this.logger
-    );
-    if (options.onConnected) {
-      const sub = options.eventBus.get(SSE_STREAM_CONNECTED).subscribe(() => {
-        options.onConnected();
-        sub.unsubscribe();
-      });
-    }
-    return stream;
-  }
-};
+// src/namespaces/browse.ts
+var ENTITY_TYPES_KEY = "_";
 var BrowseNamespace = class {
-  constructor(http, eventBus, getToken) {
+  constructor(http, eventBus, getToken, actor) {
     this.http = http;
     this.eventBus = eventBus;
     this.getToken = getToken;
+    this.actor = actor;
+    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.actor,
+        "browse:resource-requested",
+        { resourceId: id },
+        "browse:resource-result",
+        "browse:resource-failed"
+      );
+      return result.resource;
+    });
+    this.resourceListCache = createCache(async (key) => {
+      const filters = this.resourceListFilters.get(key) ?? {};
+      const search = filters.search ? searchQuery(filters.search) : void 0;
+      const result = await busRequest(
+        this.actor,
+        "browse:resources-requested",
+        { search, archived: filters.archived, limit: filters.limit ?? 100, offset: 0 },
+        "browse:resources-result",
+        "browse:resources-failed"
+      );
+      return result.resources;
+    });
+    this.annotationListCache = createCache(async (resourceId) => {
+      return busRequest(
+        this.actor,
+        "browse:annotations-requested",
+        { resourceId },
+        "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`);
+      }
+      const result = await busRequest(
+        this.actor,
+        "browse:annotation-requested",
+        { resourceId, annotationId },
+        "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.actor,
+        "browse:entity-types-requested",
+        {},
+        "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) => {
+      const result = await busRequest(
+        this.actor,
+        "browse:referenced-by-requested",
+        { resourceId },
+        "browse:referenced-by-result",
+        "browse:referenced-by-failed"
+      );
+      return result.referencedBy;
+    });
+    this.resourceEventsCache = createCache(async (resourceId) => {
+      const result = await busRequest(
+        this.actor,
+        "browse:events-requested",
+        { resourceId },
+        "browse:events-result",
+        "browse:events-failed"
+      );
+      return result.events;
+    });
     this.subscribeToEvents();
   }
-  // ── Annotation list cache ───────────────────────────────────────────────
-  annotationList$ = new BehaviorSubject(/* @__PURE__ */ new Map());
-  fetchingAnnotationList = /* @__PURE__ */ new Set();
-  annotationListObs$ = /* @__PURE__ */ new Map();
-  // ── Annotation detail cache ─────────────────────────────────────────────
-  annotationDetail$ = new BehaviorSubject(/* @__PURE__ */ new Map());
-  fetchingAnnotationDetail = /* @__PURE__ */ new Set();
-  annotationDetailObs$ = /* @__PURE__ */ new Map();
-  // ── Resource detail cache ───────────────────────────────────────────────
-  resourceDetail$ = new BehaviorSubject(/* @__PURE__ */ new Map());
-  fetchingResourceDetail = /* @__PURE__ */ new Set();
-  resourceDetailObs$ = /* @__PURE__ */ new Map();
-  // ── Resource list cache ─────────────────────────────────────────────────
-  resourceList$ = new BehaviorSubject(/* @__PURE__ */ new Map());
-  fetchingResourceList = /* @__PURE__ */ new Set();
-  resourceListObs$ = /* @__PURE__ */ new Map();
-  // ── Entity types cache ──────────────────────────────────────────────────
-  entityTypes$ = new BehaviorSubject(void 0);
-  fetchingEntityTypes = false;
-  // ── Referenced-by cache ─────────────────────────────────────────────────
-  referencedBy$ = new BehaviorSubject(/* @__PURE__ */ new Map());
-  fetchingReferencedBy = /* @__PURE__ */ new Set();
-  referencedByObs$ = /* @__PURE__ */ new Map();
+  // ── Caches, backed by the RxJS-native `Cache<K, V>` primitive ───────────
+  //
+  // 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`.
+  //
+  // Public surface (`resource()`, `annotations()`, etc.) is unchanged;
+  // the caches are an implementation detail of this namespace.
+  resourceCache;
+  resourceListCache;
+  annotationListCache;
+  /**
+   * Annotation-detail cache keyed by `annotationId` only — the resourceId
+   * is a routing hint for the backend fetch, not an identity component.
+   * We track the most recent resourceId per annotationId in a side-map
+   * so `mark:delete-ok` (which carries only `annotationId`) can reach
+   * the right cache entry. Aligns with the pre-refactor semantics.
+   */
+  annotationDetailCache;
+  annotationResources = /* @__PURE__ */ new Map();
+  entityTypesCache;
+  referencedByCache;
+  resourceEventsCache;
+  /** Filter-blob memory so `invalidateResourceLists` can replay per-key. */
+  resourceListFilters = /* @__PURE__ */ new Map();
+  /**
+   * Per-key memo for `annotations()` observables. The cache stores the
+   * full `AnnotationsListResponse`; the public shape is just the inner
+   * `Annotation[]`. Without this memo, every call to `annotations(rId)`
+   * would produce a fresh `.pipe(map(...))` observable, violating B4
+   * (per-key observable stability). Consumers that compare observable
+   * identity — React hooks depending on the observable reference,
+   * `distinctUntilChanged` at a higher level — would misbehave.
+   */
+  annotationListObs = /* @__PURE__ */ new Map();
   getToken;
+  actor;
   // ── Live queries ────────────────────────────────────────────────────────
   resource(resourceId) {
-    if (!this.resourceDetail$.value.has(resourceId) && !this.fetchingResourceDetail.has(resourceId)) {
-      this.fetchResourceDetail(resourceId);
-    }
-    let obs = this.resourceDetailObs$.get(resourceId);
-    if (!obs) {
-      obs = this.resourceDetail$.pipe(map((m) => m.get(resourceId)), distinctUntilChanged());
-      this.resourceDetailObs$.set(resourceId, obs);
-    }
-    return obs;
+    return this.resourceCache.observe(resourceId);
   }
   resources(filters) {
     const key = JSON.stringify(filters ?? {});
-    if (!this.resourceList$.value.has(key) && !this.fetchingResourceList.has(key)) {
-      this.fetchResourceList(key, filters);
-    }
-    let obs = this.resourceListObs$.get(key);
-    if (!obs) {
-      obs = this.resourceList$.pipe(map((m) => m.get(key)), distinctUntilChanged());
-      this.resourceListObs$.set(key, obs);
-    }
-    return obs;
+    this.resourceListFilters.set(key, filters ?? {});
+    return this.resourceListCache.observe(key);
   }
   annotations(resourceId) {
-    if (!this.annotationList$.value.has(resourceId) && !this.fetchingAnnotationList.has(resourceId)) {
-      this.fetchAnnotationList(resourceId);
-    }
-    let obs = this.annotationListObs$.get(resourceId);
+    let obs = this.annotationListObs.get(resourceId);
     if (!obs) {
-      obs = this.annotationList$.pipe(
-        map((m) => m.get(resourceId)?.annotations),
-        distinctUntilChanged()
-      );
-      this.annotationListObs$.set(resourceId, obs);
+      obs = this.annotationListCache.observe(resourceId).pipe(map$1((r) => r?.annotations));
+      this.annotationListObs.set(resourceId, obs);
     }
     return obs;
   }
   annotation(resourceId, annotationId) {
-    if (!this.annotationDetail$.value.has(annotationId) && !this.fetchingAnnotationDetail.has(annotationId)) {
-      this.fetchAnnotationDetail(resourceId, annotationId);
-    }
-    let obs = this.annotationDetailObs$.get(annotationId);
-    if (!obs) {
-      obs = this.annotationDetail$.pipe(map((m) => m.get(annotationId)), distinctUntilChanged());
-      this.annotationDetailObs$.set(annotationId, obs);
-    }
-    return obs;
+    this.annotationResources.set(annotationId, resourceId);
+    return this.annotationDetailCache.observe(annotationId);
   }
   entityTypes() {
-    if (this.entityTypes$.value === void 0 && !this.fetchingEntityTypes) {
-      this.fetchEntityTypes();
+    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 this.entityTypes$.asObservable();
+    return self.__entityTypesDiag__;
   }
   referencedBy(resourceId) {
-    if (!this.referencedBy$.value.has(resourceId) && !this.fetchingReferencedBy.has(resourceId)) {
-      this.fetchReferencedBy(resourceId);
-    }
-    let obs = this.referencedByObs$.get(resourceId);
-    if (!obs) {
-      obs = this.referencedBy$.pipe(map((m) => m.get(resourceId)), distinctUntilChanged());
-      this.referencedByObs$.set(resourceId, obs);
-    }
-    return obs;
+    return this.referencedByCache.observe(resourceId);
+  }
+  events(resourceId) {
+    return this.resourceEventsCache.observe(resourceId);
   }
   // ── One-shot reads ──────────────────────────────────────────────────────
   async resourceContent(resourceId) {
@@ -466,11 +540,23 @@ var BrowseNamespace = class {
     });
   }
   async resourceEvents(resourceId) {
-    const result = await this.http.getResourceEvents(resourceId, { auth: this.getToken() });
+    const result = await busRequest(
+      this.actor,
+      "browse:events-requested",
+      { resourceId },
+      "browse:events-result",
+      "browse:events-failed"
+    );
     return result.events;
   }
   async annotationHistory(resourceId, annotationId) {
-    return this.http.getAnnotationHistory(resourceId, annotationId, { auth: this.getToken() });
+    return busRequest(
+      this.actor,
+      "browse:annotation-history-requested",
+      { resourceId, annotationId },
+      "browse:annotation-history-result",
+      "browse:annotation-history-failed"
+    );
   }
   async connections(_resourceId) {
     throw new Error("Not implemented: connections endpoint does not exist yet");
@@ -482,302 +568,326 @@ var BrowseNamespace = class {
     throw new Error("Not implemented: resourcesByName endpoint does not exist yet");
   }
   async files(dirPath, sort) {
-    return this.http.browseFiles(dirPath, sort, { auth: this.getToken() });
+    return busRequest(
+      this.actor,
+      "browse:directory-requested",
+      { path: dirPath ?? ".", sort: sort ?? "name" },
+      "browse:directory-result",
+      "browse:directory-failed"
+    );
   }
-  // ── Invalidation (exposed for other namespaces) ─────────────────────────
+  // ── Cache-mutation API (used by the bus-event subscribers below and by
+  //    other namespaces that know about specific updates) ─────────────────
+  //
+  //  - `invalidate*`     — SWR refetch (B7). Keeps prior value visible.
+  //  - `removeAnnotationDetail` — drops the entry (B13a: entity gone).
+  //  - `updateAnnotationInPlace` — write-through (B13b: new value known).
   invalidateAnnotationList(resourceId) {
-    const next = new Map(this.annotationList$.value);
-    next.delete(resourceId);
-    this.annotationList$.next(next);
-    this.fetchAnnotationList(resourceId);
+    this.annotationListCache.invalidate(resourceId);
   }
-  invalidateAnnotationDetail(annotationId) {
-    const next = new Map(this.annotationDetail$.value);
-    next.delete(annotationId);
-    this.annotationDetail$.next(next);
+  removeAnnotationDetail(annotationId) {
+    this.annotationDetailCache.remove(annotationId);
+    this.annotationResources.delete(annotationId);
   }
   invalidateResourceDetail(id) {
-    const next = new Map(this.resourceDetail$.value);
-    next.delete(id);
-    this.resourceDetail$.next(next);
-    this.fetchResourceDetail(id);
+    this.resourceCache.invalidate(id);
   }
   invalidateResourceLists() {
-    this.resourceList$.next(/* @__PURE__ */ new Map());
+    this.resourceListCache.invalidateAll();
   }
   invalidateEntityTypes() {
-    this.entityTypes$.next(void 0);
-    this.fetchEntityTypes();
+    this.entityTypesCache.invalidate(ENTITY_TYPES_KEY);
   }
   invalidateReferencedBy(resourceId) {
-    const next = new Map(this.referencedBy$.value);
-    next.delete(resourceId);
-    this.referencedBy$.next(next);
-    this.fetchReferencedBy(resourceId);
+    this.referencedByCache.invalidate(resourceId);
+  }
+  invalidateResourceEvents(resourceId) {
+    this.resourceEventsCache.invalidate(resourceId);
   }
   updateAnnotationInPlace(resourceId, annotation) {
-    const currentList = this.annotationList$.value.get(resourceId);
-    if (!currentList) return;
-    const existingIdx = currentList.annotations.findIndex((a) => a.id === annotation.id);
-    const nextAnnotations = existingIdx >= 0 ? currentList.annotations.map((a, i) => i === existingIdx ? annotation : a) : [...currentList.annotations, annotation];
-    const nextList = { ...currentList, annotations: nextAnnotations };
-    const nextMap = new Map(this.annotationList$.value);
-    nextMap.set(resourceId, nextList);
-    this.annotationList$.next(nextMap);
+    const currentList = this.annotationListCache.get(resourceId);
+    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 });
+    }
+    const aId = annotationId(annotation.id);
+    this.annotationResources.set(aId, resourceId);
+    this.annotationDetailCache.set(aId, annotation);
   }
   // ── EventBus subscriptions ──────────────────────────────────────────────
+  /**
+   * Typed shorthand for `eventBus.get(channel).subscribe(handler)`.
+   * Preserves per-channel payload typing so handlers read
+   * `EventMap[K]` without any casts.
+   */
+  on(channel, handler) {
+    this.eventBus.get(channel).subscribe(handler);
+  }
+  /**
+   * Handler shared by `mark:entity-tag-added` and `mark:entity-tag-removed`.
+   * Both events carry the same effect: the annotation list, the
+   * resource descriptor, and the event log for that resource all may
+   * now reflect different entity tagging, so invalidate all three.
+   */
+  onEntityTagChanged = (stored) => {
+    if (!stored.resourceId) return;
+    this.invalidateAnnotationList(stored.resourceId);
+    this.invalidateResourceDetail(stored.resourceId);
+    this.invalidateResourceEvents(stored.resourceId);
+  };
+  /**
+   * Handler shared by `mark:archived` and `mark:unarchived`. Both
+   * change a resource's archived flag, which is stored on the resource
+   * descriptor and affects the resource-list filter.
+   */
+  onArchiveToggled = (stored) => {
+    if (!stored.resourceId) return;
+    this.invalidateResourceDetail(stored.resourceId);
+    this.invalidateResourceLists();
+  };
+  /**
+   * Handler shared by `yield:create-ok` and `yield:update-ok`. Both
+   * report a resource mutation with the resourceId as a string (not
+   * yet branded), so we brand and apply the same effect as
+   * `onArchiveToggled`.
+   */
+  onYieldResourceMutated = (event) => {
+    const rId = resourceId(event.resourceId);
+    this.invalidateResourceDetail(rId);
+    this.invalidateResourceLists();
+  };
   subscribeToEvents() {
-    const bus = this.eventBus;
-    bus.get("mark:delete-ok").subscribe((event) => {
-      this.invalidateAnnotationDetail(annotationId(event.annotationId));
+    this.on("bus:resume-gap", (event) => {
+      const gapScope = event.scope;
+      if (gapScope) {
+        const rId = gapScope;
+        this.invalidateAnnotationList(rId);
+        this.invalidateResourceDetail(rId);
+        this.invalidateResourceEvents(rId);
+        this.invalidateReferencedBy(rId);
+      } else {
+        this.invalidateResourceLists();
+        for (const rId of this.annotationListCache.keys()) this.invalidateAnnotationList(rId);
+        for (const rId of this.resourceCache.keys()) this.invalidateResourceDetail(rId);
+        for (const rId of this.resourceEventsCache.keys()) this.invalidateResourceEvents(rId);
+        for (const rId of this.referencedByCache.keys()) this.invalidateReferencedBy(rId);
+      }
+      this.invalidateEntityTypes();
     });
-    bus.get("mark:added").subscribe((stored) => {
+    this.on("mark:delete-ok", (event) => {
+      this.removeAnnotationDetail(annotationId(event.annotationId));
+    });
+    this.on("mark:added", (stored) => {
       if (stored.resourceId) {
         this.invalidateAnnotationList(stored.resourceId);
+        this.invalidateResourceEvents(stored.resourceId);
       }
     });
-    bus.get("mark:removed").subscribe((stored) => {
+    this.on("mark:removed", (stored) => {
       if (stored.resourceId) {
         this.invalidateAnnotationList(stored.resourceId);
+        this.invalidateResourceEvents(stored.resourceId);
       }
-      this.invalidateAnnotationDetail(annotationId(stored.payload.annotationId));
+      this.removeAnnotationDetail(annotationId(stored.payload.annotationId));
     });
-    bus.get("mark:body-updated").subscribe((event) => {
+    this.on("mark:body-updated", (event) => {
       const enriched = event;
       if (!enriched.resourceId || !enriched.annotation) return;
       this.updateAnnotationInPlace(enriched.resourceId, enriched.annotation);
-      this.invalidateAnnotationDetail(annotationId(enriched.annotation.id));
-    });
-    bus.get("mark:entity-tag-added").subscribe((stored) => {
-      if (stored.resourceId) {
-        this.invalidateAnnotationList(stored.resourceId);
-        this.invalidateResourceDetail(stored.resourceId);
-      }
-    });
-    bus.get("mark:entity-tag-removed").subscribe((stored) => {
-      if (stored.resourceId) {
-        this.invalidateAnnotationList(stored.resourceId);
-        this.invalidateResourceDetail(stored.resourceId);
-      }
+      this.invalidateResourceEvents(enriched.resourceId);
     });
-    bus.get("replay-window-exceeded").subscribe((event) => {
+    this.on("mark:entity-tag-added", this.onEntityTagChanged);
+    this.on("mark:entity-tag-removed", this.onEntityTagChanged);
+    this.on("replay-window-exceeded", (event) => {
       if (event.resourceId) {
         this.invalidateAnnotationList(event.resourceId);
       }
     });
-    bus.get("yield:create-ok").subscribe((event) => {
-      this.fetchResourceDetail(resourceId(event.resourceId));
-      this.invalidateResourceLists();
-    });
-    bus.get("yield:update-ok").subscribe((event) => {
-      this.invalidateResourceDetail(resourceId(event.resourceId));
-      this.invalidateResourceLists();
-    });
-    bus.get("mark:archived").subscribe((stored) => {
-      if (stored.resourceId) {
-        this.invalidateResourceDetail(stored.resourceId);
-        this.invalidateResourceLists();
-      }
-    });
-    bus.get("mark:unarchived").subscribe((stored) => {
-      if (stored.resourceId) {
-        this.invalidateResourceDetail(stored.resourceId);
-        this.invalidateResourceLists();
-      }
-    });
-    bus.get("mark:entity-type-added").subscribe(() => {
-      this.invalidateEntityTypes();
-    });
-  }
-  // ── Fetch helpers ───────────────────────────────────────────────────────
-  async fetchAnnotationList(resourceId) {
-    if (this.fetchingAnnotationList.has(resourceId)) return;
-    this.fetchingAnnotationList.add(resourceId);
-    try {
-      const result = await this.http.browseAnnotations(resourceId, void 0, { auth: this.getToken() });
-      const next = new Map(this.annotationList$.value);
-      next.set(resourceId, result);
-      this.annotationList$.next(next);
-    } catch {
-    } finally {
-      this.fetchingAnnotationList.delete(resourceId);
-    }
-  }
-  async fetchAnnotationDetail(resourceId, annotationId) {
-    if (this.fetchingAnnotationDetail.has(annotationId)) return;
-    this.fetchingAnnotationDetail.add(annotationId);
-    try {
-      const result = await this.http.browseAnnotation(resourceId, annotationId, { auth: this.getToken() });
-      const next = new Map(this.annotationDetail$.value);
-      next.set(annotationId, result.annotation);
-      this.annotationDetail$.next(next);
-    } catch {
-    } finally {
-      this.fetchingAnnotationDetail.delete(annotationId);
-    }
-  }
-  async fetchResourceDetail(id) {
-    if (this.fetchingResourceDetail.has(id)) return;
-    this.fetchingResourceDetail.add(id);
-    try {
-      const result = await this.http.browseResource(id, { auth: this.getToken() });
-      const next = new Map(this.resourceDetail$.value);
-      next.set(id, result.resource);
-      this.resourceDetail$.next(next);
-    } catch {
-    } finally {
-      this.fetchingResourceDetail.delete(id);
-    }
-  }
-  async fetchResourceList(key, filters) {
-    if (this.fetchingResourceList.has(key)) return;
-    this.fetchingResourceList.add(key);
-    try {
-      const search = filters?.search ? searchQuery(filters.search) : void 0;
-      const result = await this.http.browseResources(filters?.limit, filters?.archived, search, { auth: this.getToken() });
-      const next = new Map(this.resourceList$.value);
-      next.set(key, result.resources);
-      this.resourceList$.next(next);
-    } catch {
-    } finally {
-      this.fetchingResourceList.delete(key);
-    }
-  }
-  async fetchEntityTypes() {
-    if (this.fetchingEntityTypes) return;
-    this.fetchingEntityTypes = true;
-    try {
-      const result = await this.http.listEntityTypes({ auth: this.getToken() });
-      this.entityTypes$.next(result.entityTypes);
-    } catch {
-    } finally {
-      this.fetchingEntityTypes = false;
-    }
-  }
-  async fetchReferencedBy(resourceId) {
-    if (this.fetchingReferencedBy.has(resourceId)) return;
-    this.fetchingReferencedBy.add(resourceId);
-    try {
-      const result = await this.http.browseReferences(resourceId, { auth: this.getToken() });
-      const next = new Map(this.referencedBy$.value);
-      next.set(resourceId, result.referencedBy);
-      this.referencedBy$.next(next);
-    } catch {
-    } finally {
-      this.fetchingReferencedBy.delete(resourceId);
-    }
+    this.on("yield:create-ok", this.onYieldResourceMutated);
+    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());
   }
 };
 var MarkNamespace = class {
-  constructor(http, eventBus, getToken) {
+  constructor(http, eventBus, getToken, actor) {
     this.http = http;
     this.eventBus = eventBus;
     this.getToken = getToken;
+    this.actor = actor;
   }
   async annotation(resourceId, input) {
-    return this.http.markAnnotation(resourceId, input, { auth: this.getToken() });
+    return busRequest(
+      this.actor,
+      "mark:create-request",
+      { resourceId, request: input },
+      "mark:create-ok",
+      "mark:create-failed"
+    );
   }
   async delete(resourceId, annotationId) {
-    return this.http.deleteAnnotation(resourceId, annotationId, { auth: this.getToken() });
+    await this.actor.emit("mark:delete", { annotationId, resourceId });
   }
   async entityType(type) {
-    return this.http.addEntityType(type, { auth: this.getToken() });
+    await this.actor.emit("mark:add-entity-type", { tag: type });
   }
   async entityTypes(types) {
-    return this.http.addEntityTypesBulk(types, { auth: this.getToken() });
+    for (const tag of types) {
+      await this.actor.emit("mark:add-entity-type", { tag });
+    }
   }
   async updateResource(resourceId, data) {
     return this.http.updateResource(resourceId, data, { auth: this.getToken() });
   }
   async archive(resourceId) {
-    return this.http.updateResource(resourceId, { archived: true }, { auth: this.getToken() });
+    await this.actor.emit("mark:archive", { resourceId });
   }
   async unarchive(resourceId) {
-    return this.http.updateResource(resourceId, { archived: false }, { auth: this.getToken() });
+    await this.actor.emit("mark:unarchive", { resourceId });
   }
   assist(resourceId, motivation, options) {
     return new Observable((subscriber) => {
-      const progress$ = this.eventBus.get("mark:progress").pipe(
-        filter((e) => e.resourceId === resourceId)
+      let done = false;
+      let pollTimer = null;
+      let pollInterval = null;
+      const cleanup = () => {
+        done = true;
+        if (pollTimer) {
+          clearTimeout(pollTimer);
+          pollTimer = null;
+        }
+        if (pollInterval) {
+          clearInterval(pollInterval);
+          pollInterval = null;
+        }
+      };
+      const resetPollTimer = (jobId) => {
+        if (pollTimer) clearTimeout(pollTimer);
+        if (pollInterval) {
+          clearInterval(pollInterval);
+          pollInterval = null;
+        }
+        pollTimer = setTimeout(() => {
+          if (done) return;
+          pollInterval = setInterval(() => {
+            if (done) return;
+            busRequest(
+              this.actor,
+              "job:status-requested",
+              { jobId },
+              "job:status-result",
+              "job:status-failed"
+            ).then((status) => {
+              if (done) return;
+              if (status.status === "complete") {
+                cleanup();
+                subscriber.next({ motivation, resourceId, progress: status.result });
+                subscriber.complete();
+              } else if (status.status === "failed") {
+                cleanup();
+                subscriber.error(new Error(status.error ?? "Job failed"));
+              }
+            }).catch(() => {
+            });
+          }, 5e3);
+        }, 1e4);
+      };
+      let activeJobId = null;
+      const progress$ = this.eventBus.get("job:report-progress").pipe(
+        filter((e) => e.jobId === activeJobId)
       );
-      const finished$ = this.eventBus.get("mark:assist-finished").pipe(
-        filter((e) => e.resourceId === resourceId && e.motivation === motivation)
+      const complete$ = this.eventBus.get("job:complete").pipe(
+        filter((e) => e.jobId === activeJobId)
       );
-      const failed$ = this.eventBus.get("mark:assist-failed").pipe(
-        filter((e) => e.resourceId === resourceId)
+      const fail$ = this.eventBus.get("job:fail").pipe(
+        filter((e) => e.jobId === activeJobId)
       );
-      const progressSub = progress$.pipe(takeUntil(merge(finished$, failed$))).subscribe((e) => subscriber.next(e));
-      const finishedSub = finished$.subscribe((e) => {
-        subscriber.next(e);
+      const progressSub = progress$.pipe(takeUntil(merge(complete$, fail$))).subscribe((e) => {
+        subscriber.next(e.progress);
+        if (activeJobId) resetPollTimer(activeJobId);
+      });
+      const completeSub = complete$.subscribe(() => {
+        cleanup();
         subscriber.complete();
       });
-      const failedSub = failed$.subscribe((e) => {
-        subscriber.error(new Error(e.message));
+      const failSub = fail$.subscribe((e) => {
+        cleanup();
+        subscriber.error(new Error(e.error));
       });
       const auth = this.getToken();
-      const postPromise = this.dispatchAssist(resourceId, motivation, options, auth);
-      postPromise.catch((error) => {
+      this.dispatchAssist(resourceId, motivation, options, auth).then(({ jobId }) => {
+        if (jobId && !done) {
+          activeJobId = jobId;
+          resetPollTimer(jobId);
+        }
+      }).catch((error) => {
+        cleanup();
         subscriber.error(error);
       });
       return () => {
+        cleanup();
         progressSub.unsubscribe();
-        finishedSub.unsubscribe();
-        failedSub.unsubscribe();
+        completeSub.unsubscribe();
+        failSub.unsubscribe();
       };
     });
   }
-  async dispatchAssist(resourceId, motivation, options, auth) {
+  async dispatchAssist(resourceId, motivation, options, _auth) {
+    const jobTypeMap = {
+      tagging: "tag-annotation",
+      linking: "reference-annotation",
+      highlighting: "highlight-annotation",
+      assessing: "assessment-annotation",
+      commenting: "comment-annotation"
+    };
+    const jobType = jobTypeMap[motivation];
+    if (!jobType) throw new Error(`Unsupported motivation: ${motivation}`);
     if (motivation === "tagging") {
-      const { schemaId, categories } = options;
-      if (!schemaId || !categories?.length) throw new Error("Tag assist requires schemaId and categories");
-      await this.http.annotateTags(resourceId, { schemaId, categories }, { auth });
+      if (!options.schemaId || !options.categories?.length) throw new Error("Tag assist requires schemaId and categories");
     } else if (motivation === "linking") {
-      const { entityTypes, includeDescriptiveReferences } = options;
-      if (!entityTypes?.length) throw new Error("Reference assist requires entityTypes");
-      await this.http.annotateReferences(resourceId, {
-        entityTypes,
-        includeDescriptiveReferences: includeDescriptiveReferences ?? false
-      }, { auth });
-    } else if (motivation === "highlighting") {
-      await this.http.annotateHighlights(resourceId, {
-        instructions: options.instructions,
-        density: options.density
-      }, { auth });
-    } else if (motivation === "assessing") {
-      await this.http.annotateAssessments(resourceId, {
-        instructions: options.instructions,
-        tone: options.tone,
-        density: options.density,
-        language: options.language
-      }, { auth });
-    } else if (motivation === "commenting") {
-      await this.http.annotateComments(resourceId, {
-        instructions: options.instructions,
-        tone: options.tone,
-        density: options.density,
-        language: options.language
-      }, { auth });
+      if (!options.entityTypes?.length) throw new Error("Reference assist requires entityTypes");
     }
+    const params = {};
+    if (options.entityTypes) params.entityTypes = options.entityTypes;
+    if (options.includeDescriptiveReferences !== void 0) params.includeDescriptiveReferences = options.includeDescriptiveReferences;
+    if (options.instructions !== void 0) params.instructions = options.instructions;
+    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.schemaId !== void 0) params.schemaId = options.schemaId;
+    if (options.categories !== void 0) params.categories = options.categories;
+    return busRequest(
+      this.actor,
+      "job:create",
+      { jobType, resourceId, params },
+      "job:created",
+      "job:create-failed"
+    );
   }
 };
 
 // src/namespaces/bind.ts
 var BindNamespace = class {
-  constructor(http, getToken) {
-    this.http = http;
-    this.getToken = getToken;
+  constructor(actor) {
+    this.actor = actor;
   }
   async body(resourceId, annotationId, operations) {
-    await this.http.bindAnnotation(resourceId, annotationId, { operations }, { auth: this.getToken() });
+    await this.actor.emit("bind:update-body", {
+      correlationId: crypto.randomUUID(),
+      annotationId,
+      resourceId,
+      operations
+    });
   }
 };
 var GatherNamespace = class {
-  constructor(http, eventBus, getToken) {
-    this.http = http;
+  constructor(eventBus, actor) {
     this.eventBus = eventBus;
-    this.getToken = getToken;
+    this.actor = actor;
   }
-  annotation(annotationId$1, resourceId, options) {
+  annotation(annotationId, resourceId, options) {
     return new Observable((subscriber) => {
       const correlationId = crypto.randomUUID();
       const complete$ = this.eventBus.get("gather:complete").pipe(
@@ -788,8 +898,7 @@ var GatherNamespace = class {
       );
       const sub = merge(
         this.eventBus.get("gather:annotation-progress").pipe(
-          // Progress events don't carry correlationId, so match by annotationId
-          filter((e) => e.annotationId === annotationId$1),
+          filter((e) => e.annotationId === annotationId),
           map((e) => e)
         ),
         complete$.pipe(map((e) => e))
@@ -804,12 +913,12 @@ var GatherNamespace = class {
       const failedSub = failed$.subscribe((e) => {
         subscriber.error(new Error(e.message));
       });
-      this.http.gatherAnnotationContext(
+      this.actor.emit("gather:requested", {
+        correlationId,
+        annotationId,
         resourceId,
-        annotationId(annotationId$1),
-        { correlationId, contextWindow: options?.contextWindow ?? 2e3 },
-        { auth: this.getToken() }
-      ).catch((error) => {
+        contextWindow: options?.contextWindow ?? 2e3
+      }).catch((error) => {
         subscriber.error(error);
       });
       return () => {
@@ -824,10 +933,9 @@ var GatherNamespace = class {
   }
 };
 var MatchNamespace = class {
-  constructor(http, eventBus, getToken) {
-    this.http = http;
+  constructor(eventBus, actor) {
     this.eventBus = eventBus;
-    this.getToken = getToken;
+    this.actor = actor;
   }
   search(resourceId, referenceId, context, options) {
     return new Observable((subscriber) => {
@@ -845,17 +953,14 @@ var MatchNamespace = class {
       const failedSub = failed$.subscribe((e) => {
         subscriber.error(new Error(e.error));
       });
-      this.http.matchSearch(
+      this.actor.emit("match:search-requested", {
+        correlationId,
         resourceId,
-        {
-          correlationId,
-          referenceId,
-          context,
-          limit: options?.limit,
-          useSemanticScoring: options?.useSemanticScoring
-        },
-        { auth: this.getToken() }
-      ).catch((error) => {
+        referenceId,
+        context,
+        limit: options?.limit ?? 10,
+        useSemanticScoring: options?.useSemanticScoring ?? true
+      }).catch((error) => {
         subscriber.error(error);
       });
       return () => {
@@ -866,105 +971,193 @@ var MatchNamespace = class {
   }
 };
 var YieldNamespace = class {
-  constructor(http, eventBus, getToken) {
+  constructor(http, eventBus, getToken, actor) {
     this.http = http;
     this.eventBus = eventBus;
     this.getToken = getToken;
+    this.actor = actor;
   }
   async resource(data) {
     return this.http.yieldResource(data, { auth: this.getToken() });
   }
-  fromAnnotation(resourceId$1, annotationId$1, options) {
+  fromAnnotation(resourceId, annotationId, options) {
     return new Observable((subscriber) => {
-      const progress$ = this.eventBus.get("yield:progress").pipe(
-        filter((e) => e.referenceId === annotationId$1)
+      let done = false;
+      let pollTimer = null;
+      let pollInterval = null;
+      const cleanup = () => {
+        done = true;
+        if (pollTimer) {
+          clearTimeout(pollTimer);
+          pollTimer = null;
+        }
+        if (pollInterval) {
+          clearInterval(pollInterval);
+          pollInterval = null;
+        }
+      };
+      const resetPollTimer = (jid) => {
+        if (pollTimer) clearTimeout(pollTimer);
+        if (pollInterval) {
+          clearInterval(pollInterval);
+          pollInterval = null;
+        }
+        pollTimer = setTimeout(() => {
+          if (done) return;
+          pollInterval = setInterval(() => {
+            if (done) return;
+            busRequest(
+              this.actor,
+              "job:status-requested",
+              { jobId: jid },
+              "job:status-result",
+              "job:status-failed"
+            ).then((status) => {
+              if (done) return;
+              if (status.status === "complete") {
+                cleanup();
+                subscriber.next({ stage: "complete", percentage: 100, message: "Generation complete" });
+                subscriber.complete();
+              } else if (status.status === "failed") {
+                cleanup();
+                subscriber.error(new Error(status.error ?? "Generation failed"));
+              }
+            }).catch(() => {
+            });
+          }, 5e3);
+        }, 1e4);
+      };
+      let activeJobId = null;
+      const progress$ = this.eventBus.get("job:report-progress").pipe(
+        filter((e) => e.jobId === activeJobId)
       );
-      const finished$ = this.eventBus.get("yield:finished").pipe(
-        filter((e) => e.referenceId === annotationId$1)
+      const complete$ = this.eventBus.get("job:complete").pipe(
+        filter((e) => e.jobId === activeJobId)
       );
-      const failed$ = this.eventBus.get("yield:failed").pipe(
-        filter((e) => e.referenceId === annotationId$1)
+      const fail$ = this.eventBus.get("job:fail").pipe(
+        filter((e) => e.jobId === activeJobId)
       );
-      const progressSub = progress$.pipe(takeUntil(merge(finished$, failed$))).subscribe((e) => subscriber.next(e));
-      const finishedSub = finished$.subscribe((event) => {
-        subscriber.next(event);
+      const progressSub = progress$.pipe(takeUntil(merge(complete$, fail$))).subscribe((e) => {
+        subscriber.next(e.progress);
+        if (activeJobId) resetPollTimer(activeJobId);
+      });
+      const completeSub = complete$.subscribe(() => {
+        cleanup();
         subscriber.complete();
-        if (event.resourceId && event.referenceId && event.sourceResourceId) {
-          this.eventBus.get("bind:update-body").next({
-            correlationId: crypto.randomUUID(),
-            annotationId: annotationId(event.referenceId),
-            resourceId: resourceId(event.sourceResourceId),
-            operations: [{ op: "add", item: { type: "SpecificResource", source: event.resourceId } }]
-          });
-        }
       });
-      const failedSub = failed$.subscribe((e) => {
-        subscriber.error(new Error(e.error ?? e.message ?? "Generation failed"));
+      const failSub = fail$.subscribe((e) => {
+        cleanup();
+        subscriber.error(new Error(e.error));
       });
-      this.http.yieldResourceFromAnnotation(
-        resourceId$1,
-        annotationId$1,
-        options,
-        { auth: this.getToken() }
-      ).catch((error) => {
+      busRequest(
+        this.actor,
+        "job:create",
+        {
+          jobType: "generation",
+          resourceId,
+          params: {
+            referenceId: annotationId,
+            title: options.title,
+            prompt: options.prompt,
+            language: options.language,
+            temperature: options.temperature,
+            maxTokens: options.maxTokens,
+            storageUri: options.storageUri,
+            context: options.context
+          }
+        },
+        "job:created",
+        "job:create-failed"
+      ).then(({ jobId }) => {
+        if (jobId && !done) {
+          activeJobId = jobId;
+          resetPollTimer(jobId);
+        }
+      }).catch((error) => {
+        cleanup();
         subscriber.error(error);
       });
       return () => {
+        cleanup();
         progressSub.unsubscribe();
-        finishedSub.unsubscribe();
-        failedSub.unsubscribe();
+        completeSub.unsubscribe();
+        failSub.unsubscribe();
       };
     });
   }
   async cloneToken(resourceId) {
-    const result = await this.http.generateCloneToken(resourceId, { auth: this.getToken() });
-    return result;
+    return busRequest(
+      this.actor,
+      "yield:clone-token-requested",
+      { resourceId },
+      "yield:clone-token-generated",
+      "yield:clone-token-failed"
+    );
   }
   async fromToken(token) {
-    const result = await this.http.getResourceByToken(token, { auth: this.getToken() });
+    const result = await busRequest(
+      this.actor,
+      "yield:clone-resource-requested",
+      { token },
+      "yield:clone-resource-result",
+      "yield:clone-resource-failed"
+    );
     return result.sourceResource;
   }
   async createFromToken(options) {
-    return this.http.createResourceFromToken(options, { auth: this.getToken() });
+    return busRequest(
+      this.actor,
+      "yield:clone-create",
+      options,
+      "yield:clone-created",
+      "yield:clone-create-failed"
+    );
   }
 };
 
 // src/namespaces/beckon.ts
 var BeckonNamespace = class {
-  constructor(http, getToken) {
-    this.http = http;
-    this.getToken = getToken;
+  constructor(actor) {
+    this.actor = actor;
   }
   attention(annotationId, resourceId) {
-    this.http.beckonAttention(
-      "me",
-      // participantId — always 'me' for self-identification
-      { annotationId, resourceId },
-      { auth: this.getToken() }
-    ).catch(() => {
+    this.actor.emit("beckon:focus", { annotationId, resourceId }).catch(() => {
     });
   }
 };
 
 // src/namespaces/job.ts
 var JobNamespace = class {
-  constructor(http, getToken) {
-    this.http = http;
-    this.getToken = getToken;
+  constructor(actor) {
+    this.actor = actor;
   }
   async status(jobId) {
-    return this.http.getJobStatus(jobId, { auth: this.getToken() });
+    return busRequest(
+      this.actor,
+      "job:status-requested",
+      { jobId },
+      "job:status-result",
+      "job:status-failed"
+    );
   }
   async pollUntilComplete(jobId, options) {
-    return this.http.pollJobUntilComplete(jobId, {
-      interval: options?.interval,
-      timeout: options?.timeout,
-      onProgress: options?.onProgress,
-      auth: this.getToken()
-    });
+    const interval = options?.interval ?? 1e3;
+    const timeout7 = options?.timeout ?? 6e4;
+    const startTime = Date.now();
+    while (true) {
+      const status = await this.status(jobId);
+      if (options?.onProgress) options.onProgress(status);
+      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`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
   }
   async cancel(jobId, type) {
-    throw new Error(`Not implemented: job.cancel(${jobId}, ${type}) \u2014 needs EventBus wiring`);
+    await this.actor.emit("job:cancel-requested", { jobId, type });
   }
 };
 var AuthNamespace = class {
@@ -1037,8 +1230,66 @@ var AdminNamespace = class {
     return this.http.importKnowledgeBase(file, { auth: this.getToken(), onProgress });
   }
 };
-
-// src/client.ts
+var RESOURCE_SCOPED_CHANNELS = [
+  ...PERSISTED_EVENT_TYPES.filter((t) => t !== "mark:entity-type-added"),
+  ...RESOURCE_BROADCAST_TYPES
+];
+var BUS_RESULT_CHANNELS = [
+  "browse:resources-result",
+  "browse:resources-failed",
+  "browse:resource-result",
+  "browse:resource-failed",
+  "browse:annotations-result",
+  "browse:annotations-failed",
+  "browse:annotation-result",
+  "browse:annotation-failed",
+  "browse:annotation-history-result",
+  "browse:annotation-history-failed",
+  "browse:events-result",
+  "browse:events-failed",
+  "browse:referenced-by-result",
+  "browse:referenced-by-failed",
+  "browse:entity-types-result",
+  "browse:entity-types-failed",
+  "browse:directory-result",
+  "browse:directory-failed",
+  "browse:annotation-context-result",
+  "browse:annotation-context-failed",
+  "mark:delete-ok",
+  "mark:delete-failed",
+  "mark:create-ok",
+  "mark:create-failed",
+  "match:search-results",
+  "match:search-failed",
+  "gather:complete",
+  "gather:failed",
+  "gather:annotation-progress",
+  "gather:annotation-finished",
+  "gather:summary-result",
+  "gather:summary-failed",
+  "bind:body-updated",
+  "bind:body-update-failed",
+  "job:report-progress",
+  "job:complete",
+  "job:fail",
+  "job:status-result",
+  "job:status-failed",
+  "job:created",
+  "job:create-failed",
+  "job:claimed",
+  "job:claim-failed",
+  "yield:clone-token-generated",
+  "yield:clone-token-failed",
+  "yield:clone-resource-result",
+  "yield:clone-resource-failed",
+  "yield:clone-created",
+  "yield:clone-create-failed",
+  "mark:entity-type-added",
+  "beckon:focus",
+  "beckon:sparkle",
+  "bus:resume-gap"
+];
+var ACTOR_TO_LOCAL_BRIDGES = BUS_RESULT_CHANNELS;
 var APIError = class extends Error {
   constructor(message, status, statusText, details) {
     super(message);
@@ -1051,21 +1302,18 @@ var APIError = class extends Error {
 var SemiontApiClient = class {
   http;
   baseUrl;
-  /** The workspace-scoped EventBus this client was constructed with. */
-  eventBus;
-  logger;
   /**
-   * Shared mutable token getter. All verb namespaces read from this.
-   * Updated via setTokenGetter() from the React auth layer.
+   * Workspace-scoped EventBus — owned by the client, constructed
+   * internally, never accepted from config. Private: all bus access
+   * goes through `client.emit` / `client.on` / `client.stream`.
    */
-  _getToken = () => void 0;
+  eventBus;
+  logger;
   /**
-   * SSE streaming client for real-time operations
-   *
-   * Separate from the main HTTP client to clearly mark streaming endpoints.
-   * Uses native fetch() instead of ky for SSE support.
+   * Observable token source. All auth reads from this.
    */
-  sse;
+  token$;
+  _actor = null;
   // ── Verb-oriented namespace API ──────────────────────────────────────────
   browse;
   mark;
@@ -1078,17 +1326,17 @@ var SemiontApiClient = class {
   auth;
   admin;
   constructor(config) {
-    const { baseUrl, eventBus, timeout = 3e4, retry = 2, logger, tokenRefresher } = config;
-    this.eventBus = eventBus;
+    const { baseUrl: baseUrl3, timeout: timeout7 = 3e4, retry = 2, logger, tokenRefresher } = config;
+    this.eventBus = new EventBus();
     this.logger = logger;
-    this.baseUrl = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+    this.baseUrl = baseUrl3.endsWith("/") ? baseUrl3.slice(0, -1) : baseUrl3;
     const retryConfig = tokenRefresher ? {
       limit: 1,
       methods: ["get", "post", "put", "patch", "delete", "head", "options"],
       statusCodes: [401, 408, 413, 429, 500, 502, 503, 504]
     } : retry;
     this.http = ky.create({
-      timeout,
+      timeout: timeout7,
       retry: retryConfig,
       credentials: "include",
       hooks: {
@@ -1161,33 +1409,131 @@ var SemiontApiClient = class {
         ]
       }
     });
-    this.sse = new SSEClient({
-      baseUrl: this.baseUrl,
-      logger: this.logger
-    });
-    if (config.getToken) this._getToken = config.getToken;
-    const getToken = () => this._getToken();
-    this.browse = new BrowseNamespace(this, this.eventBus, getToken);
-    this.mark = new MarkNamespace(this, this.eventBus, getToken);
-    this.bind = new BindNamespace(this, getToken);
-    this.gather = new GatherNamespace(this, this.eventBus, getToken);
-    this.match = new MatchNamespace(this, this.eventBus, getToken);
-    this.yield = new YieldNamespace(this, this.eventBus, getToken);
-    this.beckon = new BeckonNamespace(this, getToken);
-    this.job = new JobNamespace(this, getToken);
+    this.token$ = config.token$ ?? new BehaviorSubject(null);
+    const getToken = () => this.token$.getValue() ?? void 0;
+    this.browse = new BrowseNamespace(this, this.eventBus, getToken, this.actor);
+    this.mark = new MarkNamespace(this, this.eventBus, getToken, this.actor);
+    this.bind = new BindNamespace(this.actor);
+    this.gather = new GatherNamespace(this.eventBus, this.actor);
+    this.match = new MatchNamespace(this.eventBus, this.actor);
+    this.yield = new YieldNamespace(this, this.eventBus, getToken, this.actor);
+    this.beckon = new BeckonNamespace(this.actor);
+    this.job = new JobNamespace(this.actor);
     this.auth = new AuthNamespace(this, getToken);
     this.admin = new AdminNamespace(this, getToken);
+    this.token$.subscribe((token) => {
+      if (token && !this._actorStarted) {
+        this._actorStarted = true;
+        this.actor.start();
+      }
+    });
   }
+  _actorStarted = false;
+  get actor() {
+    if (!this._actor) {
+      this._actor = createActorVM({
+        baseUrl: this.baseUrl,
+        token: () => this.token$.getValue() ?? "",
+        channels: [...BUS_RESULT_CHANNELS]
+      });
+      for (const channel of ACTOR_TO_LOCAL_BRIDGES) {
+        this._actor.on$(channel).subscribe((payload) => {
+          this.eventBus.get(channel).next(payload);
+        });
+      }
+    }
+    return this._actor;
+  }
+  activeResource = null;
   /**
-   * Update the token getter for all verb namespaces.
-   * Called from the React auth layer when the token changes.
-   * All namespaces share this getter via closure — no per-namespace sync needed.
+   * Subscribe the bus actor to the resource-scoped SSE stream for a single
+   * resource and bridge incoming scoped events into the workspace event bus.
+   *
+   * **One distinct scope at a time**: the client supports subscriptions
+   * to a single resource scope concurrently. Multiple calls with the
+   * **same** resourceId are ref-counted — each returns an independent
+   * unsubscribe; the underlying SSE scope is torn down only when the
+   * last unsubscribe fires. Calling with a **different** resourceId
+   * while a subscription is live throws. Widening this to multiple
+   * concurrent scopes is deferred until a product requirement (e.g.
+   * split-pane viewer, headless fleet-watcher) forces the design.
+   *
+   * @returns a disposer that decrements the ref count (and tears down
+   *          the SSE scope + bridges when it reaches zero).
    */
-  setTokenGetter(getter) {
-    this._getToken = getter;
+  subscribeToResource(resourceId) {
+    if (this.activeResource) {
+      if (this.activeResource.resourceId !== resourceId) {
+        throw new Error(
+          `SemiontApiClient already subscribed to resource ${this.activeResource.resourceId}; call the unsubscribe returned from the previous subscribeToResource before subscribing to ${resourceId}.`
+        );
+      }
+      this.activeResource.refCount++;
+      return this.makeUnsubscriber();
+    }
+    this.actor.addChannels([...RESOURCE_SCOPED_CHANNELS], resourceId);
+    const bridgeSubs = [];
+    for (const channel of RESOURCE_SCOPED_CHANNELS) {
+      bridgeSubs.push(
+        this.actor.on$(channel).subscribe((payload) => {
+          this.eventBus.get(channel).next(payload);
+        })
+      );
+    }
+    this.activeResource = { resourceId, refCount: 1, bridgeSubs };
+    return this.makeUnsubscriber();
+  }
+  makeUnsubscriber() {
+    let called = false;
+    return () => {
+      if (called) return;
+      called = true;
+      if (!this.activeResource) return;
+      this.activeResource.refCount--;
+      if (this.activeResource.refCount > 0) return;
+      for (const sub of this.activeResource.bridgeSubs) sub.unsubscribe();
+      this.actor.removeChannels([...RESOURCE_SCOPED_CHANNELS]);
+      this.activeResource = null;
+    };
+  }
+  dispose() {
+    if (this.activeResource) {
+      for (const sub of this.activeResource.bridgeSubs) sub.unsubscribe();
+      this.activeResource = null;
+    }
+    if (this._actor) {
+      this._actor.dispose();
+      this._actor = null;
+    }
   }
+  // ── Event bus surface ─────────────────────────────────────────
+  // The ONE public path to the workspace bus. VMs, session, and
+  // components route through these methods; `this.eventBus` remains
+  // the internal owner and will be privatized once all callers
+  // have migrated.
+  /** Emit an event on the internal bus. */
+  emit(channel, payload) {
+    this.eventBus.get(channel).next(payload);
+  }
+  /** Subscribe to an event on the internal bus; returns unsubscribe. */
+  on(channel, handler) {
+    const sub = this.eventBus.get(channel).subscribe(handler);
+    return () => sub.unsubscribe();
+  }
+  /** Read-only observable for a bus channel. Consumers `.pipe(...)` over this. */
+  stream(channel) {
+    return this.eventBus.get(channel).asObservable();
+  }
+  /**
+   * Build the `Authorization: Bearer <token>` header. If the caller passed
+   * an explicit `{ auth }` it wins (used by session-internal throwaway
+   * clients that need to run a validation request with a specific token).
+   * Otherwise the current value of `this.token$` is used, so external
+   * callers never have to plumb the token themselves.
+   */
   authHeaders(options) {
-    return options?.auth ? { Authorization: `Bearer ${options.auth}` } : {};
+    const token = options?.auth ?? this.token$.getValue() ?? void 0;
+    return token ? { Authorization: `Bearer ${token}` } : {};
   }
   // ============================================================================
   // AUTHENTICATION
@@ -1254,6 +1600,8 @@ var SemiontApiClient = class {
    * @param data.creationMethod - Optional creation method
    * @param data.sourceAnnotationId - Optional source annotation ID
    * @param data.sourceResourceId - Optional source resource ID
+   * @param data.generationPrompt - Optional prompt that drove AI generation
+   * @param data.generator - Optional Agent(s) that generated the content
    * @param options - Request options including auth
    */
   async yieldResource(data, options) {
@@ -1284,15 +1632,22 @@ var SemiontApiClient = class {
     if (data.sourceResourceId) {
       formData.append("sourceResourceId", data.sourceResourceId);
     }
+    if (data.generationPrompt) {
+      formData.append("generationPrompt", data.generationPrompt);
+    }
+    if (data.generator) {
+      formData.append("generator", JSON.stringify(data.generator));
+    }
+    if (data.isDraft !== void 0) {
+      formData.append("isDraft", String(data.isDraft));
+    }
     return this.http.post(`${this.baseUrl}/resources`, {
       body: formData,
       headers: this.authHeaders(options)
     }).json();
   }
-  async browseResource(id, options) {
-    return this.http.get(`${this.baseUrl}/resources/${id}`, {
-      headers: this.authHeaders(options)
-    }).json();
+  async browseResource(id, _options) {
+    return busRequest(this.actor, "browse:resource-requested", { resourceId: id }, "browse:resource-result", "browse:resource-failed");
   }
   /**
    * Get resource representation using W3C content negotiation
@@ -1376,15 +1731,14 @@ var SemiontApiClient = class {
     }
     return { stream: response.body, contentType };
   }
-  async browseResources(limit, archived, query, options) {
-    const searchParams = new URLSearchParams();
-    if (limit) searchParams.append("limit", limit.toString());
-    if (archived !== void 0) searchParams.append("archived", archived.toString());
-    if (query) searchParams.append("q", query);
-    return this.http.get(`${this.baseUrl}/resources`, {
-      searchParams,
-      headers: this.authHeaders(options)
-    }).json();
+  async browseResources(limit, archived, query, _options) {
+    return busRequest(
+      this.actor,
+      "browse:resources-requested",
+      { search: query, archived, limit: limit ?? 100, offset: 0 },
+      "browse:resources-result",
+      "browse:resources-failed"
+    );
   }
   async updateResource(id, data, options) {
     await this.http.patch(`${this.baseUrl}/resources/${id}`, {
@@ -1392,151 +1746,153 @@ var SemiontApiClient = class {
       headers: this.authHeaders(options)
     }).text();
   }
-  async getResourceEvents(id, options) {
-    return this.http.get(`${this.baseUrl}/resources/${id}/events`, {
-      headers: this.authHeaders(options)
-    }).json();
+  async getResourceEvents(id, _options) {
+    return busRequest(this.actor, "browse:events-requested", { resourceId: id }, "browse:events-result", "browse:events-failed");
   }
-  async browseReferences(id, options) {
-    return this.http.get(`${this.baseUrl}/resources/${id}/referenced-by`, {
-      headers: this.authHeaders(options)
-    }).json();
+  async browseReferences(id, _options) {
+    return busRequest(this.actor, "browse:referenced-by-requested", { resourceId: id }, "browse:referenced-by-result", "browse:referenced-by-failed");
   }
-  async generateCloneToken(id, options) {
-    return this.http.post(`${this.baseUrl}/resources/${id}/clone-with-token`, {
-      headers: this.authHeaders(options)
-    }).json();
+  async generateCloneToken(id, _options) {
+    return busRequest(this.actor, "yield:clone-token-requested", { resourceId: id }, "yield:clone-token-generated", "yield:clone-token-failed");
   }
-  async getResourceByToken(token, options) {
-    return this.http.get(`${this.baseUrl}/api/clone-tokens/${token}`, {
-      headers: this.authHeaders(options)
-    }).json();
+  async getResourceByToken(token, _options) {
+    return busRequest(this.actor, "yield:clone-resource-requested", { token }, "yield:clone-resource-result", "yield:clone-resource-failed");
   }
-  async createResourceFromToken(data, options) {
-    return this.http.post(`${this.baseUrl}/api/clone-tokens/create-resource`, {
-      json: data,
-      headers: this.authHeaders(options)
-    }).json();
+  async createResourceFromToken(data, _options) {
+    return busRequest(this.actor, "yield:clone-create", data, "yield:clone-created", "yield:clone-create-failed");
   }
   // ============================================================================
   // ANNOTATIONS
   // ============================================================================
-  async markAnnotation(id, data, options) {
-    return this.http.post(`${this.baseUrl}/resources/${id}/annotations`, {
-      json: data,
-      headers: this.authHeaders(options)
-    }).json();
-  }
-  async getAnnotation(id, options) {
-    return this.http.get(`${this.baseUrl}/annotations/${id}`, {
-      headers: this.authHeaders(options)
-    }).json();
-  }
-  async browseAnnotation(resourceId, annotationId, options) {
-    return this.http.get(`${this.baseUrl}/resources/${resourceId}/annotations/${annotationId}`, {
-      headers: this.authHeaders(options)
-    }).json();
-  }
-  async browseAnnotations(id, motivation, options) {
-    const searchParams = new URLSearchParams();
-    if (motivation) searchParams.append("motivation", motivation);
-    return this.http.get(`${this.baseUrl}/resources/${id}/annotations`, {
-      searchParams,
-      headers: this.authHeaders(options)
-    }).json();
-  }
-  async deleteAnnotation(resourceId, annotationId, options) {
-    await this.http.delete(`${this.baseUrl}/resources/${resourceId}/annotations/${annotationId}`, {
-      headers: this.authHeaders(options)
-    });
+  async markAnnotation(id, data, _options) {
+    return busRequest(
+      this.actor,
+      "mark:create-request",
+      { resourceId: id, request: data },
+      "mark:create-ok",
+      "mark:create-failed"
+    );
   }
-  async bindAnnotation(resourceId, annotationId, data, options) {
-    return this.http.post(`${this.baseUrl}/resources/${resourceId}/annotations/${annotationId}/bind`, {
-      json: { resourceId, ...data },
-      headers: this.authHeaders(options)
-    }).json();
+  async getAnnotation(id, _options) {
+    return busRequest(this.actor, "browse:annotation-requested", { annotationId: id }, "browse:annotation-result", "browse:annotation-failed");
   }
-  async getAnnotationHistory(resourceId, annotationId, options) {
-    return this.http.get(`${this.baseUrl}/resources/${resourceId}/annotations/${annotationId}/history`, {
-      headers: this.authHeaders(options)
-    }).json();
+  async browseAnnotation(resourceId, annotationId, _options) {
+    return busRequest(this.actor, "browse:annotation-requested", { resourceId, annotationId }, "browse:annotation-result", "browse:annotation-failed");
   }
-  async annotateReferences(resourceId, data, options) {
-    return this.http.post(`${this.baseUrl}/resources/${resourceId}/annotate-references`, {
-      json: data,
-      headers: this.authHeaders(options)
-    }).json();
+  async browseAnnotations(id, _motivation, _options) {
+    return busRequest(this.actor, "browse:annotations-requested", { resourceId: id }, "browse:annotations-result", "browse:annotations-failed");
   }
-  async annotateHighlights(resourceId, data, options) {
-    return this.http.post(`${this.baseUrl}/resources/${resourceId}/annotate-highlights`, {
-      json: data,
-      headers: this.authHeaders(options)
-    }).json();
+  async deleteAnnotation(resourceId, annotationId, _options) {
+    await this.actor.emit("mark:delete", { annotationId, resourceId });
   }
-  async annotateAssessments(resourceId, data, options) {
-    return this.http.post(`${this.baseUrl}/resources/${resourceId}/annotate-assessments`, {
-      json: data,
-      headers: this.authHeaders(options)
-    }).json();
+  async bindAnnotation(resourceId, annotationId, data, _options) {
+    const correlationId = crypto.randomUUID();
+    await this.actor.emit("bind:update-body", { correlationId, annotationId, resourceId, operations: data.operations });
+    return { correlationId };
   }
-  async annotateComments(resourceId, data, options) {
-    return this.http.post(`${this.baseUrl}/resources/${resourceId}/annotate-comments`, {
-      json: data,
-      headers: this.authHeaders(options)
-    }).json();
+  async getAnnotationHistory(resourceId, annotationId, _options) {
+    return busRequest(this.actor, "browse:annotation-history-requested", { resourceId, annotationId }, "browse:annotation-history-result", "browse:annotation-history-failed");
   }
-  async annotateTags(resourceId, data, options) {
-    return this.http.post(`${this.baseUrl}/resources/${resourceId}/annotate-tags`, {
-      json: data,
-      headers: this.authHeaders(options)
-    }).json();
-  }
-  async yieldResourceFromAnnotation(resourceId, annotationId, data, options) {
-    return this.http.post(`${this.baseUrl}/resources/${resourceId}/annotations/${annotationId}/yield-resource`, {
-      json: data,
-      headers: this.authHeaders(options)
-    }).json();
-  }
-  async gatherAnnotationContext(resourceId, annotationId, data, options) {
-    return this.http.post(`${this.baseUrl}/resources/${resourceId}/annotations/${annotationId}/gather`, {
-      json: data,
-      headers: this.authHeaders(options)
-    }).json();
-  }
-  async matchSearch(resourceId, data, options) {
-    return this.http.post(`${this.baseUrl}/resources/${resourceId}/match-search`, {
-      json: { resourceId, ...data },
-      headers: this.authHeaders(options)
-    }).json();
+  async annotateReferences(resourceId, data, _options) {
+    const { jobId } = await busRequest(
+      this.actor,
+      "job:create",
+      { jobType: "reference-annotation", resourceId, params: data },
+      "job:created",
+      "job:create-failed"
+    );
+    return { correlationId: crypto.randomUUID(), jobId };
+  }
+  async annotateHighlights(resourceId, data, _options) {
+    const { jobId } = await busRequest(
+      this.actor,
+      "job:create",
+      { jobType: "highlight-annotation", resourceId, params: data },
+      "job:created",
+      "job:create-failed"
+    );
+    return { correlationId: crypto.randomUUID(), jobId };
+  }
+  async annotateAssessments(resourceId, data, _options) {
+    const { jobId } = await busRequest(
+      this.actor,
+      "job:create",
+      { jobType: "assessment-annotation", resourceId, params: data },
+      "job:created",
+      "job:create-failed"
+    );
+    return { correlationId: crypto.randomUUID(), jobId };
+  }
+  async annotateComments(resourceId, data, _options) {
+    const { jobId } = await busRequest(
+      this.actor,
+      "job:create",
+      { jobType: "comment-annotation", resourceId, params: data },
+      "job:created",
+      "job:create-failed"
+    );
+    return { correlationId: crypto.randomUUID(), jobId };
+  }
+  async annotateTags(resourceId, data, _options) {
+    const { jobId } = await busRequest(
+      this.actor,
+      "job:create",
+      { jobType: "tag-annotation", resourceId, params: data },
+      "job:created",
+      "job:create-failed"
+    );
+    return { correlationId: crypto.randomUUID(), jobId };
+  }
+  async yieldResourceFromAnnotation(resourceId, annotationId, data, _options) {
+    const { jobId } = await busRequest(
+      this.actor,
+      "job:create",
+      { jobType: "generation", resourceId, params: { referenceId: annotationId, ...data } },
+      "job:created",
+      "job:create-failed"
+    );
+    return { correlationId: crypto.randomUUID(), jobId };
+  }
+  async gatherAnnotationContext(resourceId, annotationId, data, _options) {
+    await this.actor.emit("gather:requested", {
+      correlationId: data.correlationId,
+      annotationId,
+      resourceId,
+      contextWindow: data.contextWindow ?? 2e3
+    });
+    return { correlationId: data.correlationId };
+  }
+  async matchSearch(resourceId, data, _options) {
+    await this.actor.emit("match:search-requested", {
+      correlationId: data.correlationId,
+      resourceId,
+      referenceId: data.referenceId,
+      context: data.context,
+      limit: data.limit ?? 10,
+      useSemanticScoring: data.useSemanticScoring ?? true
+    });
+    return { correlationId: data.correlationId };
   }
   // ============================================================================
   // ENTITY TYPES
   // ============================================================================
-  async addEntityType(type, options) {
-    await this.http.post(`${this.baseUrl}/api/entity-types`, {
-      json: { tag: type },
-      headers: this.authHeaders(options)
-    });
+  async addEntityType(type, _options) {
+    await this.actor.emit("mark:add-entity-type", { tag: type });
   }
-  async addEntityTypesBulk(types, options) {
-    await this.http.post(`${this.baseUrl}/api/entity-types/bulk`, {
-      json: { tags: types },
-      headers: this.authHeaders(options)
-    });
+  async addEntityTypesBulk(types, _options) {
+    for (const tag of types) {
+      await this.actor.emit("mark:add-entity-type", { tag });
+    }
   }
-  async listEntityTypes(options) {
-    return this.http.get(`${this.baseUrl}/api/entity-types`, {
-      headers: this.authHeaders(options)
-    }).json();
+  async listEntityTypes(_options) {
+    return busRequest(this.actor, "browse:entity-types-requested", {}, "browse:entity-types-result", "browse:entity-types-failed");
   }
   // ============================================================================
   // PARTICIPANTS
   // ============================================================================
-  async beckonAttention(participantId, data, options) {
-    return this.http.post(`${this.baseUrl}/api/participants/${participantId}/attention`, {
-      json: data,
-      headers: this.authHeaders(options)
-    }).json();
+  async beckonAttention(_participantId, data, _options) {
+    await this.actor.emit("beckon:focus", data);
+    return {};
   }
   // ============================================================================
   // ADMIN
@@ -1642,58 +1998,1693 @@ var SemiontApiClient = class {
   // ============================================================================
   // JOB STATUS
   // ============================================================================
-  async getJobStatus(id, options) {
-    return this.http.get(`${this.baseUrl}/api/jobs/${id}`, {
+  async getJobStatus(id, _options) {
+    return busRequest(this.actor, "job:status-requested", { jobId: id }, "job:status-result", "job:status-failed");
+  }
+  /**
+   * Poll a job until it completes or fails
+   * @param id - The job ID to poll
+   * @param options - Polling options
+   * @returns The final job status
+   */
+  async pollJobUntilComplete(id, options) {
+    const interval = options?.interval ?? 1e3;
+    const timeout7 = options?.timeout ?? 6e4;
+    const startTime = Date.now();
+    while (true) {
+      const status = await this.getJobStatus(id, { auth: options?.auth });
+      if (options?.onProgress) {
+        options.onProgress(status);
+      }
+      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`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+  }
+  // ============================================================================
+  // SYSTEM STATUS
+  // ============================================================================
+  async healthCheck(options) {
+    return this.http.get(`${this.baseUrl}/api/health`, {
       headers: this.authHeaders(options)
     }).json();
   }
+  async getStatus(options) {
+    return this.http.get(`${this.baseUrl}/api/status`, {
+      headers: this.authHeaders(options)
+    }).json();
+  }
+  async browseFiles(dirPath, sort, _options) {
+    return busRequest(
+      this.actor,
+      "browse:directory-requested",
+      { path: dirPath ?? ".", sort: sort ?? "name" },
+      "browse:directory-result",
+      "browse:directory-failed"
+    );
+  }
+};
+
+// src/session/storage.ts
+var SESSION_PREFIX = "semiont.session.";
+var STORAGE_KEY = "semiont.knowledgeBases";
+var ACTIVE_KEY = "semiont.activeKnowledgeBaseId";
+var REFRESH_BEFORE_EXP_MS = 5 * 60 * 1e3;
+function sessionKey(kbId) {
+  return `${SESSION_PREFIX}${kbId}`;
+}
+function getStoredSession(storage, kbId) {
+  const raw = storage.get(sessionKey(kbId));
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.access === "string" && typeof parsed.refresh === "string") {
+      return { access: parsed.access, refresh: parsed.refresh };
+    }
+  } catch {
+  }
+  return null;
+}
+function setStoredSession(storage, kbId, session) {
+  storage.set(sessionKey(kbId), JSON.stringify(session));
+}
+function clearStoredSession(storage, kbId) {
+  storage.delete(sessionKey(kbId));
+}
+function parseJwtExpiry(token) {
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3 || !parts[1]) return null;
+    const payload = JSON.parse(atob(parts[1]));
+    if (!payload.exp) return null;
+    return new Date(payload.exp * 1e3);
+  } catch {
+    return null;
+  }
+}
+function isJwtExpired(token) {
+  const expiry = parseJwtExpiry(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 loadKnowledgeBases(storage) {
+  try {
+    const raw = storage.get(STORAGE_KEY);
+    if (!raw) return [];
+    const entries = JSON.parse(raw);
+    return entries.map(migrateLegacyEntry);
+  } catch {
+    return [];
+  }
+}
+function saveKnowledgeBases(storage, knowledgeBases) {
+  storage.set(STORAGE_KEY, JSON.stringify(knowledgeBases));
+}
+function defaultProtocol(host) {
+  return host === "localhost" || host === "127.0.0.1" ? "http" : "https";
+}
+var HOSTNAME_RE = /^(([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)*[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?|localhost|\d{1,3}(\.\d{1,3}){3})$/;
+function isValidHostname(host) {
+  return HOSTNAME_RE.test(host);
+}
+function kbBackendUrl(kb) {
+  if (!isValidHostname(kb.host)) {
+    throw new Error(`Invalid KB hostname: "${kb.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}`;
+}
+function generateKbId() {
+  return crypto.randomUUID();
+}
+
+// src/session/errors.ts
+var SemiontError = class extends Error {
+  code;
+  kbId;
+  constructor(code, message, kbId = null) {
+    super(message);
+    this.name = "SemiontError";
+    this.code = code;
+    this.kbId = kbId;
+  }
+};
+
+// src/session/semiont-session.ts
+var SemiontSession = class {
+  kb;
+  client;
+  token$;
+  user$;
+  streamState$;
+  /** Resolves after the initial validation round-trip completes (success or failure). */
+  ready;
+  storage;
+  doRefresh;
+  doValidate;
+  onAuthFailed;
+  onError;
+  refreshTimer = null;
+  unsubscribeStorage = null;
+  disposed = false;
+  constructor(config) {
+    this.kb = config.kb;
+    this.storage = config.storage;
+    this.doRefresh = config.refresh;
+    this.doValidate = config.validate;
+    this.onAuthFailed = config.onAuthFailed ?? (() => {
+    });
+    this.onError = config.onError ?? (() => {
+    });
+    const stored = getStoredSession(this.storage, this.kb.id);
+    const initialToken = stored && !isJwtExpired(stored.access) ? accessToken(stored.access) : null;
+    this.token$ = new BehaviorSubject(initialToken);
+    this.user$ = new BehaviorSubject(null);
+    this.client = new SemiontApiClient({
+      baseUrl: baseUrl(kbBackendUrl(this.kb)),
+      token$: this.token$,
+      tokenRefresher: () => this.refresh().then((t) => t ?? null)
+    });
+    this.streamState$ = this.client.actor.state$;
+    if (initialToken) {
+      this.scheduleProactiveRefresh(initialToken);
+    }
+    this.unsubscribeStorage = this.storage.subscribe?.((key, newValue) => {
+      this.handleStorageChange(key, newValue);
+    }) ?? null;
+    this.ready = this.validate(stored);
+  }
+  /**
+   * Run the initial mount-time validation. If a stored access token is
+   * present and unexpired, call the configured `validate` with it to
+   * confirm it still works and populate `user$`. If expired, try
+   * refresh first. On 401 from validate, try refresh once. Surfaces
+   * auth-failed on terminal failure.
+   *
+   * When no `validate` callback is provided (service principals), this
+   * still runs through the refresh-if-expired step so the stored
+   * token is current — it just skips the user-validation round trip.
+   */
+  async validate(stored) {
+    if (!stored) return;
+    const startToken = isJwtExpired(stored.access) ? await this.doRefresh() : stored.access;
+    if (!startToken) {
+      if (isJwtExpired(stored.access)) {
+        clearStoredSession(this.storage, this.kb.id);
+      }
+      return;
+    }
+    if (startToken !== stored.access) {
+      this.token$.next(accessToken(startToken));
+      this.scheduleProactiveRefresh(startToken);
+    }
+    if (!this.doValidate) return;
+    const attempt = async (token) => {
+      if (this.disposed) return;
+      try {
+        const data = await this.doValidate(accessToken(token));
+        if (this.disposed) return;
+        this.user$.next(data);
+      } catch (err) {
+        if (this.disposed) return;
+        if (err instanceof APIError && err.status === 401) {
+          const refreshed = await this.doRefresh();
+          if (this.disposed) return;
+          if (refreshed) {
+            this.token$.next(accessToken(refreshed));
+            this.scheduleProactiveRefresh(refreshed);
+            await attempt(refreshed);
+            return;
+          }
+          clearStoredSession(this.storage, this.kb.id);
+          this.token$.next(null);
+          this.onAuthFailed("Your session has expired. Please sign in again.");
+        } else {
+          this.onError(
+            new SemiontError(
+              "session.auth-failed",
+              err instanceof Error ? err.message : String(err),
+              this.kb.id
+            )
+          );
+        }
+      }
+    };
+    await attempt(startToken);
+  }
+  /**
+   * Refresh the access token via the configured `refresh` callback.
+   * On success, pushes the new token into `token$` and schedules the
+   * next proactive refresh. On failure, clears persisted state and
+   * fires `onAuthFailed` — the frontend's wiring of that callback is
+   * what surfaces the session-expired modal.
+   */
+  async refresh() {
+    if (this.disposed) return null;
+    const newAccess = await this.doRefresh();
+    if (this.disposed) return null;
+    if (newAccess) {
+      const tok = accessToken(newAccess);
+      this.token$.next(tok);
+      this.scheduleProactiveRefresh(newAccess);
+      return tok;
+    }
+    this.token$.next(null);
+    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)
+    );
+    return null;
+  }
+  scheduleProactiveRefresh(token) {
+    this.clearRefreshTimer();
+    const expiresAt = parseJwtExpiry(token);
+    if (!expiresAt) return;
+    const refreshAt = expiresAt.getTime() - REFRESH_BEFORE_EXP_MS;
+    const delay = Math.max(0, refreshAt - Date.now());
+    this.refreshTimer = setTimeout(() => {
+      this.refreshTimer = null;
+      if (!this.disposed) void this.refresh();
+    }, delay);
+  }
+  clearRefreshTimer() {
+    if (this.refreshTimer) {
+      clearTimeout(this.refreshTimer);
+      this.refreshTimer = null;
+    }
+  }
+  /**
+   * Cross-context sync: another tab/process refreshed or signed out this
+   * KB. Mirror the change into our in-memory state.
+   */
+  handleStorageChange(key, newValue) {
+    if (this.disposed) return;
+    if (key !== sessionKey(this.kb.id)) return;
+    if (!newValue) {
+      this.token$.next(null);
+      this.user$.next(null);
+      this.clearRefreshTimer();
+      return;
+    }
+    try {
+      const parsed = JSON.parse(newValue);
+      if (typeof parsed.access === "string") {
+        this.token$.next(accessToken(parsed.access));
+        this.scheduleProactiveRefresh(parsed.access);
+      }
+    } catch {
+    }
+  }
+  get expiresAt() {
+    const token = this.token$.getValue();
+    return token ? parseJwtExpiry(token) : null;
+  }
+  async dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.clearRefreshTimer();
+    if (this.unsubscribeStorage) {
+      this.unsubscribeStorage();
+      this.unsubscribeStorage = null;
+    }
+    this.client.dispose();
+    this.token$.complete();
+    this.user$.complete();
+  }
+};
+
+// 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 {
+  sessionExpiredAt$;
+  sessionExpiredMessage$;
+  permissionDeniedAt$;
+  permissionDeniedMessage$;
+  constructor() {
+    this.sessionExpiredAt$ = new BehaviorSubject(null);
+    this.sessionExpiredMessage$ = new BehaviorSubject(null);
+    this.permissionDeniedAt$ = new BehaviorSubject(null);
+    this.permissionDeniedMessage$ = new BehaviorSubject(null);
+  }
+  notifySessionExpired(message) {
+    this.sessionExpiredMessage$.next(
+      message ?? "Your session has expired. Please sign in again."
+    );
+    this.sessionExpiredAt$.next(Date.now());
+  }
+  notifyPermissionDenied(message) {
+    this.permissionDeniedMessage$.next(
+      message ?? "You do not have permission to perform this action."
+    );
+    this.permissionDeniedAt$.next(Date.now());
+  }
+  acknowledgeSessionExpired() {
+    this.sessionExpiredAt$.next(null);
+    this.sessionExpiredMessage$.next(null);
+  }
+  acknowledgePermissionDenied() {
+    this.permissionDeniedAt$.next(null);
+    this.permissionDeniedMessage$.next(null);
+  }
+  dispose() {
+    this.sessionExpiredAt$.complete();
+    this.sessionExpiredMessage$.complete();
+    this.permissionDeniedAt$.complete();
+    this.permissionDeniedMessage$.complete();
+  }
+};
+
+// src/session/semiont-browser.ts
+var OPEN_RESOURCES_KEY = "openDocuments";
+function sortOpenResources(resources) {
+  return [...resources].sort((a, b) => {
+    if (a.order !== void 0 && b.order !== void 0) return a.order - b.order;
+    return a.openedAt - b.openedAt;
+  });
+}
+function loadOpenResources(storage) {
+  try {
+    const stored = storage.get(OPEN_RESOURCES_KEY);
+    if (stored) return sortOpenResources(JSON.parse(stored));
+  } catch {
+  }
+  return [];
+}
+var SemiontBrowser = class {
+  kbs$;
+  activeKbId$;
+  activeSession$;
+  /**
+   * Modal signals (session-expired / permission-denied) for the
+   * currently-active session. Parallels `activeSession$` — always
+   * non-null when `activeSession$` is non-null, always null when it
+   * is. Extracted from the session itself so headless sessions
+   * (workers, CLIs, tests) don't carry dead modal observables.
+   * See [FrontendSessionSignals](./frontend-session-signals.ts).
+   */
+  activeSignals$;
+  /**
+   * True while a session is actively being constructed (setActiveKb /
+   * signIn in flight, awaiting `session.ready`). Distinguishes the
+   * "session about to arrive" intermediate state from "session
+   * intentionally null" (after signOut, or when the active KB has no
+   * stored credentials). UIs that want a loading spinner should gate
+   * on this; otherwise they get stuck spinning after every signOut.
+   */
+  sessionActivating$;
+  openResources$;
+  error$;
+  identityToken$;
+  storage;
+  /**
+   * App-scoped EventBus. Hosts UI-shell events that must work regardless
+   * of whether a KB session is active: panel toggles, sidebar state,
+   * tab reorders, routing, settings, etc. Disjoint from the per-session
+   * bus inside `SemiontApiClient`, which carries KB-content events
+   * (mark:*, beckon:*, gather:*, match:*, bind:*, yield:*, browse:click).
+   */
+  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;
+    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;
+    this.kbs$ = new BehaviorSubject(kbs);
+    this.activeKbId$ = new BehaviorSubject(initialActive);
+    this.activeSession$ = new BehaviorSubject(null);
+    this.activeSignals$ = new BehaviorSubject(null);
+    this.sessionActivating$ = new BehaviorSubject(false);
+    this.openResources$ = new BehaviorSubject(loadOpenResources(this.storage));
+    this.error$ = new Subject();
+    this.identityToken$ = new BehaviorSubject(null);
+    this.kbs$.subscribe((next) => saveKnowledgeBases(this.storage, next));
+    this.activeKbId$.subscribe((id) => {
+      if (id) this.storage.set(ACTIVE_KEY, id);
+      else this.storage.delete(ACTIVE_KEY);
+    });
+    this.openResources$.subscribe((list) => {
+      this.storage.set(OPEN_RESOURCES_KEY, JSON.stringify(list));
+    });
+    this.unsubscribeStorage = this.storage.subscribe?.((key, newValue) => {
+      if (key !== OPEN_RESOURCES_KEY || !newValue) return;
+      try {
+        this.openResources$.next(sortOpenResources(JSON.parse(newValue)));
+      } 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);
+    }
+  }
+  // ── App-scoped event bus ──────────────────────────────────────────────
+  /** Emit an event on the browser's app-scoped bus. */
+  emit(channel, payload) {
+    if (this.disposed) return;
+    this.eventBus.get(channel).next(payload);
+  }
+  /** Subscribe to an event; returns unsubscribe. */
+  on(channel, handler) {
+    const sub = this.eventBus.get(channel).subscribe(handler);
+    return () => sub.unsubscribe();
+  }
+  /** Read-only observable for an app-scoped channel. */
+  stream(channel) {
+    return this.eventBus.get(channel).asObservable();
+  }
+  // ── 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.
+   */
+  setIdentityToken(token) {
+    if (this.disposed) return;
+    this.identityToken$.next(token);
+  }
+  // ── KB list management ────────────────────────────────────────────────
+  addKb(input, access, refresh) {
+    const kb = { id: generateKbId(), ...input };
+    setStoredSession(this.storage, kb.id, { access, refresh });
+    this.kbs$.next([...this.kbs$.getValue(), kb]);
+    void this.setActiveKb(kb.id);
+    return kb;
+  }
+  removeKb(id) {
+    clearStoredSession(this.storage, id);
+    const next = this.kbs$.getValue().filter((kb) => kb.id !== id);
+    this.kbs$.next(next);
+    if (this.activeKbId$.getValue() === id) {
+      void this.setActiveKb(next[0]?.id ?? null);
+    }
+  }
+  updateKb(id, updates) {
+    this.kbs$.next(
+      this.kbs$.getValue().map((kb) => kb.id === id ? { ...kb, ...updates } : kb)
+    );
+  }
+  /**
+   * Read the locally-stored credential status for a KB. Pure / synchronous —
+   * does not subscribe to context changes. Used by KB-list UI to color status
+   * dots without requiring re-renders on every tick.
+   */
+  getKbSessionStatus(kbId) {
+    const stored = getStoredSession(this.storage, kbId);
+    if (!stored) return "signed-out";
+    return isJwtExpired(stored.access) ? "expired" : "authenticated";
+  }
+  /**
+   * Switch the active KB. Follows the D2 disposal contract:
+   *   1. Synchronously announce the new id on `activeKbId$` and null out
+   *      `activeSession$` so views see a safe empty state first.
+   *   2. Serialize overlapping calls — if an activation is in flight, wait
+   *      for it before proceeding.
+   *   3. Dispose whatever session is currently live.
+   *   4. Construct the next session and await `session.ready`.
+   *   5. Before emitting, re-check `activeKbId$` — if a newer call superseded
+   *      us while we waited, dispose our session and skip the emit.
+   *   6. Emit the new session.
+   */
+  async setActiveKb(id) {
+    if (this.disposed) return;
+    const prevId = this.activeKbId$.getValue();
+    const prevSession = this.activeSession$.getValue();
+    if (id === prevId && prevSession) return;
+    if (prevId !== id) this.activeKbId$.next(id);
+    if (prevSession) {
+      this.activeSession$.next(null);
+      this.activeSignals$.next(null);
+    }
+    while (this.activating) {
+      const current = this.activating;
+      await current;
+      if (this.disposed) return;
+      if (this.activeKbId$.getValue() !== id) return;
+    }
+    const activation = (async () => {
+      const toDispose = this.activeSession$.getValue();
+      const signalsToDispose = this.activeSignals$.getValue();
+      if (toDispose) {
+        this.activeSession$.next(null);
+        this.activeSignals$.next(null);
+        await toDispose.dispose();
+        signalsToDispose?.dispose();
+      }
+      if (!id) return;
+      const kb = this.kbs$.getValue().find((k) => k.id === id);
+      if (!kb) return;
+      const signals = new FrontendSessionSignals();
+      const session = new SemiontSession({
+        kb,
+        storage: this.storage,
+        refresh: () => this.performRefresh(kb),
+        validate: (token) => this.performValidate(kb, token),
+        onAuthFailed: (msg) => signals.notifySessionExpired(msg),
+        onError: (err) => this.error$.next(err)
+      });
+      try {
+        await session.ready;
+      } catch (err) {
+        this.error$.next(
+          new SemiontError(
+            "session.construct-failed",
+            err instanceof Error ? err.message : String(err),
+            id
+          )
+        );
+        await session.dispose();
+        signals.dispose();
+        return;
+      }
+      if (this.disposed || this.activeKbId$.getValue() !== id) {
+        await session.dispose();
+        signals.dispose();
+        return;
+      }
+      this.activeSession$.next(session);
+      this.activeSignals$.next(signals);
+    })();
+    this.activating = activation;
+    this.sessionActivating$.next(true);
+    try {
+      await activation;
+    } finally {
+      if (this.activating === activation) {
+        this.activating = null;
+        this.sessionActivating$.next(false);
+      }
+    }
+  }
+  /**
+   * Sign in to an existing KB: store the tokens and (re)activate the
+   * session. If the KB is already active, the current session is disposed
+   * and replaced so the new tokens take effect.
+   */
+  async signIn(id, access, refresh) {
+    if (this.disposed) return;
+    setStoredSession(this.storage, id, { access, refresh });
+    if (this.activeKbId$.getValue() === id) {
+      const prevSession = this.activeSession$.getValue();
+      const prevSignals = this.activeSignals$.getValue();
+      this.activeSession$.next(null);
+      this.activeSignals$.next(null);
+      if (prevSession) await prevSession.dispose();
+      prevSignals?.dispose();
+      await this.setActiveKb(id);
+      return;
+    }
+    await this.setActiveKb(id);
+  }
+  /**
+   * Sign out of a KB: clear stored tokens. If the KB is active, dispose
+   * its session + signals and emit null for both.
+   */
+  async signOut(id) {
+    if (this.disposed) return;
+    clearStoredSession(this.storage, id);
+    this.kbs$.next([...this.kbs$.getValue()]);
+    if (this.activeKbId$.getValue() === id) {
+      const prevSession = this.activeSession$.getValue();
+      const prevSignals = this.activeSignals$.getValue();
+      this.activeSession$.next(null);
+      this.activeSignals$.next(null);
+      if (prevSession) await prevSession.dispose();
+      prevSignals?.dispose();
+    }
+  }
+  // ── Open resources ────────────────────────────────────────────────────
+  addOpenResource(id, name, mediaType, storageUri) {
+    const existing = this.openResources$.getValue();
+    const idx = existing.findIndex((r) => r.id === id);
+    if (idx >= 0) {
+      const prev = existing[idx];
+      const updated = {
+        ...prev,
+        name,
+        ...mediaType !== void 0 ? { mediaType } : {},
+        ...storageUri !== void 0 ? { storageUri } : {}
+      };
+      const next = [...existing];
+      next[idx] = updated;
+      this.openResources$.next(next);
+      return;
+    }
+    const resource = {
+      id,
+      name,
+      openedAt: Date.now(),
+      order: existing.length,
+      ...mediaType !== void 0 ? { mediaType } : {},
+      ...storageUri !== void 0 ? { storageUri } : {}
+    };
+    this.openResources$.next([...existing, resource]);
+  }
+  removeOpenResource(id) {
+    this.openResources$.next(this.openResources$.getValue().filter((r) => r.id !== id));
+  }
+  updateOpenResourceName(id, name) {
+    this.openResources$.next(
+      this.openResources$.getValue().map((r) => r.id === id ? { ...r, name } : r)
+    );
+  }
+  reorderOpenResources(oldIndex, newIndex) {
+    const list = [...this.openResources$.getValue()];
+    if (oldIndex < 0 || oldIndex >= list.length || newIndex < 0 || newIndex >= list.length) {
+      return;
+    }
+    const [moved] = list.splice(oldIndex, 1);
+    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 `SemiontApiClient` 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 throwaway = new SemiontApiClient({
+        baseUrl: baseUrl(kbBackendUrl(kb))
+      });
+      try {
+        const response = await throwaway.refreshToken(refreshToken(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);
+    }
+  }
   /**
-   * Poll a job until it completes or fails
-   * @param id - The job ID to poll
-   * @param options - Polling options
-   * @returns The final job status
+   * Validate an access token by calling `getMe` on a throwaway
+   * client. The session uses this once at startup to populate
+   * `user$`; 401 triggers a refresh-then-retry inside the session.
    */
-  async pollJobUntilComplete(id, options) {
-    const interval = options?.interval ?? 1e3;
-    const timeout = options?.timeout ?? 6e4;
-    const startTime = Date.now();
-    while (true) {
-      const status = await this.getJobStatus(id, { auth: options?.auth });
-      if (options?.onProgress) {
-        options.onProgress(status);
-      }
-      if (status.status === "complete" || status.status === "failed" || status.status === "cancelled") {
-        return status;
-      }
-      if (Date.now() - startTime > timeout) {
-        throw new Error(`Job polling timeout after ${timeout}ms`);
-      }
-      await new Promise((resolve) => setTimeout(resolve, interval));
+  async performValidate(kb, token) {
+    const throwaway = new SemiontApiClient({
+      baseUrl: baseUrl(kbBackendUrl(kb))
+    });
+    try {
+      const data = await throwaway.getMe({ auth: token });
+      return data;
+    } finally {
+      throwaway.dispose();
     }
   }
-  // ============================================================================
-  // SYSTEM STATUS
-  // ============================================================================
-  async healthCheck(options) {
-    return this.http.get(`${this.baseUrl}/api/health`, {
-      headers: this.authHeaders(options)
-    }).json();
+  // ── Lifecycle ─────────────────────────────────────────────────────────
+  async dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.unregisterNotify?.();
+    this.unregisterNotify = null;
+    if (this.unsubscribeStorage) {
+      this.unsubscribeStorage();
+      this.unsubscribeStorage = null;
+    }
+    const prevSession = this.activeSession$.getValue();
+    const prevSignals = this.activeSignals$.getValue();
+    this.activeSession$.next(null);
+    this.activeSignals$.next(null);
+    if (prevSession) await prevSession.dispose();
+    prevSignals?.dispose();
+    this.kbs$.complete();
+    this.activeKbId$.complete();
+    this.activeSession$.complete();
+    this.activeSignals$.complete();
+    this.openResources$.complete();
+    this.error$.complete();
+    this.identityToken$.complete();
+    this.eventBus.destroy();
   }
-  async getStatus(options) {
-    return this.http.get(`${this.baseUrl}/api/status`, {
-      headers: this.authHeaders(options)
-    }).json();
+};
+
+// src/session/registry.ts
+var instance = null;
+function getBrowser(options) {
+  if (!instance) {
+    instance = new SemiontBrowser({ storage: options.storage });
   }
-  async browseFiles(dirPath, sort, options) {
-    const searchParams = new URLSearchParams();
-    if (dirPath) searchParams.append("path", dirPath);
-    if (sort) searchParams.append("sort", sort);
-    return this.http.get(`${this.baseUrl}/api/browse/files`, {
-      searchParams,
-      headers: this.authHeaders(options)
-    }).json();
+  return instance;
+}
+
+// src/session/session-storage.ts
+var InMemorySessionStorage = class {
+  map = /* @__PURE__ */ new Map();
+  get(key) {
+    return this.map.has(key) ? this.map.get(key) : null;
+  }
+  set(key, value) {
+    this.map.set(key, value);
   }
+  delete(key) {
+    this.map.delete(key);
+  }
+};
+function createDisposer() {
+  const sub = new Subscription();
+  return {
+    add: (item) => sub.add(typeof item === "function" ? item : () => item.dispose()),
+    dispose: () => sub.unsubscribe()
+  };
+}
+function createSearchPipeline(fetch2, options = {}) {
+  const debounceMs = options.debounceMs ?? 250;
+  const initial = options.initialQuery ?? "";
+  const input$ = new Subject();
+  const query$ = input$.pipe(startWith(initial));
+  const state$ = input$.pipe(
+    startWith(initial),
+    debounceTime(debounceMs),
+    distinctUntilChanged$1(),
+    switchMap((q) => {
+      const trimmed = q.trim();
+      if (!trimmed) {
+        return of({ results: [], isSearching: false });
+      }
+      return fetch2(trimmed).pipe(
+        map((results) => ({
+          results: results ?? [],
+          isSearching: results === void 0
+        })),
+        startWith({ results: [], isSearching: true })
+      );
+    })
+  );
+  return {
+    query$,
+    state$,
+    setQuery: (value) => input$.next(value),
+    dispose: () => input$.complete()
+  };
+}
+function createBeckonVM(client) {
+  const subs = [];
+  const hovered$ = new BehaviorSubject(null);
+  subs.push(client.stream("beckon:hover").subscribe(({ annotationId }) => {
+    hovered$.next(annotationId);
+    if (annotationId) {
+      client.emit("beckon:sparkle", { annotationId });
+    }
+  }));
+  subs.push(client.stream("browse:click").subscribe(({ annotationId }) => {
+    client.emit("beckon:focus", { annotationId });
+  }));
+  return {
+    hoveredAnnotationId$: hovered$.asObservable(),
+    hover: (annotationId) => client.emit("beckon:hover", { annotationId }),
+    focus: (annotationId) => client.emit("beckon:focus", { annotationId }),
+    sparkle: (annotationId) => client.emit("beckon:sparkle", { annotationId }),
+    dispose() {
+      subs.forEach((s) => s.unsubscribe());
+      hovered$.complete();
+    }
+  };
+}
+var HOVER_DELAY_MS = 150;
+function createHoverHandlers(emit, delayMs) {
+  let currentHover = null;
+  let timer = null;
+  const cancelTimer = () => {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  };
+  const handleMouseEnter = (annotationId) => {
+    if (currentHover === annotationId) return;
+    cancelTimer();
+    timer = setTimeout(() => {
+      timer = null;
+      currentHover = annotationId;
+      emit(annotationId);
+    }, delayMs);
+  };
+  const handleMouseLeave = () => {
+    cancelTimer();
+    if (currentHover !== null) {
+      currentHover = null;
+      emit(null);
+    }
+  };
+  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) {
+  const subs = [];
+  const context$ = new BehaviorSubject(null);
+  const loading$ = new BehaviorSubject(false);
+  const error$ = new BehaviorSubject(null);
+  const annotationId$ = new BehaviorSubject(null);
+  subs.push(client.stream("gather:requested").subscribe((event) => {
+    loading$.next(true);
+    error$.next(null);
+    context$.next(null);
+    annotationId$.next(annotationId(event.annotationId));
+    const gatherSub = client.gather.annotation(
+      annotationId(event.annotationId),
+      resourceId,
+      { contextWindow: event.options?.contextWindow ?? 2e3 }
+    ).pipe(
+      timeout(6e4)
+    ).subscribe({
+      next: (progress) => {
+        if ("response" in progress && progress.response) {
+          context$.next(
+            progress.response.context ?? null
+          );
+          loading$.next(false);
+        }
+      },
+      error: (err) => {
+        error$.next(err instanceof Error ? err : new Error(String(err)));
+        loading$.next(false);
+      },
+      complete: () => {
+        loading$.next(false);
+      }
+    });
+    subs.push(gatherSub);
+  }));
+  return {
+    context$: context$.asObservable(),
+    loading$: loading$.asObservable(),
+    error$: error$.asObservable(),
+    annotationId$: annotationId$.asObservable(),
+    dispose() {
+      subs.forEach((s) => s.unsubscribe());
+      context$.complete();
+      loading$.complete();
+      error$.complete();
+      annotationId$.complete();
+    }
+  };
+}
+function createMatchVM(client, _resourceId) {
+  const subs = [];
+  subs.push(client.stream("match:search-requested").subscribe((event) => {
+    const searchSub = client.match.search(
+      resourceId(event.resourceId),
+      event.referenceId,
+      event.context,
+      { limit: event.limit, useSemanticScoring: event.useSemanticScoring }
+    ).pipe(
+      timeout(6e4)
+    ).subscribe({
+      next: (result) => client.emit("match:search-results", result),
+      error: (err) => client.emit("match:search-failed", {
+        correlationId: event.correlationId,
+        referenceId: event.referenceId,
+        error: err instanceof Error ? err.message : String(err)
+      })
+    });
+    subs.push(searchSub);
+  }));
+  return {
+    dispose() {
+      subs.forEach((s) => s.unsubscribe());
+    }
+  };
+}
+function createYieldVM(client, resourceId$1, 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),
+      annotationId(referenceId),
+      { ...options, language: options.language || locale }
+    ).pipe(
+      timeout({ each: 3e5 })
+    ).subscribe({
+      next: (chunk) => {
+        progress$.next(chunk);
+        isGenerating$.next(true);
+      },
+      complete: () => {
+        isGenerating$.next(false);
+        if (clearTimer) clearTimeout(clearTimer);
+        clearTimer = setTimeout(() => {
+          progress$.next(null);
+          clearTimer = null;
+        }, 2e3);
+      },
+      error: () => {
+        progress$.next(null);
+        isGenerating$.next(false);
+      }
+    });
+    subs.push(genSub);
+  };
+  return {
+    isGenerating$: isGenerating$.asObservable(),
+    progress$: progress$.asObservable(),
+    generate,
+    dispose() {
+      subs.forEach((s) => s.unsubscribe());
+      if (clearTimer) clearTimeout(clearTimer);
+      isGenerating$.complete();
+      progress$.complete();
+    }
+  };
+}
+function selectionToSelector(selection) {
+  if (selection.svgSelector) return { type: "SvgSelector", value: selection.svgSelector };
+  if (selection.fragmentSelector) {
+    const selectors = [{ type: "FragmentSelector", value: selection.fragmentSelector, ...selection.conformsTo && { conformsTo: selection.conformsTo } }];
+    if (selection.exact) selectors.push({ type: "TextQuoteSelector", exact: selection.exact, ...selection.prefix && { prefix: selection.prefix }, ...selection.suffix && { suffix: selection.suffix } });
+    return selectors;
+  }
+  return { type: "TextQuoteSelector", exact: selection.exact, ...selection.prefix && { prefix: selection.prefix }, ...selection.suffix && { suffix: selection.suffix } };
+}
+function createMarkVM(client, resourceId) {
+  const subs = [];
+  const pendingAnnotation$ = new BehaviorSubject(null);
+  const assistingMotivation$ = new BehaviorSubject(null);
+  const progress$ = new BehaviorSubject(null);
+  let progressDismissTimer = null;
+  const clearProgressTimer = () => {
+    if (progressDismissTimer) {
+      clearTimeout(progressDismissTimer);
+      progressDismissTimer = null;
+    }
+  };
+  const handleAnnotationRequested = (pending) => {
+    pendingAnnotation$.next(pending);
+  };
+  subs.push(client.stream("mark:requested").subscribe(handleAnnotationRequested));
+  subs.push(client.stream("mark:select-comment").subscribe((s) => handleAnnotationRequested({ selector: selectionToSelector(s), motivation: "commenting" })));
+  subs.push(client.stream("mark:select-tag").subscribe((s) => handleAnnotationRequested({ selector: selectionToSelector(s), motivation: "tagging" })));
+  subs.push(client.stream("mark:select-assessment").subscribe((s) => handleAnnotationRequested({ selector: selectionToSelector(s), motivation: "assessing" })));
+  subs.push(client.stream("mark:select-reference").subscribe((s) => handleAnnotationRequested({ selector: selectionToSelector(s), motivation: "linking" })));
+  subs.push(client.stream("mark:cancel-pending").subscribe(() => pendingAnnotation$.next(null)));
+  subs.push(client.stream("mark:create-ok").subscribe(() => pendingAnnotation$.next(null)));
+  subs.push(client.stream("mark:submit").subscribe(async (event) => {
+    try {
+      const result = await client.mark.annotation(resourceId, {
+        motivation: event.motivation,
+        target: { source: resourceId, selector: event.selector },
+        body: event.body
+      });
+      client.emit("mark:create-ok", { annotationId: result.annotationId });
+    } catch (error) {
+      client.emit("mark:create-failed", { message: error instanceof Error ? error.message : String(error) });
+    }
+  }));
+  subs.push(client.stream("mark:delete").subscribe(async (event) => {
+    try {
+      await client.mark.delete(resourceId, event.annotationId);
+      client.emit("mark:delete-ok", { annotationId: event.annotationId });
+    } catch (error) {
+      client.emit("mark:delete-failed", { message: error instanceof Error ? error.message : String(error) });
+    }
+  }));
+  subs.push(client.stream("mark:assist-request").subscribe((event) => {
+    clearProgressTimer();
+    assistingMotivation$.next(event.motivation);
+    progress$.next(null);
+    const assistSub = client.mark.assist(resourceId, event.motivation, event.options).pipe(
+      timeout({ each: 18e4 })
+    ).subscribe({
+      next: (p) => progress$.next(p),
+      complete: () => {
+        assistingMotivation$.next(null);
+        clearProgressTimer();
+        progressDismissTimer = setTimeout(() => {
+          progress$.next(null);
+          progressDismissTimer = null;
+        }, 5e3);
+      },
+      error: () => {
+        clearProgressTimer();
+        assistingMotivation$.next(null);
+        progress$.next(null);
+      }
+    });
+    subs.push(assistSub);
+  }));
+  subs.push(client.stream("mark:progress-dismiss").subscribe(() => {
+    clearProgressTimer();
+    progress$.next(null);
+  }));
+  return {
+    pendingAnnotation$: pendingAnnotation$.asObservable(),
+    assistingMotivation$: assistingMotivation$.asObservable(),
+    progress$: progress$.asObservable(),
+    dispose() {
+      subs.forEach((s) => s.unsubscribe());
+      clearProgressTimer();
+      pendingAnnotation$.complete();
+      assistingMotivation$.complete();
+      progress$.complete();
+    }
+  };
+}
+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.listUsers().then((data) => {
+      users$.next(data.users ?? []);
+      usersLoading$.next(false);
+    }).catch(() => usersLoading$.next(false));
+  };
+  const fetchStats = () => {
+    statsLoading$.next(true);
+    client.getUserStats().then((data) => {
+      stats$.next(data.stats ?? null);
+      statsLoading$.next(false);
+    }).catch(() => statsLoading$.next(false));
+  };
+  fetchUsers();
+  fetchStats();
+  const updateUser = async (id, data) => {
+    await client.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.getOAuthConfig().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.getMe().then((data) => userData$.next(data)).catch(() => {
+  });
+  const acceptTerms = async () => {
+    isProcessing$.next(true);
+    try {
+      await client.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.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.stream("job:queued").subscribe((event) => {
+      const job = {
+        jobId: event.jobId,
+        type: event.jobType,
+        status: "pending",
+        resourceId: event.resourceId ?? "",
+        userId: "",
+        created: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      addOrUpdate(job);
+      jobCreated$.next(job);
+    }),
+    client.stream("job:complete").subscribe((event) => {
+      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.stream("job:fail").subscribe((event) => {
+      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 ?? "Unknown 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();
+    }
+  };
+}
+
+// src/utils/text-encoding.ts
+function extractCharset(mediaType) {
+  const charsetMatch = mediaType.match(/charset=([^\s;]+)/i);
+  return (charsetMatch?.[1] || "utf-8").toLowerCase();
+}
+function decodeWithCharset(buffer, mediaType) {
+  const charset = extractCharset(mediaType);
+  const decoder = new TextDecoder(charset);
+  return decoder.decode(buffer);
+}
 function getBodySource(body) {
   if (Array.isArray(body)) {
     for (const item of body) {
@@ -1847,6 +3838,115 @@ function extractBoundingBox(svg) {
   return null;
 }
 
+// src/view-models/pages/resource-viewer-page-vm.ts
+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.stream("bind:initiate").subscribe((event) => {
+    wizard$.next({
+      open: true,
+      annotationId: event.annotationId,
+      resourceId: event.resourceId,
+      defaultTitle: event.defaultTitle,
+      entityTypes: event.entityTypes
+    });
+    client.emit("gather:requested", {
+      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();
+    }
+  };
+}
+
 // src/utils/fuzzy-anchor.ts
 function normalizeText(text) {
   return text.replace(/\s+/g, " ").replace(/[\u2018\u2019]/g, "'").replace(/[\u201C\u201D]/g, '"').replace(/\u2014/g, "--").replace(/\u2013/g, "-").trim();
@@ -2277,17 +4377,6 @@ function validateAndCorrectOffsets(content, aiStart, aiEnd, exact) {
   };
 }
 
-// src/utils/text-encoding.ts
-function extractCharset(mediaType) {
-  const charsetMatch = mediaType.match(/charset=([^\s;]+)/i);
-  return (charsetMatch?.[1] || "utf-8").toLowerCase();
-}
-function decodeWithCharset(buffer, mediaType) {
-  const charset = extractCharset(mediaType);
-  const decoder = new TextDecoder(charset);
-  return decoder.decode(buffer);
-}
-
 // src/utils/validation.ts
 var JWTTokenSchema = {
   parse(token) {
@@ -2334,16 +4423,128 @@ function isValidEmail(email) {
   return emailRegex.test(email);
 }
 
+// src/view-models/pages/compose-page-vm.ts
+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.getResourceRepresentation(rId, {
+            accept: mediaType,
+            auth
+          });
+          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();
+    }
+  };
+}
+
 // src/mime-utils.ts
 function getExtensionForMimeType(mimeType) {
-  const map3 = {
+  const map15 = {
     "text/plain": "txt",
     "text/markdown": "md",
     "image/png": "png",
     "image/jpeg": "jpg",
     "application/pdf": "pdf"
   };
-  return map3[mimeType] || "dat";
+  return map15[mimeType] || "dat";
 }
 function isImageMimeType(mimeType) {
   return mimeType === "image/png" || mimeType === "image/jpeg";
@@ -2364,6 +4565,6 @@ function getMimeCategory(mimeType) {
   return "unsupported";
 }
 
-export { APIError, AdminNamespace, AuthNamespace, BeckonNamespace, BindNamespace, BrowseNamespace, GatherNamespace, JWTTokenSchema, JobNamespace, LOCALES, MarkNamespace, MatchNamespace, SSEClient, SSE_STREAM_CONNECTED, SemiontApiClient, YieldNamespace, buildContentCache, createCircleSvg, createPolygonSvg, createRectangleSvg, decodeRepresentation, decodeWithCharset, extractBoundingBox, extractCharset, extractContext, findBestTextMatch, findTextWithContext, formatLocaleDisplay, getAllLocaleCodes, getAnnotationExactText, getBodySource, getBodyType, getChecksum, getCommentText, getCreator, getDerivedFrom, getExactText, getExtensionForMimeType, getLanguage, getLocaleEnglishName, getLocaleInfo, getLocaleNativeName, getMimeCategory, getNodeEncoding, getPrimaryMediaType, getPrimaryRepresentation, getPrimarySelector, getResourceEntityTypes, getResourceId, getStorageUri, getTargetSelector, getTargetSource, getTextQuoteSelector, hasTargetSelector, isArchived, isAssessment, isBodyResolved, isComment, isDraft, isHighlight, isImageMimeType, isPdfMimeType, isReference, isResolvedReference, isStubReference, isTag, isTextMimeType, isValidEmail, normalizeCoordinates, normalizeText, parseSvgSelector, scaleSvgToNative, validateAndCorrectOffsets, validateData, verifyPosition };
+export { APIError, AdminNamespace, AuthNamespace, BeckonNamespace, BindNamespace, BrowseNamespace, BusRequestError, COMMON_PANELS, DEGRADED_THRESHOLD_MS, FrontendSessionSignals, GatherNamespace, HOVER_DELAY_MS, InMemorySessionStorage, JWTTokenSchema, JobNamespace, LOCALES, MarkNamespace, MatchNamespace, RESOURCE_PANELS, SemiontApiClient, SemiontBrowser, SemiontError, SemiontSession, YieldNamespace, buildContentCache, busRequest, createActorVM, createAdminSecurityVM, createAdminUsersVM, createBeckonVM, createCache, createCircleSvg, createComposePageVM, createDiscoverVM, createDisposer, createEntityTagsVM, createExchangeVM, createGatherVM, createHoverHandlers, createJobClaimAdapter, createJobQueueVM, createMarkVM, createMatchVM, createPolygonSvg, createRectangleSvg, createResourceLoaderVM, createResourceViewerPageVM, createSearchPipeline, createSessionVM, createShellVM, createSmelterActorVM, createWelcomeVM, createYieldVM, decodeRepresentation, decodeWithCharset, defaultProtocol, extractBoundingBox, extractCharset, extractContext, findBestTextMatch, findTextWithContext, formatLocaleDisplay, getAllLocaleCodes, getAnnotationExactText, getBodySource, getBodyType, getBrowser, getChecksum, getCommentText, getCreator, getDerivedFrom, getExactText, getExtensionForMimeType, getLanguage, getLocaleEnglishName, getLocaleInfo, getLocaleNativeName, getMimeCategory, getNodeEncoding, getPrimaryMediaType, getPrimaryRepresentation, getPrimarySelector, getResourceEntityTypes, getResourceId, getStorageUri, getTargetSelector, getTargetSource, getTextQuoteSelector, hasTargetSelector, isArchived, isAssessment, isBodyResolved, isComment, isDraft, isHighlight, isImageMimeType, isPdfMimeType, isReference, isResolvedReference, isStubReference, isTag, isTextMimeType, isValidEmail, isValidHostname, kbBackendUrl, normalizeCoordinates, normalizeText, notifyPermissionDenied, notifySessionExpired, parseSvgSelector, scaleSvgToNative, setStoredSession, validateAndCorrectOffsets, validateData, verifyPosition };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map