@coventia/softphone 0.4.0 → 0.5.1

package/dist/index.js

@@ -1,9 +1,10 @@
 import { isBrowser } from './chunk-KAXEMJ7E.js';
 export { isBrowser, isWebRtcSupported } from './chunk-KAXEMJ7E.js';
-export { CallEvent, SoftphoneEvent } from './chunk-7R6LOOAI.js';
+export { CallEvent, SoftphoneEvent } from './chunk-N4PLEYFJ.js';
 export { isOutboundNumberRefused } from './chunk-5E5OEXS2.js';
-import { isFatal } from './chunk-2ZSOGGPO.js';
-export { ERROR_CATALOGUE, isFatal } from './chunk-2ZSOGGPO.js';
+import { normalizeApiBase } from './chunk-M76SAXXM.js';
+import { createError, isSoftphoneError, isFatal } from './chunk-FRXHEHQA.js';
+export { ERROR_CATALOGUE, isFatal } from './chunk-FRXHEHQA.js';
 import { cachedTokenSource } from './chunk-MHOJHG5E.js';
 
 // src/core/emitter.ts
@@ -285,7 +286,7 @@ function coventiaBackend(config, tokenSource, fallbackBaseUrl) {
   }
   let pending = null;
   const load = () => {
-    pending ??= import('./sources-ONYQW733.js').then(
+    pending ??= import('./sources-LGFJG7W2.js').then(
       (m) => m.coventiaSources({ ...config, baseUrl, tokenSource })
     );
     return pending;
@@ -316,13 +317,15 @@ function isWebLocksSupported() {
   return isBrowser() && typeof navigator.locks?.request === "function";
 }
 function webLocksTabLock(lockName = LOCK_NAME) {
-  const controller = new AbortController();
+  let controller;
   let releaseHold;
   return {
     acquireLeadership() {
       if (!isWebLocksSupported()) return Promise.resolve();
+      const { signal } = controller = new AbortController();
       return new Promise((resolveAcquired) => {
-        navigator.locks.request(lockName, { signal: controller.signal }, () => {
+        navigator.locks.request(lockName, { signal }, () => {
+          if (signal.aborted) return Promise.resolve();
           resolveAcquired();
           return new Promise((resolveHold) => {
             releaseHold = resolveHold;
@@ -337,7 +340,7 @@ function webLocksTabLock(lockName = LOCK_NAME) {
         releaseHold = void 0;
         resolve();
       } else {
-        controller.abort();
+        controller?.abort();
       }
     }
   };
@@ -418,17 +421,70 @@ function startTransferWatch(params) {
   return stop;
 }
 
+// src/core/start-retry.ts
+var BACKOFF_BASE_MS = 1e3;
+var BACKOFF_MAX_MS = 3e4;
+function backoffDelayMs(attempt, random = Math.random) {
+  const capped = Math.min(BACKOFF_BASE_MS * 2 ** (Math.max(1, attempt) - 1), BACKOFF_MAX_MS);
+  return capped * random();
+}
+function isTransientStatus(status) {
+  return status === 0 || status === 408 || status === 425 || status === 429 || status >= 500;
+}
+function isNetworkFailure(error) {
+  const name = typeof error.name === "string" ? error.name : "";
+  return error instanceof TypeError || name === "AbortError" || name === "TimeoutError" || name === "NetworkError";
+}
+function transientStartFailure(error) {
+  let retryAfterMs = 0;
+  let viaTokenEndpoint = false;
+  let current = error;
+  for (let depth = 0; depth < 6 && current !== null && typeof current === "object"; depth += 1) {
+    const layer = current;
+    if (typeof layer.retryAfterMs === "number" && Number.isFinite(layer.retryAfterMs)) {
+      retryAfterMs = Math.max(retryAfterMs, layer.retryAfterMs);
+    }
+    if (typeof layer.status === "number") return isTransientStatus(layer.status) ? { retryAfterMs } : null;
+    if (isNetworkFailure(layer)) return { retryAfterMs };
+    if (isSoftphoneError(current)) {
+      if (layer.code === "auth/token-rejected") return null;
+      if (layer.code === "auth/token-fetch-failed") viaTokenEndpoint = true;
+    }
+    current = layer.cause;
+  }
+  return viaTokenEndpoint ? { retryAfterMs } : null;
+}
+function watchWake(wake) {
+  if (!isBrowser()) return () => {
+  };
+  const onOnline = () => wake();
+  const onVisibility = () => {
+    if (document.visibilityState === "visible") wake();
+  };
+  window.addEventListener("online", onOnline);
+  document.addEventListener("visibilitychange", onVisibility);
+  return () => {
+    window.removeEventListener("online", onOnline);
+    document.removeEventListener("visibilitychange", onVisibility);
+  };
+}
+
 // src/core/presence-socket.ts
-var RECONNECT_BASE_MS = 1e3;
-var RECONNECT_MAX_MS = 3e4;
 var NOOP_WATCH = { reportCallState: () => {
-}, stop: () => {
+}, claimLine: () => false, stop: () => {
 } };
 function startPresenceSocket(params) {
   const {
     source,
     getIsLeader,
     onAgentsChanged,
+    clientId,
+    onLine,
+    onClaimResult,
+    onOffer,
+    onLineUnsupported,
+    onConnectFailed,
+    onDisconnect,
     setTimeout: scheduleTimeout = globalThis.setTimeout,
     clearTimeout: cancelTimeout = globalThis.clearTimeout,
     random = Math.random
@@ -439,6 +495,8 @@ function startPresenceSocket(params) {
   let reconnectTimer = null;
   let agents = /* @__PURE__ */ new Map();
   let lastReportedOnCall = null;
+  let sentOnCall = null;
+  let line = null;
   let connection = null;
   let byeOnArrival = false;
   const stop = (options) => {
@@ -455,11 +513,16 @@ function startPresenceSocket(params) {
     connection?.close();
     connection = null;
   };
+  const send = (onCall) => {
+    if (!connection) return;
+    connection.reportCallState(onCall);
+    sentOnCall = onCall;
+  };
+  const mayReport = (onCall) => line !== "elsewhere" || !onCall && sentOnCall === true;
   const scheduleReconnect = () => {
     if (stopped) return;
     attempt += 1;
-    const capped = Math.min(RECONNECT_BASE_MS * 2 ** (attempt - 1), RECONNECT_MAX_MS);
-    const delay = capped * random();
+    const delay = backoffDelayMs(attempt, random);
     reconnectTimer = scheduleTimeout(() => void connect(), delay);
   };
   const connect = async () => {
@@ -483,10 +546,26 @@ function startPresenceSocket(params) {
           if (connection === null) return;
           connection = null;
           scheduleReconnect();
+          onDisconnect?.();
+        },
+        onLine: (update) => {
+          if (stopped) return;
+          const was = line;
+          line = update.state;
+          if (was === "elsewhere" && line === "here" && lastReportedOnCall !== null) send(lastReportedOnCall);
+          onLine?.(update);
+        },
+        onClaimResult: (result) => {
+          if (!stopped) onClaimResult?.(result);
+        },
+        onOffer: (offer) => {
+          if (!stopped) onOffer?.(offer);
         }
       });
     } catch {
-      if (!stopped) scheduleReconnect();
+      if (stopped) return;
+      scheduleReconnect();
+      onConnectFailed?.();
       return;
     }
     if (stopped) {
@@ -496,22 +575,63 @@ function startPresenceSocket(params) {
     }
     connection = opened;
     attempt = 0;
-    if (lastReportedOnCall !== null) connection.reportCallState(lastReportedOnCall);
+    sentOnCall = null;
+    line = null;
+    if (clientId !== void 0 && opened.hello) opened.hello(clientId);
+    else onLineUnsupported?.();
+    if (lastReportedOnCall !== null) send(lastReportedOnCall);
   };
   void connect();
   return {
     reportCallState: (onCall) => {
       if (onCall === lastReportedOnCall) return;
       lastReportedOnCall = onCall;
-      connection?.reportCallState(onCall);
+      if (mayReport(onCall)) send(onCall);
+    },
+    claimLine: () => {
+      if (!connection?.claimLine) return false;
+      connection.claimLine();
+      return true;
     },
     stop
   };
 }
 
+// src/core/line.ts
+var CLIENT_ID_KEY = "coventia-softphone:client-id";
+var CLIENT_ID_PATTERN = /^[A-Za-z0-9_.:-]{1,64}$/;
+function lineClientId() {
+  const stored = readStoredId();
+  if (stored) return stored;
+  const id = freshClientId();
+  try {
+    if (isBrowser()) globalThis.sessionStorage?.setItem(CLIENT_ID_KEY, id);
+  } catch {
+  }
+  return id;
+}
+function readStoredId() {
+  if (!isBrowser()) return null;
+  try {
+    const value = globalThis.sessionStorage?.getItem(CLIENT_ID_KEY);
+    return value && CLIENT_ID_PATTERN.test(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+function freshClientId() {
+  const uuid = globalThis.crypto?.randomUUID?.();
+  if (uuid) return uuid;
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;
+}
+
 // src/core/softphone-impl.ts
 var liveInstance = false;
 var PRESENCE_TEARDOWN_GRACE_MS = 1e4;
+var LINE_ANSWER_TIMEOUT_MS = 4e3;
+var CALL_DECISION_TIMEOUT_MS = LINE_ANSWER_TIMEOUT_MS + 2e3;
+var LINE_CLAIM_TIMEOUT_MS = 1e4;
+var LINE_LAPSE_MS = 1e4;
 var BrowserAudioDevices = class {
   inputs = [];
   outputs = [];
@@ -619,6 +739,8 @@ var SoftphoneImpl = class extends Emitter {
   #activeCall = null;
   #destroyed = false;
   #startedHere = false;
+  /** Bumped by every `stop()`, so a `start()` still waiting to lead can tell it was stopped. */
+  #run = 0;
   #isLeader = false;
   #engine;
   #tabLock;
@@ -643,6 +765,63 @@ var SoftphoneImpl = class extends Emitter {
   /** A pending state-driven teardown of the watch — see `PRESENCE_TEARDOWN_GRACE_MS`. */
   #presenceTeardownTimer = null;
   #presenceAgents = [];
+  // ── The line owner (`docs/specs/line-owner.md` §5) ──────────────────────────────────────────────
+  // Heard over the presence watch: the server names ONE softphone per extension that listens, and this one
+  // runs its engine only while that is it (or nobody can say). `#engineOn` and `#standby` are the two halves
+  // of that decision, kept apart because neither is true while `start()` is still waiting to make it.
+  #line = "unknown";
+  #lineWhere = null;
+  /** How the last attempt to bring the line here went (`lineClaim`), whoever made it. */
+  #lineClaim = "idle";
+  /** This tab's id in `hello` (`lineClientId`), read once — one id for every reconnect of this softphone. */
+  #clientId = null;
+  /** What the line wants: the engine running. Set the moment the line decides; the engine follows (`#queueEngine`). */
+  #engineOn = false;
+  /**
+   * What the engine was last TOLD by the queue — started or stopped. Apart from `#engineOn` because the line
+   * can flip twice while a start is still running: the stop and start queued meanwhile then find nothing
+   * to do, instead of stopping the engine (and the softphone with it) for a moment.
+   */
+  #engineRunning = false;
+  /** Waiting in `standby`: the engine is stopped ON PURPOSE, so its own `stopped` is not the softphone's. */
+  #standby = false;
+  /**
+   * Every engine start and stop the line asks for, one after another: a promotion can follow a demotion
+   * within a moment, and an engine started while its own stop is still running can end up neither.
+   */
+  #engineSteps = Promise.resolve();
+  /** Dials in flight (`call()` awaiting `placeCall`): a call about to exist holds the line like one that does. */
+  #dialing = 0;
+  /**
+   * Open from `start()`'s first line until it has decided whether the engine runs — or given up (stopped,
+   * destroyed, failed). `call()` waits on it, so it never dials ahead of that decision: not on a phone
+   * stopped meanwhile, and not without the line.
+   */
+  #startDecision = null;
+  /**
+   * Who decides whether the engine runs. `off`: nobody — not started, a follower, or `stop()` has begun
+   * (whatever its teardown sets off, like a call ending, must not start anything). `deciding`: `start()`
+   * has leadership and owes the FIRST decision itself, since it must await the engine start — a line
+   * message meanwhile only records what it says. `on`: the line decides (`#applyLine`).
+   */
+  #lineMode = "off";
+  /** Ends `start()`'s wait for the server's first word on the line early (`#waitForFirstLine`). */
+  #releaseFirstLine = null;
+  /** The `takeLine()` in flight — one at a time; a second caller shares it. */
+  #claim = null;
+  /** Pending: what the server said about the line stops counting (`LINE_LAPSE_MS`). */
+  #lineLapseTimer = null;
+  // ── The start retry (incoming-call-reliability.md §4.6) ─────────────────────────────────────────────────
+  // An engine start that failed for a passing reason (a 5xx, the network, a timeout) is attempted again on its
+  // own, with backoff, instead of leaving the phone `offline` until someone presses "Reintentar".
+  /** Failed attempts in the current streak; back to 0 when the engine starts, or the softphone stops. */
+  #startRetries = 0;
+  /** The wait before the next attempt, or `null` when none is pending. */
+  #startRetryTimer = null;
+  /** No attempt before this (epoch ms): a `Retry-After` the failure carried, which a wake-up must honour too. */
+  #startRetryNotBefore = 0;
+  /** Unsubscribes the `online` / tab-visible wake-ups, armed only while an attempt is pending. */
+  #unwatchWake = null;
   /**
    * `tabLock` defaults to the real Web Locks implementation — not part of `SoftphoneConfig` (an
    * internal seam, not something an integrator tunes). Tests construct this class directly with a
@@ -660,7 +839,9 @@ var SoftphoneImpl = class extends Emitter {
     this.sources = config.coventia || config.apiBase ? coventiaBackend(config.coventia ?? {}, cachedTokenSource(config.tokenSource), config.apiBase) : null;
     this.#resolveContact = config.resolveContact ?? this.sources?.resolveContact;
     this.#engine.onIncoming((engineCall) => this.#onIncoming(engineCall));
-    this.#engine.onStateChange((state) => this.#setState(state));
+    this.#engine.onStateChange((state) => {
+      if (!this.#standby) this.#setState(state);
+    });
     this.#engine.onError?.((error) => this.#onError(error));
   }
   get state() {
@@ -678,6 +859,15 @@ var SoftphoneImpl = class extends Emitter {
   get presence() {
     return this.#presenceAgents;
   }
+  get line() {
+    return this.#line;
+  }
+  get lineWhere() {
+    return this.#lineWhere;
+  }
+  get lineClaim() {
+    return this.#lineClaim;
+  }
   get canPlayAudio() {
     return true;
   }
@@ -693,15 +883,34 @@ var SoftphoneImpl = class extends Emitter {
     }
     liveInstance = true;
     this.#startedHere = true;
-    this.#setState("starting");
-    await this.#tabLock.acquireLeadership();
-    if (this.#destroyed) return;
-    this.#setLeader(true);
-    await this.#engine.start();
+    const run = this.#run;
+    const decision = this.#openStartDecision();
+    try {
+      this.#setState("starting");
+      await this.#tabLock.acquireLeadership();
+      if (this.#destroyed || run !== this.#run) return;
+      this.#lineMode = "deciding";
+      this.#setLeader(true);
+      if (this.#presenceWatch && this.#line === "unknown") await this.#waitForFirstLine();
+      if (this.#destroyed || run !== this.#run) return;
+      this.#lineMode = "on";
+      const engineStart = this.#applyLine();
+      decision.end();
+      await engineStart;
+    } finally {
+      decision.end();
+    }
   }
   async stop() {
     if (!this.#startedHere) return;
+    this.#run += 1;
+    this.#cancelStartRetry();
+    this.#lineMode = "off";
     this.#sayGoodbye();
+    this.#startDecision?.end();
+    this.#standby = false;
+    this.#engineOn = false;
+    this.#engineRunning = false;
     this.#tabLock.release();
     if (this.#isLeader) {
       await this.#engine.stop();
@@ -723,16 +932,51 @@ var SoftphoneImpl = class extends Emitter {
     this.#setState("destroyed");
     this.clear();
   }
+  async takeLine() {
+    this.#assertUsable();
+    if (this.#line === "here") return;
+    if (this.#claim) return this.#claim.promise;
+    const watch = this.#presenceWatch;
+    if (!watch) {
+      this.#setLineClaim("failed");
+      throw createError("line/unavailable");
+    }
+    const claim = this.#openClaim();
+    if (!watch.claimLine()) this.#settleClaim(createError("line/unavailable"));
+    return claim;
+  }
   async call(destination, options) {
     this.#assertUsable();
+    const run = this.#run;
+    if (this.#startRetryTimer !== null) this.#wakeStartRetry();
+    if (this.#startDecision) {
+      let timer;
+      const decided = await Promise.race([
+        this.#startDecision.promise.then(() => true),
+        new Promise((resolve) => {
+          timer = setTimeout(() => resolve(false), CALL_DECISION_TIMEOUT_MS);
+        })
+      ]);
+      clearTimeout(timer);
+      if (!decided) throw createError("engine/not-started");
+    }
+    if (run === this.#run && this.#state === "standby") await this.takeLine();
+    this.#assertUsable();
+    if (run !== this.#run) throw createError("engine/not-started");
     if (this.#state !== "online" && this.#state !== "offline" && this.#state !== "starting") {
       throw new Error(`Cannot place a call while softphone is '${this.#state}'.`);
     }
-    if (this.#activeCall) {
+    if (this.#activeCall || this.#dialing > 0) {
       throw new Error("A call is already in progress. Hang up before placing another.");
     }
-    const engineCall = await this.#engine.placeCall(destination, options);
-    return this.#adopt(engineCall);
+    this.#dialing += 1;
+    try {
+      const engineCall = await this.#engine.placeCall(destination, options);
+      return this.#adopt(engineCall);
+    } finally {
+      this.#dialing -= 1;
+      this.#syncLine();
+    }
   }
   // ── internals ───────────────────────────────────────────────────────────────
   #onIncoming(engineCall) {
@@ -761,6 +1005,7 @@ var SoftphoneImpl = class extends Emitter {
         this.#activeCall = null;
         this.emit("activeCallChanged" /* ActiveCallChanged */, { call: null });
         this.#syncCallState();
+        this.#syncLine();
       }
     });
     if (this.#resolveContact) {
@@ -790,7 +1035,8 @@ var SoftphoneImpl = class extends Emitter {
   /**
    * Reports the current on-a-call value to the backend. The watch de-duplicates (it only sends on change) and
    * remembers the latest value to replay after a reconnect, so this can be called on every transition without
-   * ceremony. A no-op while there is no presence watch (not online, not the leader, no backend configured).
+   * ceremony — and holds it back while the line is elsewhere, since only the owner's reports count (line-owner
+   * R8). A no-op while there is no presence watch (stopped, not the leader, no backend configured).
    */
   #syncCallState() {
     this.#presenceWatch?.reportCallState(this.#isOnCall());
@@ -811,17 +1057,22 @@ var SoftphoneImpl = class extends Emitter {
    * `presence-socket.ts`'s own `getIsLeader` is checked at start and before each reconnect attempt,
    * not on a poll tick the way `startTransferWatch`'s is — see that module's own doc comment for why.
    * This still passes `getIsLeader: () => this.#isLeader` for that narrower, defensive recheck; the
-   * BROAD online/leader gate — whether to be connected AT ALL — is owned entirely here, the same
+   * BROAD started/leader gate — whether to be connected AT ALL — is owned entirely here, the same
    * split `#onTransfer` already has with `startTransferWatch`.
    *
-   * One exception to "tear down the moment `online` is lost": a leader that is merely `offline` or
-   * `reconnecting` keeps its watch for `PRESENCE_TEARDOWN_GRACE_MS` — a blip shorter than that never touches
-   * the presence socket at all. Anything else (stopped, starting, destroyed, or no longer the leader) still
-   * tears it down at once: those are not blips, and a follower must never hold a connection.
+   * The watch runs for a leader that is `starting`, `online` or in `standby` — not only `online`, as it did
+   * before the line owner (`docs/specs/line-owner.md` §5.4): while starting it is how this softphone learns
+   * whether to listen at all, and in standby how it learns the line came back.
+   *
+   * A leader that is merely `offline` or `reconnecting` keeps its watch for `PRESENCE_TEARDOWN_GRACE_MS` — a
+   * blip shorter than that never touches the presence socket at all; a longer outage closes it, which lets
+   * the server hand the line to a softphone that can still take calls. Anything else (stopped, destroyed, or
+   * no longer the leader) tears it down at once: those are not blips, and a follower must never hold a
+   * connection.
    */
   #syncPresenceWatch() {
     const eligible = Boolean(this.sources) && this.#isLeader;
-    const shouldRun = eligible && this.#state === "online";
+    const shouldRun = eligible && this.#presenceRunsIn(this.#state);
     const blip = eligible && (this.#state === "offline" || this.#state === "reconnecting");
     if (!blip) this.#cancelPresenceTeardown();
     if (blip && this.#presenceWatch !== null) {
@@ -830,13 +1081,25 @@ var SoftphoneImpl = class extends Emitter {
     }
     if (shouldRun === (this.#presenceWatch !== null)) return;
     if (shouldRun) {
+      this.#clientId ??= lineClientId();
       this.#presenceWatch = startPresenceSocket({
         source: this.sources.presence,
         getIsLeader: () => this.#isLeader,
         onAgentsChanged: (agents) => {
           this.#presenceAgents = agents;
           this.emit("presenceChanged" /* PresenceChanged */, { agents });
-        }
+        },
+        clientId: this.#clientId,
+        onLine: (update) => this.#onLine(update),
+        onClaimResult: (result) => this.#onClaimResult(result),
+        // The calls offered to this line, straight to the engine: after a decline, they say when the declined
+        // call's re-offers stop (incoming-call-reliability.md §4.4). Not public — nothing a host acts on.
+        onOffer: (offer) => this.#engine.noteOffer?.(offer),
+        // A source that cannot take part will never answer, and one that cannot connect cannot answer yet:
+        // `start()` need not wait out its 4 s for either (R7). A later answer still applies.
+        onLineUnsupported: () => this.#releaseFirstLine?.(),
+        onConnectFailed: () => this.#releaseFirstLine?.(),
+        onDisconnect: () => this.#onPresenceDisconnect()
       });
       this.#syncCallState();
     } else {
@@ -851,19 +1114,24 @@ var SoftphoneImpl = class extends Emitter {
     if (this.#presenceTeardownTimer !== null) return;
     this.#presenceTeardownTimer = setTimeout(() => {
       this.#presenceTeardownTimer = null;
-      if (this.#state === "online" && this.#isLeader) return;
+      if (this.#isLeader && this.#presenceRunsIn(this.#state)) return;
       this.#stopPresence();
     }, PRESENCE_TEARDOWN_GRACE_MS);
   }
+  /** The states in which a leader keeps its presence watch with no clock running (`#syncPresenceWatch`). */
+  #presenceRunsIn(state) {
+    return state === "online" || state === "starting" || state === "standby";
+  }
   #cancelPresenceTeardown() {
     if (this.#presenceTeardownTimer === null) return;
     clearTimeout(this.#presenceTeardownTimer);
     this.#presenceTeardownTimer = null;
   }
   /**
-   * Stops the presence watch and forgets its roster. A STATE-DRIVEN teardown (the softphone left `online`
-   * for good, or lost leadership) passes nothing and says no goodbye; only a deliberate stop passes `bye`.
-   * Any pending grace-period teardown is cancelled — there is nothing left for it to do.
+   * Stops the presence watch and forgets its roster, and the line. A STATE-DRIVEN teardown (an outage
+   * outlasted the grace, the engine stopped, or leadership was lost) passes nothing and says no goodbye;
+   * only a deliberate stop passes `bye`. Any pending grace-period teardown is cancelled — there is nothing
+   * left for it to do.
    */
   #stopPresence(options) {
     this.#cancelPresenceTeardown();
@@ -872,6 +1140,8 @@ var SoftphoneImpl = class extends Emitter {
     this.#presenceWatch = null;
     this.#presenceAgents = [];
     this.emit("presenceChanged" /* PresenceChanged */, { agents: [] });
+    this.#forgetLine();
+    this.#engine.noteOffer?.(null);
   }
   /**
    * A DELIBERATE stop (`stop()` / `destroy()`): say any call is over, then say goodbye, so the backend drops
@@ -881,6 +1151,278 @@ var SoftphoneImpl = class extends Emitter {
     this.#presenceWatch?.reportCallState(false);
     this.#stopPresence({ bye: true });
   }
+  // ── the line owner (`docs/specs/line-owner.md` §5) ──────────────────────────────────────────────
+  /**
+   * THE decision: from where the line is and whether a call is in progress, whether the engine runs, and
+   * the state that says so. Synchronous, so the state moves the instant the line does — the waiting screen
+   * goes the moment the line comes here, and a `call()` that took the line dials from `starting` without
+   * waiting out the engine start. Only the engine start or stop is queued (`#queueEngine`). Returns that
+   * queued step, or `null` when nothing had to change.
+   */
+  #applyLine() {
+    if (this.#lineMode !== "on") return null;
+    const run = this.#run;
+    if (this.#line === "elsewhere") {
+      if (this.#standby || this.#activeCall || this.#dialing > 0) return null;
+      this.#standby = true;
+      this.#setState("standby");
+      if (!this.#engineOn) return null;
+      this.#engineOn = false;
+      return this.#queueEngine(run);
+    }
+    if (this.#engineOn) return null;
+    this.#engineOn = true;
+    if (this.#standby) {
+      this.#standby = false;
+      this.#setState("starting");
+    }
+    return this.#queueEngine(run);
+  }
+  /** `#applyLine` from an event — nobody to hand a failure to, and `#engineStartFailed` has reported it. */
+  #syncLine() {
+    void this.#applyLine()?.catch(() => {
+    });
+  }
+  /**
+   * Brings the engine to what the line wants (`#engineOn`) once every step already queued has run — and does
+   * nothing when it is already there: the line can flip twice while a start is still running, and the stop
+   * and start queued meanwhile must not take the engine (and the softphone's state) down and up for nothing.
+   * Nothing at all once `stop()` has run since `run` was read: a stopped softphone's engine is `stop()`'s
+   * alone. Rejects with a failed start's cause; the queue itself never rejects, so one failure blocks nothing.
+   */
+  #queueEngine(run) {
+    const step = this.#engineSteps.then(async () => {
+      if (run !== this.#run || this.#engineOn === this.#engineRunning) return;
+      this.#engineRunning = this.#engineOn;
+      if (this.#engineRunning) await this.#startEngine(run);
+      else await this.#engine.stop();
+    });
+    this.#engineSteps = step.catch(() => {
+    });
+    return step;
+  }
+  /** Resolves when the engine started — or when its failure is being retried on its own (§4.6). */
+  async #startEngine(run) {
+    const reported = this.#lastError;
+    try {
+      await this.#engine.start();
+      if (run === this.#run) this.#startRetries = 0;
+    } catch (cause) {
+      if (run === this.#run && this.#engineStartFailed(cause, reported)) return;
+      throw cause;
+    }
+  }
+  /**
+   * An engine start the line asked for failed. Kept as it was, this softphone would stay the owner on the
+   * server — `starting`, its presence socket renewing the line — with no push socket anywhere: nobody would
+   * listen. So it gives the line up the ordinary way, by closing its presence socket without a goodbye (the
+   * phone was not switched off): the server hands the line on after its grace (R4).
+   *
+   * Then it depends on why (incoming-call-reliability.md §4.6, F5):
+   *   - **a passing failure** (a 5xx, the network, a timeout — `transientStartFailure`) is attempted again on its
+   *     own, after a backoff, as `reconnecting`, with no error gate. Found live: a voice token answered 500 after
+   *     10 s left a background tab `offline` for good, and every call was lost until someone pressed "Reintentar".
+   *     Returns `true`.
+   *   - **anything else** (a refused credential, no extension) is reported like any engine failure —
+   *     `SoftphoneEvent.Error` and `lastError`, which is the widget's error gate and its "Reintentar" (`stop()`
+   *     then `start()`, which asks for the line again) — and nothing retries on its own. Returns `false`.
+   */
+  #engineStartFailed(cause, reportedBefore) {
+    this.#engineOn = false;
+    this.#engineRunning = false;
+    this.#lineMode = "off";
+    const transient = this.#destroyed ? null : transientStartFailure(cause);
+    this.#stopPresence();
+    if (transient) {
+      this.#scheduleStartRetry(transient.retryAfterMs, cause);
+      this.#setState("reconnecting");
+      return true;
+    }
+    if (this.#lastError === reportedBefore) {
+      this.#onError(isSoftphoneError(cause) && isFatal(cause) ? cause : createError("net/transport-failed", cause));
+    }
+    this.#setState("offline");
+    return false;
+  }
+  /**
+   * The next attempt, after the shared backoff (1 s doubling to 30 s, jittered — the presence socket's own) and
+   * never before a `Retry-After` the failure carried. A plain timer: in a hidden tab it can stretch to about a
+   * minute, which is why the browser coming back `online`, or the tab becoming visible, attempts at once
+   * (`watchWake`). One warning per streak, so a console says what is going on without filling up.
+   */
+  #scheduleStartRetry(retryAfterMs, cause) {
+    this.#startRetries += 1;
+    const wait = Math.max(backoffDelayMs(this.#startRetries), retryAfterMs);
+    if (this.#startRetries === 1) {
+      console.warn("[softphone] the phone could not start; it keeps trying on its own", cause);
+    }
+    this.#startRetryNotBefore = Date.now() + retryAfterMs;
+    if (this.#startRetryTimer !== null) clearTimeout(this.#startRetryTimer);
+    const run = this.#run;
+    this.#startRetryTimer = setTimeout(() => void this.#retryStart(run), wait);
+    this.#unwatchWake ??= watchWake(() => this.#wakeStartRetry());
+  }
+  /** The pending attempt, now — unless a `Retry-After` says not yet, in which case it moves up to that moment. */
+  #wakeStartRetry() {
+    if (this.#startRetryTimer === null) return;
+    const run = this.#run;
+    clearTimeout(this.#startRetryTimer);
+    const wait = this.#startRetryNotBefore - Date.now();
+    if (wait > 0) {
+      this.#startRetryTimer = setTimeout(() => void this.#retryStart(run), wait);
+      return;
+    }
+    void this.#retryStart(run);
+  }
+  /** The wait and the wake-ups go; the streak's count stays (the next failure doubles on from it). */
+  #clearStartRetryWait() {
+    if (this.#startRetryTimer !== null) clearTimeout(this.#startRetryTimer);
+    this.#startRetryTimer = null;
+    this.#unwatchWake?.();
+    this.#unwatchWake = null;
+  }
+  #cancelStartRetry() {
+    this.#clearStartRetryWait();
+    this.#startRetries = 0;
+  }
+  /**
+   * One attempt: what "Reintentar" does after its `stop()`, minus the goodbye and the leadership (both kept) —
+   * the presence socket opens again and its `hello` asks for the line, the line decides (`standby` if it went
+   * elsewhere meanwhile, as at any start), and the engine starts. Without the goodbye, an attempt inside the
+   * server's 10 s grace gets the line straight back. Never for a softphone stopped since it was scheduled.
+   */
+  async #retryStart(run) {
+    this.#clearStartRetryWait();
+    if (this.#destroyed || run !== this.#run || !this.#startedHere || !this.#isLeader) return;
+    const decision = this.#openStartDecision();
+    try {
+      this.#lineMode = "deciding";
+      this.#setState("starting");
+      if (this.#presenceWatch && this.#line === "unknown") await this.#waitForFirstLine();
+      if (this.#destroyed || run !== this.#run) return;
+      this.#lineMode = "on";
+      const engineStart = this.#applyLine();
+      if (!engineStart) this.#startRetries = 0;
+      decision.end();
+      await engineStart?.catch(() => {
+      });
+    } finally {
+      decision.end();
+    }
+  }
+  /** `start()`'s decision (`#startDecision`): ended once, by whichever comes first — the decision or its end. */
+  #openStartDecision() {
+    let resolve;
+    const promise = new Promise((r) => {
+      resolve = r;
+    });
+    const decision = {
+      promise,
+      end: () => {
+        resolve();
+        if (this.#startDecision === decision) this.#startDecision = null;
+      }
+    };
+    this.#startDecision = decision;
+    return decision;
+  }
+  /**
+   * `start()`'s wait for the server's first word on the line — released by that word, by a source that
+   * will never say it, by the watch going away (`stop()` among them), or after `LINE_ANSWER_TIMEOUT_MS`.
+   */
+  #waitForFirstLine() {
+    return new Promise((resolve) => {
+      const release = () => {
+        clearTimeout(timer);
+        if (this.#releaseFirstLine === release) this.#releaseFirstLine = null;
+        resolve();
+      };
+      const timer = setTimeout(release, LINE_ANSWER_TIMEOUT_MS);
+      this.#releaseFirstLine = release;
+    });
+  }
+  #onLine(update) {
+    this.#cancelLineLapse();
+    this.#setLine(update.state, update.state === "here" ? null : update.where);
+    if (this.#releaseFirstLine) this.#releaseFirstLine();
+    else this.#syncLine();
+    if (update.state === "here") this.#settleClaim();
+  }
+  #onClaimResult(result) {
+    if (result.ok) {
+      if (this.#line === "here") this.#settleClaim();
+      return;
+    }
+    this.#settleClaim(createError(result.reason === "on_call" ? "line/claim-refused" : "line/unavailable"));
+  }
+  /**
+   * The presence socket dropped; the watch is reconnecting. A claim sent on it will never be answered, so
+   * it fails now rather than on its timeout. What the server said about the line holds for `LINE_LAPSE_MS`
+   * — a reconnect is normally answered well inside that — and then stops counting: `unknown`, which a
+   * waiting softphone answers by listening again.
+   */
+  #onPresenceDisconnect() {
+    this.#engine.noteOffer?.(null);
+    this.#settleClaim(createError("line/unavailable"));
+    if (this.#line === "unknown" || this.#lineLapseTimer !== null) return;
+    this.#lineLapseTimer = setTimeout(() => {
+      this.#lineLapseTimer = null;
+      this.#setLine("unknown", null);
+      this.#syncLine();
+    }, LINE_LAPSE_MS);
+  }
+  #cancelLineLapse() {
+    if (this.#lineLapseTimer === null) return;
+    clearTimeout(this.#lineLapseTimer);
+    this.#lineLapseTimer = null;
+  }
+  /**
+   * The presence watch is gone, so nothing the server said about the line holds any more: it reads
+   * `unknown`, and every wait on it ends. Not followed by `#applyLine` — this runs inside a state change
+   * (`#syncPresenceWatch`) or a stop, and a softphone whose watch is gone is not in `standby` anyway: that
+   * state keeps the watch.
+   */
+  #forgetLine() {
+    this.#cancelLineLapse();
+    this.#releaseFirstLine?.();
+    this.#settleClaim(createError("line/unavailable"));
+    this.#setLine("unknown", null);
+    this.#setLineClaim("idle");
+  }
+  #setLine(line, where) {
+    if (line === "here") this.#setLineClaim("idle");
+    if (line === this.#line && where === this.#lineWhere) return;
+    this.#line = line;
+    this.#lineWhere = where;
+    this.emit("lineChanged" /* LineChanged */, { line, where });
+  }
+  #setLineClaim(claim) {
+    if (claim === this.#lineClaim) return;
+    this.#lineClaim = claim;
+    this.emit("lineClaimChanged" /* LineClaimChanged */, { claim });
+  }
+  #openClaim() {
+    let settle;
+    const promise = new Promise((resolve, reject) => {
+      const timer = setTimeout(() => this.#settleClaim(createError("line/unavailable")), LINE_CLAIM_TIMEOUT_MS);
+      settle = (error) => {
+        clearTimeout(timer);
+        if (error) reject(error);
+        else resolve();
+      };
+    });
+    this.#claim = { promise, settle };
+    this.#setLineClaim("claiming");
+    return promise;
+  }
+  /** Ends the claim in flight, if any — resolved without `error`, rejected with it. */
+  #settleClaim(error) {
+    const claim = this.#claim;
+    if (!claim) return;
+    this.#claim = null;
+    this.#setLineClaim(!error ? "idle" : error.code === "line/claim-refused" ? "refused" : "failed");
+    claim.settle(error);
+  }
   /**
    * Phase A (transfer outcome relay, `docs/specs/transfer-outcome-relay.md`) — `CallImpl.transfer()`'s
    * internal seam calls this. No-ops entirely when no Coventia backend is configured (`sources` is
@@ -929,6 +1471,7 @@ var SoftphoneImpl = class extends Emitter {
 };
 
 // src/core/default-provider.ts
+var MAX_PENDING_OFFERS = 20;
 var LazyRelay = class {
   #listeners = /* @__PURE__ */ new Set();
   #realOff = /* @__PURE__ */ new Map();
@@ -951,16 +1494,20 @@ var LazyRelay = class {
 function defaultZadarmaEngine(config) {
   let real = null;
   let pending = null;
+  let run = 0;
   const incoming = new LazyRelay();
   const stateChange = new LazyRelay();
   const error = new LazyRelay();
+  let pendingOffers = [];
   function load() {
-    pending ??= import('./zadarma-engine-L5DEFXUS.js').then(({ createZadarmaEngine }) => {
+    pending ??= import('./zadarma-engine-VYIXLBQG.js').then(({ createZadarmaEngine }) => {
       const engine = createZadarmaEngine(config);
       incoming.attach({ on: (l) => engine.onIncoming(l) });
       stateChange.attach({ on: (l) => engine.onStateChange(l) });
       error.attach({ on: (l) => engine.onError?.(l) ?? (() => {
       }) });
+      for (const offer of pendingOffers) engine.noteOffer?.(offer);
+      pendingOffers = [];
       real = engine;
       return engine;
     }).catch((cause) => {
@@ -974,23 +1521,52 @@ function defaultZadarmaEngine(config) {
       return real?.state ?? "stopped";
     },
     async start() {
-      await (await load()).start();
+      const current = run;
+      const engine = await load();
+      if (current !== run) return;
+      await engine.start();
     },
     async stop() {
+      run += 1;
       if (real) await real.stop();
     },
     async placeCall(destination, options) {
-      return (await load()).placeCall(destination, options);
+      const current = run;
+      const engine = await load();
+      if (current !== run) throw createError("engine/not-started");
+      return engine.placeCall(destination, options);
     },
     onIncoming: (listener) => incoming.subscribe(listener),
     onStateChange: (listener) => stateChange.subscribe(listener),
-    onError: (listener) => error.subscribe(listener)
+    onError: (listener) => error.subscribe(listener),
+    /*
+     * Relayed like the listeners above, or the decline guard on this — the default — path would never hear the
+     * backend (incoming-call-reliability.md §4.4). Before the engine loads, kept (a few) rather than loading it:
+     * a softphone in `standby` hears offers without ever starting an engine.
+     */
+    noteOffer: (offer) => {
+      if (real) {
+        real.noteOffer?.(offer);
+        return;
+      }
+      pendingOffers.push(offer);
+      if (pendingOffers.length > MAX_PENDING_OFFERS) pendingOffers.shift();
+    }
   };
 }
 
 // src/core/create.ts
 function createSoftphone(config) {
-  return new SoftphoneImpl(resolveEngine(config), config);
+  const resolved = withNormalizedBases(config);
+  return new SoftphoneImpl(resolveEngine(resolved), resolved);
+}
+function withNormalizedBases(config) {
+  const { apiBase, coventia } = config;
+  return {
+    ...config,
+    ...apiBase ? { apiBase: normalizeApiBase(apiBase) } : {},
+    ...coventia?.baseUrl ? { coventia: { ...coventia, baseUrl: normalizeApiBase(coventia.baseUrl) } } : {}
+  };
 }
 function resolveEngine(config) {
   if (config.provider !== void 0) {
@@ -1015,7 +1591,7 @@ function isCallEngine(value) {
 }
 
 // src/index.ts
-var VERSION = "0.4.0";
+var VERSION = "0.5.1";
 
 export { CALL_TRANSITIONS, INITIAL_STATES, VERSION, canTransition, createSoftphone, isTerminal };
 //# sourceMappingURL=index.js.map