@vinaverse/client 0.0.0-stage → 0.1.0-alpha.1

package/dist/conversation/index.js

@@ -0,0 +1,858 @@
+import { ConversationEngine, randomId, VinaverseSession, VinaverseClientError, isKnownCard } from '../chunk-AWHPWRGT.js';
+export { CONTRACT, VinaverseClientError, isKnownCard } from '../chunk-AWHPWRGT.js';
+
+// src/conversation/answers.ts
+var CHOICE = /* @__PURE__ */ new Set([
+  "single_choice",
+  "multi_choice",
+  "image_choice",
+  "yes_no",
+  "list_choice"
+]);
+var ONE_CHOICE = /* @__PURE__ */ new Set(["single_choice", "yes_no", "list_choice"]);
+function codePoints(text) {
+  let n = 0;
+  for (const _ of text) n++;
+  return n;
+}
+function answerProblem(question, input) {
+  const answer = input;
+  if (answer.skipped === true) return question.required ? "required" : null;
+  const kind = question.kind;
+  if (CHOICE.has(kind)) return choiceProblem(question, answer);
+  switch (kind) {
+    case "rate_each": {
+      const values = answer.values ?? [];
+      if (answer.other_text !== void 0) return "not_allowed";
+      if (values.length === 0) return "required";
+      if (values.length > 1) return "too_many";
+      return (question.options ?? []).some((o) => o.value === values[0]) ? null : "not_allowed";
+    }
+    case "short_text":
+    case "long_text": {
+      const text = answer.text ?? "";
+      if (!text.trim()) return "required";
+      return codePoints(text) > (question.text?.max_length ?? 2e3) ? "too_long" : null;
+    }
+    case "number":
+    case "scale": {
+      const n = answer.number;
+      if (typeof n !== "number" || !Number.isFinite(n)) return "required";
+      const range = kind === "number" ? question.number : question.scale;
+      if (!range) return null;
+      if (n < range.min || n > range.max) return "out_of_range";
+      const steps = (n - range.min) / range.step;
+      return Math.abs(steps - Math.round(steps)) > 1e-9 ? "out_of_range" : null;
+    }
+    case "date":
+      return dateProblem(question, answer.date);
+    case "photo":
+      return answer.upload_ref ? null : "required";
+    default:
+      return null;
+  }
+}
+function choiceProblem(question, answer) {
+  const values = answer.values ?? [];
+  const other = answer.other_text;
+  if (other !== void 0) {
+    if (!question.allows_other) return "not_allowed";
+    if (!other.trim()) return "required";
+    if (codePoints(other) > (question.other_max_length ?? 500))
+      return "too_long";
+    if (values.length > 0 && question.kind !== "single_choice" && question.kind !== "multi_choice")
+      return "not_allowed";
+  }
+  if (values.length === 0) return other !== void 0 ? null : "required";
+  if (new Set(values).size !== values.length) return "not_allowed";
+  const none = question.none_of_the_above?.value;
+  if (none !== void 0 && values.includes(none))
+    return values.length === 1 && other === void 0 ? null : "not_allowed";
+  const known = new Set((question.options ?? []).map((o) => o.value));
+  if (!values.every((v) => known.has(v))) return "not_allowed";
+  if (ONE_CHOICE.has(question.kind) && values.length > 1) return "too_many";
+  const chosen = values.length + (other !== void 0 ? 1 : 0);
+  if (question.min !== void 0 && chosen < question.min) return "too_few";
+  if (question.max !== void 0 && chosen > question.max) return "too_many";
+  return null;
+}
+function dateProblem(question, date) {
+  if (!date) return "required";
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(date);
+  if (!m) return "bad_date";
+  const [y, mo, d] = [Number(m[1]), Number(m[2]), Number(m[3])];
+  const at = new Date(Date.UTC(y, mo - 1, d));
+  if (at.getUTCFullYear() !== y || at.getUTCMonth() !== mo - 1 || at.getUTCDate() !== d)
+    return "bad_date";
+  if (question.date?.min !== void 0 && date < question.date.min)
+    return "bad_date";
+  if (question.date?.max !== void 0 && date > question.date.max)
+    return "bad_date";
+  return null;
+}
+
+// src/conversation/links.ts
+var PREFIX = /^[a-z][a-z0-9+.-]*:(\/\/\.*[A-Za-z0-9_~-][A-Za-z0-9._~-]*(:(6553[0-5]|655[0-2][0-9]|65[0-4][0-9]{2}|6[0-4][0-9]{3}|[1-5][0-9]{4}|[1-9][0-9]{0,3}))?\/|\.*[A-Za-z0-9_~-][A-Za-z0-9._~-]*\/)(\.*[A-Za-z0-9_~-][A-Za-z0-9._~-]*\/)*$/;
+var PREFIX_HTTPS = /^https?:\/\/[a-z0-9-]+(\.[a-z0-9-]+)*(:(6553[0-5]|655[0-2][0-9]|65[0-4][0-9]{2}|6[0-4][0-9]{3}|[1-5][0-9]{4}|[1-9][0-9]{0,3}))?\/\.*[A-Za-z0-9_~-][A-Za-z0-9._~-]*\//;
+var REFUSED_SCHEMES = /^(javascript|vbscript|data|blob|file|filesystem|about|view-source|intent|android-app|content|jar|mhtml|itms-services|ftp|ws|wss):/;
+var CONTROLS = /[\x00-\x1f\x7f]/;
+var REMAINDER = /^(\.*[A-Za-z0-9_~-][A-Za-z0-9._~-]*(\/\.*[A-Za-z0-9_~-][A-Za-z0-9._~-]*)*\/?)?(\?([A-Za-z0-9._~=&-]|%(2[0-46-9A-Ea-e]|3[0-9B-Fb-f]|[46][0-9A-Fa-f]|5[0-9ABD-Fabd-f]|7[0-9A-Ea-e]))*)?$/;
+function isValidLinkPrefix(prefix) {
+  if (CONTROLS.test(prefix) || REFUSED_SCHEMES.test(prefix)) return false;
+  if (/^https?:/.test(prefix) && !PREFIX_HTTPS.test(prefix)) return false;
+  return PREFIX.test(prefix);
+}
+function isAllowedLink(link, prefixes) {
+  return prefixes.some(
+    (prefix) => isValidLinkPrefix(prefix) && link.startsWith(prefix) && REMAINDER.test(link.slice(prefix.length))
+  );
+}
+
+// src/conversation/timeline.ts
+function lastOrder(state) {
+  let last = -1;
+  for (const m of state.messages) last = Math.max(last, m.seq);
+  for (const c of state.cards) last = Math.max(last, c.seq);
+  if (state.streaming) last = Math.max(last, state.streaming.seq);
+  return last;
+}
+function pendingState(id, input) {
+  const { state } = input;
+  if (input.retried.has(id)) return null;
+  if (input.early.has(id)) return "sending";
+  if (state.messages.some((m) => m.key === id)) return null;
+  const refused = state.refused[id];
+  if (refused !== void 0) return refused === "guardrail" ? null : "not_sent";
+  if (state.heldForNextSession.includes(id)) return "held";
+  if (state.resend.includes(id) || state.held.includes(id) || state.unacknowledged.some((f) => f.client_event_id === id))
+    return "sending";
+  return null;
+}
+function buildTimeline(input, previous) {
+  const before = new Map(previous.map((item) => [item.key, item]));
+  const live = [];
+  const { state } = input;
+  for (const m of state.messages)
+    live.push({ item: messageItem(m), order: m.seq });
+  if (state.streaming) {
+    live.push({
+      item: {
+        type: "message",
+        key: `a:${state.streaming.turnId}`,
+        role: "agent",
+        text: "",
+        state: "streaming"
+      },
+      order: state.streaming.seq
+    });
+  }
+  for (const card of state.cards) {
+    if (!isKnownCard(card.card)) continue;
+    live.push({
+      item: {
+        type: "card",
+        key: card.id,
+        card,
+        busy: input.busy.has(card.id),
+        ...input.decisionErrors?.has(card.id) ? { decisionError: true } : {}
+      },
+      order: card.seq
+    });
+  }
+  for (const { item, order } of input.system) live.push({ item, order });
+  for (const [id, sent] of input.sent) {
+    const pending = pendingState(id, input);
+    if (pending === null) continue;
+    const rejection = state.rejections[id];
+    live.push({
+      item: {
+        type: "message",
+        key: id,
+        role: "person",
+        text: sent.text,
+        state: pending,
+        ...pending === "not_sent" ? {
+          rejection: rejection ?? {
+            code: state.refused[id] ?? "",
+            message: ""
+          }
+        } : {}
+      },
+      order: sent.order
+    });
+  }
+  live.sort((a, b) => a.order - b.order);
+  const liveByKey = new Map(live.map((l) => [l.item.key, l.item]));
+  const transcript = input.transcriptSeen === true;
+  const items = [];
+  const placed = /* @__PURE__ */ new Set();
+  if (!transcript)
+    for (const item of input.history) {
+      const current = liveByKey.get(item.key);
+      items.push(current ?? item);
+      if (current) placed.add(item.key);
+    }
+  for (const { item } of live) if (!placed.has(item.key)) items.push(item);
+  let same = items.length === previous.length;
+  const shared = items.map((item, i) => {
+    const prev = before.get(item.key);
+    const kept = prev !== void 0 && equal(prev, item) ? prev : item;
+    if (kept !== previous[i]) same = false;
+    return kept;
+  });
+  return same ? previous : shared;
+}
+function messageItem(m) {
+  const role = m.role === "assistant" ? "agent" : m.role;
+  return {
+    type: "message",
+    key: m.key,
+    role,
+    text: m.text,
+    state: m.received ? "delivered" : "sent",
+    ...m.partial ? { partial: m.partial } : {},
+    ...m.refusal ? { refusal: true } : {}
+  };
+}
+function equal(a, b) {
+  if (a.type !== b.type || a.key !== b.key) return false;
+  if (a.type === "message" && b.type === "message")
+    return a.role === b.role && a.text === b.text && a.state === b.state && a.partial === b.partial && a.refusal === b.refusal && a.rejection?.code === b.rejection?.code && a.rejection?.message === b.rejection?.message;
+  if (a.type === "card" && b.type === "card")
+    return a.busy === b.busy && a.restored === b.restored && a.decisionError === b.decisionError && sameCard(a.card, b.card);
+  return a === b;
+}
+function sameCard(a, b) {
+  return a.card === b.card && a.seq === b.seq && a.turnId === b.turnId && a.outcome === b.outcome && a.locked.length === b.locked.length && a.locked.every((q, i) => q === b.locked[i]) && a.question?.state === b.question?.state && JSON.stringify(a.question?.answer) === JSON.stringify(b.question?.answer) && JSON.stringify(a.question?.row_answers) === JSON.stringify(b.question?.row_answers);
+}
+function persistable(item) {
+  if (item.type === "message")
+    return item.state === "sent" || item.state === "delivered";
+  return item.type === "card";
+}
+
+// src/conversation/store.ts
+var MAX_TEXT = 2e3;
+var PERSIST_DELAY = 500;
+var PERSIST_VERSION = 1;
+var NO_ITEMS = [];
+var OUTCOMES = /* @__PURE__ */ new Set([
+  "confirmed",
+  "declined",
+  "failed",
+  "expired"
+]);
+var ConversationStore = class {
+  options;
+  engine = new ConversationEngine();
+  session = null;
+  info = null;
+  getting = null;
+  failed = false;
+  disposed = false;
+  online = null;
+  foreground = true;
+  lastStatus = "idle";
+  offlineAfterRetries = false;
+  /** The id the next send gets, so a text typed before the session keeps its key. */
+  nextId = null;
+  sent = /* @__PURE__ */ new Map();
+  early = /* @__PURE__ */ new Map();
+  retried = /* @__PURE__ */ new Set();
+  busy = /* @__PURE__ */ new Set();
+  /** Proposals whose tenant decision threw: shown as recoverable, the person may decide again. */
+  decisionErrors = /* @__PURE__ */ new Set();
+  system = [];
+  /** Numbers system rows that carry no id of their own. */
+  systemSeq = 0;
+  history = NO_ITEMS;
+  historyState = "none";
+  /** A resumed session.ready carried a transcript: the server's history replaced what the device kept. */
+  transcriptSeen = false;
+  locale;
+  /** The request for a session in flight, to abort when it is no longer wanted. */
+  fetching = null;
+  view;
+  listeners = /* @__PURE__ */ new Set();
+  streaming = null;
+  streamListeners = /* @__PURE__ */ new Set();
+  /** The frame that will notify, and what it will notify about. */
+  frame = void 0;
+  framePending = false;
+  viewDirty = false;
+  streamDirty = false;
+  persistTimer;
+  unsubscribe = [];
+  constructor(options) {
+    this.options = options;
+    this.locale = options.locale;
+    this.view = this.compute(null);
+    this.restore();
+  }
+  // ------------------------------------------------------------ reading
+  getSnapshot = () => this.view;
+  subscribe = (listener) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+  getStreaming = () => this.streaming;
+  subscribeStreaming = (listener) => {
+    this.streamListeners.add(listener);
+    return () => this.streamListeners.delete(listener);
+  };
+  /** Whether a card's link may be opened (the deep-link rule, against `deepLinkPrefixes`). */
+  checkLink(link) {
+    return isAllowedLink(link, this.options.deepLinkPrefixes ?? []);
+  }
+  // ------------------------------------------------------------ the conversation's life
+  /** Ask for a session and connect, early: a client secret must open its first connection within two minutes. */
+  start() {
+    this.live();
+    if (this.session) {
+      if (this.session.status === "idle") this.session.connect();
+      return;
+    }
+    void this.ensureSession("open");
+  }
+  /** Close for good. */
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.fetching?.abort();
+    this.fetching = null;
+    this.session?.close();
+    for (const off of this.unsubscribe) off();
+    this.unsubscribe = [];
+    clearTimeout(this.persistTimer);
+    this.update();
+    this.flush();
+  }
+  /** Close for good and forget the conversation kept on the device (sign-out). Never throws for the storage. */
+  clear() {
+    this.dispose();
+    this.history = NO_ITEMS;
+    try {
+      const removed = this.options.persistence?.removeItem(this.key());
+      if (removed) removed.catch(() => void 0);
+    } catch {
+    }
+    this.update();
+    this.flush();
+  }
+  /**
+   * The person switched the app's language: the UI's words change at once (the kit's own locale); the next session
+   * asks for this locale (`subject.locale`). The open session keeps its language: the agent answers in the new one
+   * from the next session, and the store never starts a session for it.
+   */
+  setLocale(locale) {
+    this.locale = locale;
+  }
+  /** The app came to the foreground or went to the background (AppState, `visibilitychange`). */
+  setForeground(foreground) {
+    this.foreground = foreground;
+    this.session?.setForeground(foreground);
+    if (foreground) this.reconnectIfDown();
+  }
+  /** The network as the app sees it; null when unknown. Back online reconnects a connection that gave up. */
+  setOnline(online) {
+    this.online = online;
+    if (online) this.reconnectIfDown();
+    this.update();
+  }
+  // ------------------------------------------------------------ the person's actions
+  /** Send a typed message; returns its `client_event_id`. Typed before a session exists, it is sent once one does. */
+  send(text) {
+    this.live();
+    if (!text.trim()) throw new RangeError("A message needs some text.");
+    if ([...text].length > MAX_TEXT)
+      throw new RangeError(`A message is at most ${MAX_TEXT} characters.`);
+    const id = (this.options.createId ?? randomId)();
+    this.sent.set(id, { text, order: lastOrder(this.engine.state()) + 0.5 });
+    if (!this.session) {
+      this.early.set(id, text);
+      void this.ensureSession("open");
+      this.update();
+      return id;
+    }
+    if (this.nextFrom(this.engine.state()) === "continue_here") {
+      this.early.set(id, text);
+      void this.resumeWith("continue_here");
+      this.update();
+      return id;
+    }
+    this.nextId = id;
+    this.session.sendText(text);
+    this.nextId = null;
+    this.continueIfEnded();
+    return id;
+  }
+  /** Answer a question card (a `rate_each` row by its `question_id`); returns the `client_event_id`. */
+  answer(cardId, questionId, answer) {
+    const session = this.required();
+    const id = session.answer(cardId, questionId, answer);
+    this.continueIfEnded();
+    return id;
+  }
+  /** A card action (`ui.action`) other than a proposal's outcome. */
+  cardAction(cardId, action) {
+    return this.required().action(cardId, action);
+  }
+  /**
+   * Decide a proposal: `decide` is the tenant's own call (its backend, the person's token), which confirms or
+   * declines it and says the outcome; the store then reports it. One decision per card; the card is busy meanwhile.
+   * Resolves to the outcome reported, or null when the card was busy or already decided.
+   *
+   * Only an outcome `decide` resolves with is reported (§6: the first is final). When `decide` throws, or resolves
+   * with anything but `confirmed`, `declined`, `failed` or `expired`, nothing is reported: the backend may have
+   * applied the change, so the outcome stays unknown; the card shows `decisionError` and the person may decide
+   * again. When the conversation is disposed meanwhile (sign-out), the outcome is not reported either: the tenant's
+   * backend holds it, and the session takes it as unknown.
+   */
+  async decideProposal(cardId, decide) {
+    this.live();
+    const card = this.engine.state().cards.find((c) => c.id === cardId);
+    if (card?.kind !== "proposal") return null;
+    if (this.busy.has(cardId) || (card.outcome ?? null) !== null) return null;
+    this.busy.add(cardId);
+    this.decisionErrors.delete(cardId);
+    this.update();
+    try {
+      const outcome = await decide();
+      if (typeof outcome !== "string" || !OUTCOMES.has(outcome))
+        throw new TypeError(
+          `decide() resolved with ${JSON.stringify(outcome)}, not confirmed, declined, failed or expired`
+        );
+      if (this.disposed) return outcome;
+      if (this.view.next === "continue") await this.resumeWith("resume");
+      this.required().reportOutcome(cardId, outcome);
+      return outcome;
+    } catch (error) {
+      this.decisionErrors.add(cardId);
+      throw error;
+    } finally {
+      this.busy.delete(cardId);
+      this.update();
+    }
+  }
+  /** Send a "not sent" message again, as a new message (the person's action). Returns the new id. */
+  retry(key) {
+    const sent = this.sent.get(key);
+    if (!sent || this.engine.state().refused[key] === void 0) return null;
+    this.retried.add(key);
+    this.sent.delete(key);
+    return this.send(sent.text);
+  }
+  /** After the conversation continued on another device: continue it here (the person's choice). */
+  continueHere() {
+    return this.resumeWith("continue_here");
+  }
+  /** Stop the turn in progress. */
+  cancel() {
+    const turn = this.engine.state().turn;
+    if (this.session && turn) this.session.cancel(turn);
+  }
+  // ------------------------------------------------------------ sessions
+  async ensureSession(reason) {
+    if (this.session) return this.session;
+    if (this.getting) return this.getting;
+    this.getting = this.fetchSession(reason).then((info) => {
+      this.getting = null;
+      if (!info || this.disposed) return null;
+      this.open(info);
+      return this.session;
+    });
+    this.update();
+    return this.getting;
+  }
+  async fetchSession(reason) {
+    this.failed = false;
+    this.fetching?.abort();
+    const Controller = globalThis.AbortController;
+    const controller = Controller ? new Controller() : null;
+    const mine = { abort: () => controller?.abort() };
+    this.fetching = mine;
+    let aborted = false;
+    const signal = controller?.signal;
+    signal?.addEventListener("abort", () => {
+      aborted = true;
+    });
+    try {
+      const info = await this.options.getSession({
+        reason,
+        conversationId: this.engine.state().conversationId,
+        ...this.locale !== void 0 ? { locale: this.locale } : {},
+        ...this.options.timeZone !== void 0 ? { timeZone: this.options.timeZone } : {},
+        ...signal ? { signal } : {}
+      });
+      return aborted || this.fetching !== mine ? null : info;
+    } catch (error) {
+      if (aborted || this.fetching !== mine) return null;
+      this.failed = true;
+      this.getting = null;
+      this.options.onError?.(error);
+      this.update();
+      return null;
+    } finally {
+      if (this.fetching === mine) this.fetching = null;
+    }
+  }
+  open(info) {
+    this.info = info;
+    const session = new VinaverseSession({
+      ...this.options.transport,
+      session: info,
+      engine: this.engine,
+      ...this.options.refreshSecret ? { refreshSecret: this.options.refreshSecret } : {},
+      createId: () => this.nextId ?? (this.options.createId ?? randomId)()
+    });
+    this.session = session;
+    this.unsubscribe.push(
+      session.on("state", () => this.update()),
+      session.on("status", (status) => this.statusChanged(status)),
+      session.on("event", (event) => this.event(event)),
+      session.on("error", (error) => this.options.onError?.(error))
+    );
+    session.setForeground(this.foreground);
+    session.connect();
+    this.flushEarly();
+  }
+  /** What was typed before there was a session to take it. */
+  flushEarly() {
+    const session = this.session;
+    if (!session) return;
+    for (const [id, text] of this.early) {
+      this.nextId = id;
+      session.sendText(text);
+    }
+    this.nextId = null;
+    this.early.clear();
+    this.update();
+  }
+  /** A new session for the conversation, then `resume()`: once per person action, never in a loop. */
+  resuming = null;
+  resumeWith(reason) {
+    this.live();
+    if (this.resuming) return this.resuming;
+    if (!this.session) return this.ensureSession(reason).then(() => void 0);
+    this.resuming = this.fetchSession(reason).then((info) => {
+      this.resuming = null;
+      if (!info || this.disposed || !this.session) return;
+      this.info = info;
+      this.session.resume(info);
+      this.flushEarly();
+    });
+    return this.resuming;
+  }
+  /** The person acted after the session ended idle, expired or at its limit: the next session takes what they sent. */
+  continueIfEnded() {
+    if (this.nextFrom(this.engine.state()) === "continue")
+      void this.resumeWith("resume");
+    this.update();
+  }
+  reconnectIfDown() {
+    const session = this.session;
+    if (session && session.status === "idle" && this.nextFrom(this.engine.state()) === null)
+      session.connect();
+  }
+  statusChanged(status) {
+    if (status === "idle")
+      this.offlineAfterRetries = this.lastStatus === "reconnecting";
+    else if (status !== "reconnecting") this.offlineAfterRetries = false;
+    this.lastStatus = status;
+    this.update();
+  }
+  event(event) {
+    const frame = event;
+    const str = (v) => typeof v === "string" ? v : null;
+    const add = (key, kind, data) => {
+      if (this.system.some((s) => s.item.key === key)) return;
+      this.system = [
+        ...this.system,
+        {
+          item: { type: "system", key, event: kind, data },
+          order: lastOrder(this.engine.state()) + 0.75
+        }
+      ];
+    };
+    switch (frame.type) {
+      case "session.ready":
+        if (frame.resumed === true && Array.isArray(frame.transcript))
+          this.transcriptSeen = true;
+        return;
+      // `at` is required (v1-draft.15); the same takeover announced again after a reconnect has the same `at`, so it
+      // draws one row. A frame without one still gets a row of its own.
+      case "takeover.started":
+        add(
+          `takeover:${str(frame.at) ?? `#${++this.systemSeq}`}`,
+          "takeover_started",
+          { by: str(frame.by) }
+        );
+        return;
+      case "takeover.ended":
+        add(
+          `takeover-ended:${str(frame.at) ?? `#${++this.systemSeq}`}`,
+          "takeover_ended",
+          {}
+        );
+        return;
+      case "handoff.created": {
+        const ticket = frame.ticket;
+        add(`handoff:${str(ticket?.id) ?? ""}`, "handoff_created", {
+          expected_response: str(ticket?.expected_response)
+        });
+        return;
+      }
+      case "flow.completed":
+        add(`flow:#${++this.systemSeq}`, "flow_completed", {
+          result: str(frame.result),
+          code: str(frame.code)
+        });
+        return;
+      case "turn.failed": {
+        const turn = str(frame.turn_id) ?? "";
+        if (this.engine.state().messages.some((m) => m.key === `a:${turn}`))
+          return;
+        if (frame.code === "cancelled") return;
+        add(`failed:${turn}`, "turn_failed", {
+          code: str(frame.code),
+          message: str(frame.message),
+          retryable: frame.retryable === true
+        });
+        return;
+      }
+      default:
+        return;
+    }
+  }
+  // ------------------------------------------------------------ the view
+  /**
+   * Recomputes now (getSnapshot and getStreaming are always current) and notifies from the scheduler, at most once
+   * per frame, both channels in the same flush: a streamed reply that completes becomes its message in one frame.
+   */
+  update() {
+    const state = this.engine.state();
+    this.stream(state);
+    const view = this.compute(state);
+    if (view !== this.view) {
+      this.view = view;
+      this.viewDirty = true;
+      this.schedulePersist();
+    }
+    if (this.viewDirty || this.streamDirty) this.scheduleNotify();
+  }
+  scheduleNotify() {
+    if (this.framePending || this.disposed) return;
+    if (this.listeners.size === 0 && this.streamListeners.size === 0) return;
+    this.framePending = true;
+    this.frame = this.scheduler().request(() => {
+      this.frame = void 0;
+      this.framePending = false;
+      this.flush();
+    });
+  }
+  /** Calls the listeners of what changed since the last flush. */
+  flush() {
+    if (this.frame !== void 0) {
+      this.scheduler().cancel(this.frame);
+      this.frame = void 0;
+      this.framePending = false;
+    }
+    const view = this.viewDirty;
+    const stream = this.streamDirty;
+    this.viewDirty = false;
+    this.streamDirty = false;
+    if (stream) for (const l of [...this.streamListeners]) l();
+    if (view) for (const l of [...this.listeners]) l();
+  }
+  compute(state) {
+    const s = state ?? this.engine.state();
+    const prev = this.view;
+    for (const id of [...this.sent.keys()])
+      if (!this.early.has(id) && s.messages.some((m) => m.key === id))
+        this.sent.delete(id);
+    const items = buildTimeline(
+      {
+        state: s,
+        history: this.history,
+        sent: this.sent,
+        early: new Set(this.early.keys()),
+        retried: this.retried,
+        busy: this.busy,
+        decisionErrors: this.decisionErrors,
+        transcriptSeen: this.transcriptSeen,
+        system: this.system
+      },
+      prev?.items ?? NO_ITEMS
+    );
+    const status = this.status();
+    const next = this.nextFrom(s);
+    const activity = s.turn === null ? [] : s.tools.filter((t) => t.turn_id === s.turn);
+    const name = this.info?.agent?.display_name ?? null;
+    const avatarUrl = this.info?.agent?.avatar_url ?? null;
+    const view = {
+      status,
+      banner: banner(status, next),
+      next,
+      agent: sameAgent(prev?.agent, name, avatarUrl) ? prev.agent : { name, avatarUrl },
+      disclosure: s.disclosure ?? this.info?.disclosure ?? null,
+      takeover: s.takeover,
+      items,
+      activity: prev && sameTools(prev.activity, activity) ? prev.activity : activity,
+      responding: s.turn !== null || s.streaming !== null,
+      openQuestion: s.openQuestion,
+      answersNeedWebSocket: status === "sse",
+      turnsLeft: s.turnsLeft,
+      history: this.historyState
+    };
+    if (prev && shallowEqual(prev, view)) return prev;
+    return view;
+  }
+  status() {
+    if (this.disposed) return "closed";
+    const session = this.session;
+    if (!session) {
+      if (this.failed) return "unavailable";
+      return this.getting || this.early.size ? "starting" : "idle";
+    }
+    const status = session.status;
+    if (this.failed && status === "ended") return "unavailable";
+    if (status === "idle")
+      return this.offlineAfterRetries || this.online === false ? "offline" : "idle";
+    if (status === "reconnecting" && this.online === false) return "offline";
+    return status;
+  }
+  nextFrom(state) {
+    if (this.session?.status !== "ended" && state.reconnect === "allowed")
+      return null;
+    if (state.reconnect === "new_session_on_next_action") return "continue";
+    if (state.reconnect === "user_action_only") return "continue_here";
+    return null;
+  }
+  /** The streamed text, current at once; its listeners hear of it with the next flush. */
+  stream(state) {
+    const s = state.streaming;
+    if (!s) {
+      if (this.streaming !== null) {
+        this.streaming = null;
+        this.streamDirty = true;
+      }
+      return;
+    }
+    if (this.streaming?.turnId === s.turnId && this.streaming.text === s.text)
+      return;
+    this.streaming = { key: `a:${s.turnId}`, turnId: s.turnId, text: s.text };
+    this.streamDirty = true;
+  }
+  scheduler() {
+    return this.options.scheduler ?? defaultScheduler;
+  }
+  // ------------------------------------------------------------ persistence
+  key() {
+    return this.options.persistenceKey ?? "vinaverse.conversation";
+  }
+  restore() {
+    const store = this.options.persistence;
+    if (!store) return;
+    const done = () => {
+      this.historyState = "restored";
+      this.update();
+    };
+    const apply = (raw) => {
+      if (this.disposed) return;
+      if (raw === null) return done();
+      try {
+        const saved = JSON.parse(raw);
+        if (saved.v === PERSIST_VERSION && Array.isArray(saved.items))
+          this.history = saved.items.map(
+            (item) => item.type === "card" ? { ...item, busy: false, restored: true } : item
+          );
+      } catch {
+      }
+      done();
+    };
+    try {
+      const raw = store.getItem(this.key());
+      if (typeof raw === "string" || raw === null) apply(raw);
+      else {
+        this.historyState = "restoring";
+        this.view = this.compute(null);
+        raw.then(apply, () => {
+          if (!this.disposed) done();
+        });
+      }
+    } catch {
+      done();
+    }
+  }
+  schedulePersist() {
+    const store = this.options.persistence;
+    if (!store || this.disposed || this.persistTimer !== void 0) return;
+    this.persistTimer = setTimeout(() => {
+      this.persistTimer = void 0;
+      const items = this.view.items.filter(persistable).slice(-100);
+      try {
+        void store.setItem(
+          this.key(),
+          JSON.stringify({ v: PERSIST_VERSION, items })
+        );
+      } catch {
+      }
+    }, PERSIST_DELAY);
+  }
+  // ------------------------------------------------------------ guards
+  live() {
+    if (this.disposed)
+      throw new VinaverseClientError(
+        "session_ended",
+        "This conversation was closed."
+      );
+  }
+  required() {
+    this.live();
+    if (!this.session)
+      throw new VinaverseClientError(
+        "session_ended",
+        "The conversation has no session yet: start() it first."
+      );
+    return this.session;
+  }
+};
+function createConversation(options) {
+  return new ConversationStore(options);
+}
+var defaultScheduler = {
+  request(callback) {
+    const raf = globalThis.requestAnimationFrame;
+    return raf ? { raf: raf(callback) } : { timer: setTimeout(callback, 16) };
+  },
+  cancel(handle) {
+    const h = handle;
+    const caf = globalThis.cancelAnimationFrame;
+    if (h.raf !== void 0) caf?.(h.raf);
+    if (h.timer !== void 0) clearTimeout(h.timer);
+  }
+};
+function banner(status, next) {
+  if (status === "connecting" || status === "starting") return "connecting";
+  if (status === "reconnecting") return "reconnecting";
+  if (status === "offline") return "offline";
+  if (status === "unavailable" || status === "unauthorized")
+    return "unavailable";
+  if (next === "continue_here") return "continued_elsewhere";
+  return null;
+}
+function sameAgent(agent, name, avatarUrl) {
+  return agent?.name === name && agent?.avatarUrl === avatarUrl;
+}
+function sameTools(a, b) {
+  return a.length === b.length && a.every(
+    (t, i) => t.turn_id === b[i]?.turn_id && t.label === b[i]?.label && t.state === b[i]?.state
+  );
+}
+function shallowEqual(a, b) {
+  return a.status === b.status && a.banner === b.banner && a.next === b.next && a.agent.name === b.agent.name && a.agent.avatarUrl === b.agent.avatarUrl && a.disclosure === b.disclosure && a.takeover?.by === b.takeover?.by && a.takeover?.at === b.takeover?.at && a.takeover === null === (b.takeover === null) && a.items === b.items && a.activity === b.activity && a.responding === b.responding && a.openQuestion === b.openQuestion && a.answersNeedWebSocket === b.answersNeedWebSocket && a.turnsLeft === b.turnsLeft && a.history === b.history;
+}
+
+export { ConversationStore, MAX_TEXT, answerProblem, codePoints, createConversation, isAllowedLink, isValidLinkPrefix };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map