@coventia/softphone 0.4.0 → 0.5.0

package/dist/index.cjs

@@ -316,6 +316,16 @@ function coventiaSources(config) {
               if (ws.readyState !== WS.OPEN) return;
               ws.send(JSON.stringify({ type: "bye" }));
             },
+            // `line: true` is what makes the server treat this socket as taking part in the line owner;
+            // without it (or with an id it rejects) the `hello` is ignored, as an older SDK's would be.
+            hello: (clientId) => {
+              if (ws.readyState !== WS.OPEN) return;
+              ws.send(JSON.stringify({ type: "hello", clientId, line: true }));
+            },
+            claimLine: () => {
+              if (ws.readyState !== WS.OPEN) return;
+              ws.send(JSON.stringify({ type: "line-claim" }));
+            },
             close: () => {
               ws.onclose = null;
               ws.onerror = null;
@@ -335,6 +345,12 @@ function coventiaSources(config) {
             callbacks.onSnapshot((msg.agents ?? []).map(toPresenceEntry));
           } else if (msg.type === "delta" && msg.agent) {
             callbacks.onDelta(toPresenceEntry(msg.agent));
+          } else if (msg.type === "line" && (msg.state === "here" || msg.state === "elsewhere")) {
+            callbacks.onLine?.({ state: msg.state, where: msg.state === "here" ? null : toLineLocation(msg.where) });
+          } else if (msg.type === "line-claim-result") {
+            callbacks.onClaimResult?.(
+              msg.ok === true ? { ok: true } : { ok: false, reason: typeof msg.reason === "string" ? msg.reason : "unavailable" }
+            );
           }
         };
         ws.onclose = () => {
@@ -478,7 +494,7 @@ function coventiaSources(config) {
     outboundNumbers
   };
 }
-var toContact, toDirection, otherParty, isMissed, toOutcome, toDate, toTransferOutcome, toPresenceState, toPresenceEntry, toWebSocketUrl;
+var toContact, toDirection, otherParty, isMissed, toOutcome, toDate, toTransferOutcome, toPresenceState, toPresenceEntry, toLineLocation, toWebSocketUrl;
 var init_sources2 = __esm({
   "src/coventia/sources.ts"() {
     init_sources();
@@ -527,6 +543,7 @@ var init_sources2 = __esm({
       name: row.name ?? null,
       state: toPresenceState(row.state)
     });
+    toLineLocation = (raw) => raw === "desktop" || raw === "browser" ? raw : null;
     toWebSocketUrl = (httpUrl) => httpUrl.replace(/^http/, "ws").replace(/\/+$/, "");
   }
 });
@@ -679,6 +696,19 @@ var init_errors = __esm({
         message: "The provider does not support this operation.",
         solution: "Guard the UI on the operation before offering it."
       },
+      // ── Line owner (docs/specs/line-owner.md §5) ────────────────────────────────
+      // What `takeLine()` rejects with — and `call()` from `standby`, which takes the line first. Never
+      // emitted on `SoftphoneEvent.Error`: the promise IS the answer, and nothing about the phone is broken.
+      "line/claim-refused": {
+        fatal: false,
+        message: "The line was not moved here: the user is on a call on the softphone that has it.",
+        solution: "Nothing to fix. The line never moves during a call; take it again once that call has ended. Incoming calls keep ringing where they ring now."
+      },
+      "line/unavailable": {
+        fatal: false,
+        message: "The line could not be taken: nothing decided where it is.",
+        solution: "The presence connection is down, the backend predates the line owner, or it did not answer in time. Retry in a moment; incoming calls keep ringing where they ring now."
+      },
       // ── Provider ────────────────────────────────────────────────────────────────
       "provider/provision-failed": {
         fatal: true,
@@ -978,9 +1008,22 @@ var init_ua = __esm({
       provider;
       factory;
       #state = "stopped";
+      /**
+       * Which `start()`…`stop()` cycle this is — bumped by `stop()`, which ends one. Everything that awaits
+       * and then acts (builds a UA, subscribes to the signal, sets the state) captures it first and gives up
+       * if a stop has happened since. Not bumped by `start()`: that would cancel work begun just before it,
+       * such as a call placed while the softphone is still starting.
+       *
+       * Without it a stopped phone came back to life: a provisioning or a signal connect still in flight
+       * when `stop()` ran finished afterwards and REGISTERed — and since the PBX routes a call to whichever
+       * client registered last, it quietly took calls from the user's other device while its UI said off.
+       */
+      #run = 0;
       #ua = null;
       /** In-flight `#createUA()`. THE concurrency guard — see `#ensureUA`. */
       #uaInFlight = null;
+      /** Calls waiting for the current UA to register (`#callWhenRegistered`), failed by `#teardownUA`. */
+      #awaitingRegistration = /* @__PURE__ */ new Set();
       #domain = "";
       #activeCall = null;
       /**
@@ -1063,14 +1106,25 @@ var init_ua = __esm({
         for (const listener of [...this.#errorListeners]) listener(error);
       }
       async start() {
+        const run = this.#run;
         this.#setState("starting");
         if (this.provider.registrationMode === "persistent") {
-          await this.#ensureUA();
+          try {
+            await this.#ensureUA();
+          } catch (cause) {
+            if (run === this.#run) throw cause;
+          }
+          if (run !== this.#run) return;
           this.#setState("online");
         } else {
           const signal = this.provider.incomingSignal;
           if (signal) {
-            await signal.connect();
+            try {
+              await signal.connect();
+            } catch (cause) {
+              if (run === this.#run) throw cause;
+            }
+            if (run !== this.#run) return;
             this.#signalUnsub = signal.onSignal(() => void this.#onIncomingSignal());
             this.#signalConnectionUnsub = signal.onConnectionChange?.(
               (connected) => this.#setState(connected ? "online" : "offline")
@@ -1080,6 +1134,7 @@ var init_ua = __esm({
         }
       }
       async stop() {
+        this.#run += 1;
         this.#clearNoInviteTimer();
         this.#signalUnsub?.();
         this.#signalUnsub = null;
@@ -1098,11 +1153,12 @@ var init_ua = __esm({
       async #onIncomingSignal() {
         if (this.now() < this.#rejectGuardUntil) return;
         if (this.#activeCall) return;
+        const run = this.#run;
         try {
           await this.#ensureUA();
           this.#armNoInviteTeardown();
         } catch {
-          this.#teardownUA();
+          if (run === this.#run) this.#teardownUA();
         }
       }
       #armNoInviteTeardown() {
@@ -1164,12 +1220,16 @@ var init_ua = __esm({
        */
       async #ensureUA() {
         if (this.#ua) return this.#ua;
-        this.#uaInFlight ??= this.#createUA().finally(() => {
-          this.#uaInFlight = null;
-        });
+        if (!this.#uaInFlight) {
+          const inFlight = this.#createUA().finally(() => {
+            if (this.#uaInFlight === inFlight) this.#uaInFlight = null;
+          });
+          this.#uaInFlight = inFlight;
+        }
         return this.#uaInFlight;
       }
       async #createUA() {
+        const run = this.#run;
         const factory = await this.#resolveFactory();
         let credentials;
         try {
@@ -1179,17 +1239,28 @@ var init_ua = __esm({
           else this.#reportError("provider/provision-failed", cause);
           throw cause;
         }
+        if (run !== this.#run) throw createError("engine/not-started");
         this.#domain = domainOf(credentials);
         const config = this.#uaConfig(credentials, factory);
         const ua = factory.createUA(config);
-        ua.on("newRTCSession", ({ session, originator }) => this.#onNewSession(session, originator));
+        ua.on("newRTCSession", ({ session, originator }) => {
+          if (ua !== this.#ua) {
+            if (originator === "remote") session.terminate({ status_code: 486, reason_phrase: "Busy Here" });
+            return;
+          }
+          this.#onNewSession(session, originator);
+        });
         ua.on("disconnected", ({ error }) => {
+          if (ua !== this.#ua) return;
           if (!error) return;
           this.#setState("reconnecting");
           this.#reportError("net/transport-failed", error);
         });
-        ua.on("connected", () => this.#setState("online"));
+        ua.on("connected", () => {
+          if (ua === this.#ua) this.#setState("online");
+        });
         ua.on("registrationFailed", (e) => {
+          if (run !== this.#run) return;
           const detail = e;
           this.#reportError("net/registration-failed", {
             cause: detail?.cause,
@@ -1197,7 +1268,7 @@ var init_ua = __esm({
             domain: this.#domain,
             hint: "A bare 401 with no auth challenge usually means the registrar is in the wrong datacenter (SPEC \xA73.1)."
           });
-          this.#teardownUA();
+          if (ua === this.#ua) this.#teardownUA();
           void this.#refreshSignal();
         });
         this.#ua = ua;
@@ -1224,6 +1295,7 @@ var init_ua = __esm({
       #teardownUA() {
         this.#uaInFlight = null;
         if (!this.#ua) return;
+        for (const fail of [...this.#awaitingRegistration]) fail();
         try {
           this.#ua.terminateSessions({ status_code: 487 });
           this.#ua.stop();
@@ -1247,8 +1319,27 @@ var init_ua = __esm({
       #callWhenRegistered(ua, target) {
         const options = { mediaConstraints: buildAudioConstraints(this.#inputDeviceId), pcConfig: PC_CONFIG };
         if (ua.isRegistered()) return Promise.resolve(ua.call(target, options));
-        return new Promise((resolve) => {
-          ua.on("registered", () => resolve(ua.call(target, options)));
+        const run = this.#run;
+        return new Promise((resolve, reject) => {
+          let settled = false;
+          const fail = () => {
+            if (settled) return;
+            settled = true;
+            this.#awaitingRegistration.delete(fail);
+            reject(createError(run === this.#run ? "call/failed" : "engine/not-started"));
+          };
+          this.#awaitingRegistration.add(fail);
+          ua.on("registered", () => {
+            if (settled) return;
+            if (ua !== this.#ua) return fail();
+            settled = true;
+            this.#awaitingRegistration.delete(fail);
+            try {
+              resolve(ua.call(target, options));
+            } catch (cause) {
+              reject(cause);
+            }
+          });
         });
       }
       #wrapCall(session) {
@@ -1398,6 +1489,12 @@ var init_zadarma = __esm({
       #retryTimer;
       #unwatchBackground;
       #closed = false;
+      /**
+       * Bumped by `disconnect()`. An open or a rebuild still awaiting its key when the signal is disconnected
+       * must build nothing afterwards — and `#closed` alone cannot say so once a later `connect()` (stop, then
+       * start again) has reset it: the late socket was built beside the new one, and nothing ever closed it.
+       */
+      #run = 0;
       #listeners = /* @__PURE__ */ new Set();
       #connectionListeners = /* @__PURE__ */ new Set();
       async connect() {
@@ -1407,8 +1504,9 @@ var init_zadarma = __esm({
         await this.#open();
       }
       async #open() {
+        const run = this.#run;
         const { key, sip, keyExpiresAt } = await this.deps.fetchKey();
-        if (this.#closed) return;
+        if (run !== this.#run) return;
         const socket = this.deps.createPushSocket(buildPushUrl(key, sip));
         this.#socket = socket;
         this.#attach(socket);
@@ -1503,9 +1601,10 @@ var init_zadarma = __esm({
           return;
         }
         this.#rebuilding = true;
+        const run = this.#run;
         try {
           const { key, sip, keyExpiresAt } = await this.deps.fetchKey();
-          if (this.#closed) return;
+          if (run !== this.#run) return;
           const swapped = await new Promise((resolve) => {
             const socket = this.deps.createPushSocket(buildPushUrl(key, sip));
             this.#candidate = socket;
@@ -1558,6 +1657,7 @@ var init_zadarma = __esm({
       }
       disconnect() {
         this.#closed = true;
+        this.#run += 1;
         this.#stopPings();
         clearTimeout(this.#refreshTimer);
         this.#refreshTimer = void 0;
@@ -1801,6 +1901,20 @@ var init_zadarma_browser = __esm({
   }
 });
 
+// src/core/api-base.ts
+function normalizeApiBase(url) {
+  const trimmed = url.replace(/\/+$/, "");
+  if (!trimmed.endsWith("/api/v1")) return trimmed;
+  console.warn(
+    "[softphone] apiBase should be Coventia's domain only, without /api/v1. Ignoring the /api/v1 suffix."
+  );
+  return trimmed.slice(0, -"/api/v1".length).replace(/\/+$/, "");
+}
+var init_api_base = __esm({
+  "src/core/api-base.ts"() {
+  }
+});
+
 // src/transports/zadarma-engine.ts
 var zadarma_engine_exports = {};
 __export(zadarma_engine_exports, {
@@ -1808,7 +1922,11 @@ __export(zadarma_engine_exports, {
 });
 function createZadarmaEngine(config) {
   const provider = new ZadarmaProvider(
-    makeZadarmaBrowserDeps({ ...config, tokenSource: cachedTokenSource(config.tokenSource) })
+    makeZadarmaBrowserDeps({
+      ...config,
+      apiBase: normalizeApiBase(config.apiBase),
+      tokenSource: cachedTokenSource(config.tokenSource)
+    })
   );
   return new SipCallEngine(provider, loadJsSipFactory);
 }
@@ -1819,6 +1937,7 @@ var init_zadarma_engine = __esm({
     init_zadarma();
     init_zadarma_browser();
     init_token_cache();
+    init_api_base();
   }
 });
 
@@ -1882,6 +2001,8 @@ var SoftphoneEvent = /* @__PURE__ */ ((SoftphoneEvent2) => {
   SoftphoneEvent2["LeaderChanged"] = "leaderChanged";
   SoftphoneEvent2["TransferOutcome"] = "transferOutcome";
   SoftphoneEvent2["PresenceChanged"] = "presenceChanged";
+  SoftphoneEvent2["LineChanged"] = "lineChanged";
+  SoftphoneEvent2["LineClaimChanged"] = "lineClaimChanged";
   return SoftphoneEvent2;
 })(SoftphoneEvent || {});
 var CallEvent = /* @__PURE__ */ ((CallEvent2) => {
@@ -2171,13 +2292,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;
@@ -2192,7 +2315,7 @@ function webLocksTabLock(lockName = LOCK_NAME) {
         releaseHold = void 0;
         resolve();
       } else {
-        controller.abort();
+        controller?.abort();
       }
     }
   };
@@ -2277,13 +2400,19 @@ function startTransferWatch(params) {
 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,
+    onLineUnsupported,
+    onConnectFailed,
+    onDisconnect,
     setTimeout: scheduleTimeout = globalThis.setTimeout,
     clearTimeout: cancelTimeout = globalThis.clearTimeout,
     random = Math.random
@@ -2294,6 +2423,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) => {
@@ -2310,6 +2441,12 @@ 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;
@@ -2338,10 +2475,23 @@ 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);
         }
       });
     } catch {
-      if (!stopped) scheduleReconnect();
+      if (stopped) return;
+      scheduleReconnect();
+      onConnectFailed?.();
       return;
     }
     if (stopped) {
@@ -2351,23 +2501,64 @@ 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
 init_errors();
 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 = [];
@@ -2475,6 +2666,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;
@@ -2499,6 +2692,52 @@ 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;
   /**
    * `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
@@ -2516,7 +2755,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() {
@@ -2534,6 +2775,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;
   }
@@ -2549,15 +2799,33 @@ 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.#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();
@@ -2579,16 +2847,50 @@ 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.#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) {
@@ -2617,6 +2919,7 @@ var SoftphoneImpl = class extends Emitter {
         this.#activeCall = null;
         this.emit("activeCallChanged" /* ActiveCallChanged */, { call: null });
         this.#syncCallState();
+        this.#syncLine();
       }
     });
     if (this.#resolveContact) {
@@ -2646,7 +2949,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());
@@ -2667,17 +2971,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) {
@@ -2686,13 +2995,22 @@ 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),
+        // 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 {
@@ -2707,19 +3025,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();
@@ -2728,6 +3051,7 @@ var SoftphoneImpl = class extends Emitter {
     this.#presenceWatch = null;
     this.#presenceAgents = [];
     this.emit("presenceChanged" /* PresenceChanged */, { agents: [] });
+    this.#forgetLine();
   }
   /**
    * A DELIBERATE stop (`stop()` / `destroy()`): say any call is over, then say goodbye, so the backend drops
@@ -2737,6 +3061,195 @@ 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;
+  }
+  async #startEngine(run) {
+    const reported = this.#lastError;
+    try {
+      await this.#engine.start();
+    } catch (cause) {
+      if (run === this.#run) this.#engineStartFailed(cause, reported);
+      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). The failure 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). Nothing retries on its own.
+   */
+  #engineStartFailed(cause, reportedBefore) {
+    this.#engineOn = false;
+    this.#engineRunning = false;
+    this.#lineMode = "off";
+    if (this.#lastError === reportedBefore) {
+      this.#onError(isSoftphoneError(cause) && isFatal(cause) ? cause : createError("net/transport-failed", cause));
+    }
+    this.#stopPresence();
+    this.#setState("offline");
+  }
+  /** `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.#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
@@ -2785,6 +3298,7 @@ var SoftphoneImpl = class extends Emitter {
 };
 
 // src/core/default-provider.ts
+init_errors();
 var LazyRelay = class {
   #listeners = /* @__PURE__ */ new Set();
   #realOff = /* @__PURE__ */ new Map();
@@ -2807,6 +3321,7 @@ 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();
@@ -2830,13 +3345,20 @@ 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),
@@ -2845,8 +3367,18 @@ function defaultZadarmaEngine(config) {
 }
 
 // src/core/create.ts
+init_api_base();
 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) {
@@ -2873,7 +3405,7 @@ function isCallEngine(value) {
 // src/index.ts
 init_errors();
 init_outbound_numbers();
-var VERSION = "0.4.0";
+var VERSION = "0.5.0";
 
 exports.CALL_TRANSITIONS = CALL_TRANSITIONS;
 exports.CallEvent = CallEvent;