@coventia/softphone 0.1.0

package/dist/react/index.cjs

@@ -0,0 +1,138 @@
+'use strict';
+
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/react/context.tsx
+var SoftphoneContext = react.createContext(null);
+function SoftphoneProvider({ softphone, children }) {
+  return /* @__PURE__ */ jsxRuntime.jsx(SoftphoneContext.Provider, { value: softphone, children });
+}
+function useSoftphone() {
+  const softphone = react.useContext(SoftphoneContext);
+  if (!softphone) {
+    throw new Error("useSoftphone() must be used within a <SoftphoneProvider>.");
+  }
+  return softphone;
+}
+function useLastError() {
+  const phone = useSoftphone();
+  return react.useSyncExternalStore(
+    react.useCallback(
+      (cb) => {
+        const offError = phone.on("error" /* Error */, () => cb());
+        const offState = phone.on("stateChanged" /* StateChanged */, () => cb());
+        return () => {
+          offError();
+          offState();
+        };
+      },
+      [phone]
+    ),
+    react.useCallback(() => phone.lastError, [phone])
+  );
+}
+function useSoftphoneState() {
+  const phone = useSoftphone();
+  return react.useSyncExternalStore(
+    react.useCallback((cb) => phone.on("stateChanged" /* StateChanged */, () => cb()), [phone]),
+    react.useCallback(() => phone.state, [phone])
+  );
+}
+function useIsLeader() {
+  const phone = useSoftphone();
+  return react.useSyncExternalStore(
+    react.useCallback((cb) => phone.on("leaderChanged" /* LeaderChanged */, () => cb()), [phone]),
+    react.useCallback(() => phone.isLeader, [phone])
+  );
+}
+function useActiveCall() {
+  const phone = useSoftphone();
+  return react.useSyncExternalStore(
+    react.useCallback((cb) => phone.on("activeCallChanged" /* ActiveCallChanged */, () => cb()), [phone]),
+    react.useCallback(() => phone.activeCall, [phone])
+  );
+}
+var CALL_EVENTS = [
+  "stateChanged" /* StateChanged */,
+  "muted" /* Muted */,
+  "held" /* Held */,
+  "unheld" /* Unheld */,
+  "remotePartyUpdated" /* RemotePartyUpdated */,
+  "remoteStream" /* RemoteStream */,
+  "ended" /* Ended */
+];
+function useCall(call) {
+  const cache = react.useRef(null);
+  const subscribe = react.useCallback(
+    (cb) => {
+      if (!call) return () => {
+      };
+      const unsubs = CALL_EVENTS.map(
+        (event) => call.on(event, () => {
+          cache.current = null;
+          cb();
+        })
+      );
+      return () => {
+        for (const off of unsubs) off();
+      };
+    },
+    [call]
+  );
+  const getSnapshot = react.useCallback(() => {
+    if (!call) return null;
+    if (cache.current?.call === call) return cache.current.view;
+    const view = {
+      state: call.state,
+      isMuted: call.isMuted,
+      isOnHold: call.isOnHold,
+      remote: call.remote,
+      remoteStream: call.remoteStream,
+      answeredAt: call.answeredAt
+    };
+    cache.current = { call, view };
+    return view;
+  }, [call]);
+  return react.useSyncExternalStore(subscribe, getSnapshot);
+}
+function useDevices() {
+  const phone = useSoftphone();
+  const cache = react.useRef(null);
+  const subscribe = react.useCallback(
+    (cb) => phone.on("deviceChange" /* DeviceChange */, () => {
+      cache.current = null;
+      cb();
+    }),
+    [phone]
+  );
+  const getSnapshot = react.useCallback(() => {
+    const audio = phone.audio;
+    if (cache.current?.audio === audio) return cache.current.view;
+    const view = {
+      inputs: audio.inputs,
+      outputs: audio.outputs,
+      currentInputId: audio.currentInputId,
+      currentOutputId: audio.currentOutputId,
+      canSelectOutput: audio.canSelectOutput,
+      setInput: (deviceId) => audio.setInput(deviceId),
+      setOutput: (deviceId) => audio.setOutput(deviceId),
+      setRingtoneOutput: (deviceId) => audio.setRingtoneOutput(deviceId),
+      refresh: () => audio.refresh()
+    };
+    cache.current = { audio, view };
+    return view;
+  }, [phone]);
+  return react.useSyncExternalStore(subscribe, getSnapshot);
+}
+
+exports.SoftphoneProvider = SoftphoneProvider;
+exports.useActiveCall = useActiveCall;
+exports.useCall = useCall;
+exports.useDevices = useDevices;
+exports.useIsLeader = useIsLeader;
+exports.useLastError = useLastError;
+exports.useSoftphone = useSoftphone;
+exports.useSoftphoneState = useSoftphoneState;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/react/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/react/context.tsx","../../src/react/hooks.ts"],"names":["createContext","useContext","useSyncExternalStore","useCallback","useRef"],"mappings":"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","file":"index.cjs","sourcesContent":["import { createContext, useContext, type ReactNode } from 'react';\r\nimport type { Softphone } from '../core/softphone.js';\r\n\r\n/**\r\n * The provider takes an INSTANCE the host constructed — not config props.\r\n *\r\n * This is LiveKit's hard-won lesson (SPEC §5.1): they are deprecating their config-props\r\n * `<LiveKitRoom>` in favour of a provider that accepts an instance. Holding the `Softphone` above the\r\n * React tree lets the app own the connection, survive route changes and unmounts without dropping a\r\n * call, and unit-test the engine with no React at all. Config-props would rebuild the engine on\r\n * every prop change — catastrophic for something holding a live `RTCPeerConnection`.\r\n */\r\nconst SoftphoneContext = createContext<Softphone | null>(null);\r\n\r\nexport interface SoftphoneProviderProps {\r\n  readonly softphone: Softphone;\r\n  readonly children: ReactNode;\r\n}\r\n\r\nexport function SoftphoneProvider({ softphone, children }: SoftphoneProviderProps) {\r\n  return <SoftphoneContext.Provider value={softphone}>{children}</SoftphoneContext.Provider>;\r\n}\r\n\r\n/** The `Softphone` instance from context. Stable — does not re-render on state changes. */\r\nexport function useSoftphone(): Softphone {\r\n  const softphone = useContext(SoftphoneContext);\r\n  if (!softphone) {\r\n    throw new Error('useSoftphone() must be used within a <SoftphoneProvider>.');\r\n  }\r\n  return softphone;\r\n}\r\n","// Built-in, no shim: the peer floor is React 18 (SPEC §2.7), which ships useSyncExternalStore.\r\nimport { useCallback, useRef, useSyncExternalStore } from 'react';\r\nimport { useSoftphone } from './context.js';\r\nimport { SoftphoneEvent, CallEvent } from '../core/events.js';\r\nimport type { Call, CallState } from '../core/call.js';\r\nimport type { RemoteParty, SoftphoneState } from '../core/types.js';\r\nimport type { AudioDevices } from '../core/softphone.js';\r\nimport type { FatalSoftphoneError } from '../core/errors.js';\r\n\r\n/** Reactive softphone lifecycle state (`stopped` → `online` → …). */\r\n/**\r\n * The reason the phone cannot currently be used, or `null`.\r\n *\r\n * Reads `softphone.lastError`, which is STATE rather than only an event — the widget is usually\r\n * opened *after* something broke, and a listener mounted at that point would have missed the event\r\n * entirely and rendered a dialpad with no explanation.\r\n *\r\n * Re-reads on both channels because both can change it: `Error` sets it, and `StateChanged` clears it\r\n * on reaching `online`. Subscribing to only the first would leave a stale gate on screen after the\r\n * phone recovered.\r\n */\r\nexport function useLastError(): FatalSoftphoneError | null {\r\n  const phone = useSoftphone();\r\n  return useSyncExternalStore(\r\n    useCallback(\r\n      (cb: () => void) => {\r\n        const offError = phone.on(SoftphoneEvent.Error, () => cb());\r\n        const offState = phone.on(SoftphoneEvent.StateChanged, () => cb());\r\n        return () => {\r\n          offError();\r\n          offState();\r\n        };\r\n      },\r\n      [phone],\r\n    ),\r\n    useCallback(() => phone.lastError, [phone]),\r\n  );\r\n}\r\n\r\nexport function useSoftphoneState(): SoftphoneState {\r\n  const phone = useSoftphone();\r\n  return useSyncExternalStore(\r\n    useCallback((cb: () => void) => phone.on(SoftphoneEvent.StateChanged, () => cb()), [phone]),\r\n    useCallback(() => phone.state, [phone]),\r\n  );\r\n}\r\n\r\n/**\r\n * Whether THIS tab is the one allowed to be reachable (`multi-tab-leader-election.md`). `false` by\r\n * default and while waiting for another open tab to release it — show your own \"active in another\r\n * tab\" state for that duration; the `/ui` widget already does.\r\n */\r\nexport function useIsLeader(): boolean {\r\n  const phone = useSoftphone();\r\n  return useSyncExternalStore(\r\n    useCallback((cb: () => void) => phone.on(SoftphoneEvent.LeaderChanged, () => cb()), [phone]),\r\n    useCallback(() => phone.isLeader, [phone]),\r\n  );\r\n}\r\n\r\n/**\r\n * The current call, or null. Re-renders when it changes — inbound, outbound, or ended.\r\n *\r\n * `phone.activeCall` returns a stable reference for a given call, so it is a safe snapshot.\r\n */\r\nexport function useActiveCall(): Call | null {\r\n  const phone = useSoftphone();\r\n  return useSyncExternalStore(\r\n    useCallback((cb: () => void) => phone.on(SoftphoneEvent.ActiveCallChanged, () => cb()), [phone]),\r\n    useCallback(() => phone.activeCall, [phone]),\r\n  );\r\n}\r\n\r\n/** An immutable snapshot of a call's reactive fields. */\r\nexport interface CallView {\r\n  readonly state: CallState;\r\n  readonly isMuted: boolean;\r\n  readonly isOnHold: boolean;\r\n  readonly remote: RemoteParty;\r\n  readonly remoteStream: MediaStream | null;\r\n  readonly answeredAt: Date | null;\r\n}\r\n\r\nconst CALL_EVENTS: readonly CallEvent[] = [\r\n  CallEvent.StateChanged,\r\n  CallEvent.Muted,\r\n  CallEvent.Held,\r\n  CallEvent.Unheld,\r\n  CallEvent.RemotePartyUpdated,\r\n  CallEvent.RemoteStream,\r\n  CallEvent.Ended,\r\n];\r\n\r\n/**\r\n * Reactive view of a specific call. Re-renders only when one of the call's own events fires — no\r\n * polling, no re-render storms.\r\n *\r\n * The snapshot is CACHED and invalidated only on an event, so `useSyncExternalStore` gets a stable\r\n * reference between changes (returning a fresh object every render would infinite-loop).\r\n */\r\nexport function useCall(call: Call | null): CallView | null {\r\n  const cache = useRef<{ call: Call; view: CallView } | null>(null);\r\n\r\n  const subscribe = useCallback(\r\n    (cb: () => void) => {\r\n      if (!call) return () => {};\r\n      const unsubs = CALL_EVENTS.map((event) =>\r\n        call.on(event, () => {\r\n          cache.current = null; // invalidate; getSnapshot rebuilds on the next read\r\n          cb();\r\n        }),\r\n      );\r\n      return () => {\r\n        for (const off of unsubs) off();\r\n      };\r\n    },\r\n    [call],\r\n  );\r\n\r\n  const getSnapshot = useCallback((): CallView | null => {\r\n    if (!call) return null;\r\n    if (cache.current?.call === call) return cache.current.view;\r\n    const view: CallView = {\r\n      state: call.state,\r\n      isMuted: call.isMuted,\r\n      isOnHold: call.isOnHold,\r\n      remote: call.remote,\r\n      remoteStream: call.remoteStream,\r\n      answeredAt: call.answeredAt,\r\n    };\r\n    cache.current = { call, view };\r\n    return view;\r\n  }, [call]);\r\n\r\n  return useSyncExternalStore(subscribe, getSnapshot);\r\n}\r\n\r\n/**\r\n * The audio device surface (`phone.audio`) — reactive. Re-renders on `SoftphoneEvent.DeviceChange`: a\r\n * device plugged/unplugged, or a selection changed (SPEC §7 Phase 2).\r\n *\r\n * The snapshot is CACHED and invalidated only on that event, same reasoning as `useCall`'s own\r\n * `CallView`: `phone.audio` is ONE stable object whose fields mutate in place, so returning it\r\n * directly would never change by reference and `useSyncExternalStore` would never re-render. A fresh\r\n * object, rebuilt only when something actually changed, is what makes this reactive without polling.\r\n */\r\nexport function useDevices(): AudioDevices {\r\n  const phone = useSoftphone();\r\n  const cache = useRef<{ audio: AudioDevices; view: AudioDevices } | null>(null);\r\n\r\n  const subscribe = useCallback(\r\n    (cb: () => void) =>\r\n      phone.on(SoftphoneEvent.DeviceChange, () => {\r\n        cache.current = null; // invalidate; getSnapshot rebuilds on the next read\r\n        cb();\r\n      }),\r\n    [phone],\r\n  );\r\n\r\n  const getSnapshot = useCallback((): AudioDevices => {\r\n    const audio = phone.audio;\r\n    if (cache.current?.audio === audio) return cache.current.view;\r\n    const view: AudioDevices = {\r\n      inputs: audio.inputs,\r\n      outputs: audio.outputs,\r\n      currentInputId: audio.currentInputId,\r\n      currentOutputId: audio.currentOutputId,\r\n      canSelectOutput: audio.canSelectOutput,\r\n      setInput: (deviceId) => audio.setInput(deviceId),\r\n      setOutput: (deviceId) => audio.setOutput(deviceId),\r\n      setRingtoneOutput: (deviceId) => audio.setRingtoneOutput(deviceId),\r\n      refresh: () => audio.refresh(),\r\n    };\r\n    cache.current = { audio, view };\r\n    return view;\r\n  }, [phone]);\r\n\r\n  return useSyncExternalStore(subscribe, getSnapshot);\r\n}\r\n"]}

package/dist/react/index.d.cts

@@ -0,0 +1,68 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { S as Softphone, A as AudioDevices } from '../softphone-DhuhcKCy.cjs';
+import { f as CallState, R as RemoteParty, a as Call, h as FatalSoftphoneError, o as SoftphoneState } from '../call-BTYlT2SU.cjs';
+
+interface SoftphoneProviderProps {
+    readonly softphone: Softphone;
+    readonly children: ReactNode;
+}
+declare function SoftphoneProvider({ softphone, children }: SoftphoneProviderProps): react.JSX.Element;
+/** The `Softphone` instance from context. Stable — does not re-render on state changes. */
+declare function useSoftphone(): Softphone;
+
+/** Reactive softphone lifecycle state (`stopped` → `online` → …). */
+/**
+ * The reason the phone cannot currently be used, or `null`.
+ *
+ * Reads `softphone.lastError`, which is STATE rather than only an event — the widget is usually
+ * opened *after* something broke, and a listener mounted at that point would have missed the event
+ * entirely and rendered a dialpad with no explanation.
+ *
+ * Re-reads on both channels because both can change it: `Error` sets it, and `StateChanged` clears it
+ * on reaching `online`. Subscribing to only the first would leave a stale gate on screen after the
+ * phone recovered.
+ */
+declare function useLastError(): FatalSoftphoneError | null;
+declare function useSoftphoneState(): SoftphoneState;
+/**
+ * Whether THIS tab is the one allowed to be reachable (`multi-tab-leader-election.md`). `false` by
+ * default and while waiting for another open tab to release it — show your own "active in another
+ * tab" state for that duration; the `/ui` widget already does.
+ */
+declare function useIsLeader(): boolean;
+/**
+ * The current call, or null. Re-renders when it changes — inbound, outbound, or ended.
+ *
+ * `phone.activeCall` returns a stable reference for a given call, so it is a safe snapshot.
+ */
+declare function useActiveCall(): Call | null;
+/** An immutable snapshot of a call's reactive fields. */
+interface CallView {
+    readonly state: CallState;
+    readonly isMuted: boolean;
+    readonly isOnHold: boolean;
+    readonly remote: RemoteParty;
+    readonly remoteStream: MediaStream | null;
+    readonly answeredAt: Date | null;
+}
+/**
+ * Reactive view of a specific call. Re-renders only when one of the call's own events fires — no
+ * polling, no re-render storms.
+ *
+ * The snapshot is CACHED and invalidated only on an event, so `useSyncExternalStore` gets a stable
+ * reference between changes (returning a fresh object every render would infinite-loop).
+ */
+declare function useCall(call: Call | null): CallView | null;
+/**
+ * The audio device surface (`phone.audio`) — reactive. Re-renders on `SoftphoneEvent.DeviceChange`: a
+ * device plugged/unplugged, or a selection changed (SPEC §7 Phase 2).
+ *
+ * The snapshot is CACHED and invalidated only on that event, same reasoning as `useCall`'s own
+ * `CallView`: `phone.audio` is ONE stable object whose fields mutate in place, so returning it
+ * directly would never change by reference and `useSyncExternalStore` would never re-render. A fresh
+ * object, rebuilt only when something actually changed, is what makes this reactive without polling.
+ */
+declare function useDevices(): AudioDevices;
+
+export { type CallView, SoftphoneProvider, type SoftphoneProviderProps, useActiveCall, useCall, useDevices, useIsLeader, useLastError, useSoftphone, useSoftphoneState };

package/dist/react/index.d.ts

@@ -0,0 +1,68 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { S as Softphone, A as AudioDevices } from '../softphone-DHmhotbf.js';
+import { f as CallState, R as RemoteParty, a as Call, h as FatalSoftphoneError, o as SoftphoneState } from '../call-BTYlT2SU.js';
+
+interface SoftphoneProviderProps {
+    readonly softphone: Softphone;
+    readonly children: ReactNode;
+}
+declare function SoftphoneProvider({ softphone, children }: SoftphoneProviderProps): react.JSX.Element;
+/** The `Softphone` instance from context. Stable — does not re-render on state changes. */
+declare function useSoftphone(): Softphone;
+
+/** Reactive softphone lifecycle state (`stopped` → `online` → …). */
+/**
+ * The reason the phone cannot currently be used, or `null`.
+ *
+ * Reads `softphone.lastError`, which is STATE rather than only an event — the widget is usually
+ * opened *after* something broke, and a listener mounted at that point would have missed the event
+ * entirely and rendered a dialpad with no explanation.
+ *
+ * Re-reads on both channels because both can change it: `Error` sets it, and `StateChanged` clears it
+ * on reaching `online`. Subscribing to only the first would leave a stale gate on screen after the
+ * phone recovered.
+ */
+declare function useLastError(): FatalSoftphoneError | null;
+declare function useSoftphoneState(): SoftphoneState;
+/**
+ * Whether THIS tab is the one allowed to be reachable (`multi-tab-leader-election.md`). `false` by
+ * default and while waiting for another open tab to release it — show your own "active in another
+ * tab" state for that duration; the `/ui` widget already does.
+ */
+declare function useIsLeader(): boolean;
+/**
+ * The current call, or null. Re-renders when it changes — inbound, outbound, or ended.
+ *
+ * `phone.activeCall` returns a stable reference for a given call, so it is a safe snapshot.
+ */
+declare function useActiveCall(): Call | null;
+/** An immutable snapshot of a call's reactive fields. */
+interface CallView {
+    readonly state: CallState;
+    readonly isMuted: boolean;
+    readonly isOnHold: boolean;
+    readonly remote: RemoteParty;
+    readonly remoteStream: MediaStream | null;
+    readonly answeredAt: Date | null;
+}
+/**
+ * Reactive view of a specific call. Re-renders only when one of the call's own events fires — no
+ * polling, no re-render storms.
+ *
+ * The snapshot is CACHED and invalidated only on an event, so `useSyncExternalStore` gets a stable
+ * reference between changes (returning a fresh object every render would infinite-loop).
+ */
+declare function useCall(call: Call | null): CallView | null;
+/**
+ * The audio device surface (`phone.audio`) — reactive. Re-renders on `SoftphoneEvent.DeviceChange`: a
+ * device plugged/unplugged, or a selection changed (SPEC §7 Phase 2).
+ *
+ * The snapshot is CACHED and invalidated only on that event, same reasoning as `useCall`'s own
+ * `CallView`: `phone.audio` is ONE stable object whose fields mutate in place, so returning it
+ * directly would never change by reference and `useSyncExternalStore` would never re-render. A fresh
+ * object, rebuilt only when something actually changed, is what makes this reactive without polling.
+ */
+declare function useDevices(): AudioDevices;
+
+export { type CallView, SoftphoneProvider, type SoftphoneProviderProps, useActiveCall, useCall, useDevices, useIsLeader, useLastError, useSoftphone, useSoftphoneState };

package/dist/react/index.js

@@ -0,0 +1,4 @@
+export { SoftphoneProvider, useActiveCall, useCall, useDevices, useIsLeader, useLastError, useSoftphone, useSoftphoneState } from '../chunk-3V2L6UTK.js';
+import '../chunk-N2N2EQQJ.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/softphone-DHmhotbf.d.ts

@@ -0,0 +1,128 @@
+import { u as ContactsSource, v as HistorySource, g as Contact, A as AgentsDirectory, q as TypedEmitter, n as SoftphoneEventMap, o as SoftphoneState, h as FatalSoftphoneError, e as CallOptions, a as Call } from './call-BTYlT2SU.js';
+
+/** Contacts, history, caller ID and the agents directory, all from one config. */
+interface BackendSources {
+    readonly contacts: ContactsSource;
+    readonly history: HistorySource;
+    readonly resolveContact: (number: string) => Promise<Contact | null>;
+    /** The Historial tab's "filter by person" directory. Always Coventia's own org membership. */
+    readonly listAgents: () => Promise<AgentsDirectory>;
+}
+
+/**
+ * Audio device control (SPEC §7 Phase 2). Reactive: `SoftphoneEvent.DeviceChange` fires whenever any
+ * field here changes — a device was plugged/unplugged, or a selection changed — so `useDevices()`
+ * (and any other listener) always reads a current snapshot rather than one frozen at mount.
+ */
+interface AudioDevices {
+    readonly inputs: readonly MediaDeviceInfo[];
+    readonly outputs: readonly MediaDeviceInfo[];
+    /**
+     * The currently-selected input/output, or `null` — no explicit choice made, the browser's own
+     * default is in use. Never a stale ID: if the selected device is unplugged, its selection is
+     * cleared back to `null` rather than pointing at a device that no longer exists.
+     */
+    readonly currentInputId: string | null;
+    readonly currentOutputId: string | null;
+    /**
+     * Re-enumerate. `inputs`/`outputs` already stay current on their own — a device physically
+     * plugged or unplugged fires the browser's own `devicechange` and needs no help — but a
+     * *permission* grant does not: the labels enumerate as blank strings until the microphone has been
+     * granted at least once, and granting it later fires no event at all. Call this when a UI surface
+     * that shows device names is about to become visible (SPEC §7 Phase 2 note: the settings tab calls
+     * it on mount for exactly this reason).
+     */
+    refresh(): Promise<void>;
+    /**
+     * Switches the microphone, or `null` to reset to the browser's own default device. Applies to the
+     * call in progress, if any — immediately, via `RTCRtpSender.replaceTrack`, no renegotiation and no
+     * interruption the far end can hear — and to every call placed or answered after this resolves.
+     */
+    setInput(deviceId: string | null): Promise<void>;
+    /**
+     * Switches where the REMOTE PARTY is heard, or `null` to reset to the browser's own default
+     * device. Applies instantly, live call or not — output routing needs no WebRTC renegotiation at
+     * all, unlike the input side.
+     *
+     * A no-op (resolves immediately) when `canSelectOutput` is false.
+     */
+    setOutput(deviceId: string | null): Promise<void>;
+    /**
+     * The RINGTONE output, separate from the call speaker.
+     *
+     * Of every SDK surveyed only Twilio ships this, and users want it: ring on the laptop speakers so
+     * you hear it across the room, take the call in the headset.
+     *
+     * **Not yet implemented** — still Phase 2 groundwork, like `NoopAudioDevices` before it. Calling it
+     * resolves without effect until a later pass wires it up.
+     */
+    setRingtoneOutput(deviceId: string | null): Promise<void>;
+    /** False when the browser lacks `setSinkId` (Safari, most of Firefox) — `setOutput` is then a no-op. */
+    readonly canSelectOutput: boolean;
+}
+/**
+ * The engine. Long-lived; owns registration, credentials, devices, and the provider.
+ *
+ * Implementation lands in S2.
+ */
+interface Softphone extends TypedEmitter<SoftphoneEventMap> {
+    readonly state: SoftphoneState;
+    /**
+     * The last **fatal** error, or `null` — the reason the phone cannot currently be used.
+     *
+     * State rather than only an event, because the common case is: the phone breaks, and *then* the
+     * user opens the panel to find out why. A widget that mounts after the failure would never see
+     * `SoftphoneEvent.Error`, and would render a dialpad with no explanation for why it does nothing.
+     *
+     * **Cleared when the softphone next reaches `online`** — the only evidence available that whatever
+     * was wrong no longer is. Non-fatal errors are emitted but never set this: a busy tone is a fact
+     * about one call, not a broken phone.
+     */
+    readonly lastError: FatalSoftphoneError | null;
+    /**
+     * Whether THIS tab is the one allowed to be reachable (`multi-tab-leader-election.md`).
+     *
+     * Zadarma's on-demand registration means two tabs open for the same extension race each other to
+     * register on every inbound push — confirmed live, exactly one tab rings, unpredictably which. At
+     * most one open tab is ever the leader at a time; leadership passes to the next tab automatically
+     * (no reload) the moment the current leader closes, reloads, or crashes.
+     *
+     * `false` by default and while waiting for another tab to release it — a host should show its own
+     * "active in another tab" state for that duration (the `/ui` widget already does).
+     */
+    readonly isLeader: boolean;
+    /**
+     * Start.
+     *
+     * **Call this from a user gesture.** Both the microphone permission prompt and the browser's
+     * autoplay policy key off user activation. Twilio's own docs name this as the cause of *missed
+     * calls*: with no activation, the incoming-call ringtone is silently blocked and the agent never
+     * knows anyone rang.
+     */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Idempotent. After this the instance is dead — construct a new one. */
+    destroy(): Promise<void>;
+    call(destination: string, options?: CallOptions): Promise<Call>;
+    /** The live call, or null. The consult leg of an attended transfer is reachable from it. */
+    readonly activeCall: Call | null;
+    /**
+     * Contacts + history, when `SoftphoneConfig.coventia` was given; `null` otherwise.
+     *
+     * The widget reads these rather than being handed a config, so there is exactly ONE set per
+     * softphone — one name cache, one of every request.
+     */
+    readonly sources: BackendSources | null;
+    readonly audio: AudioDevices;
+    /**
+     * False when the browser has blocked audio playback.
+     *
+     * When false, an incoming call RINGS SILENTLY. Surface a button; call `startAudio()` from its
+     * click handler. This is the failure mode almost every voice SDK leaves undocumented.
+     */
+    readonly canPlayAudio: boolean;
+    /** Must be called from within a user gesture. */
+    startAudio(): Promise<void>;
+}
+
+export type { AudioDevices as A, Softphone as S };

package/dist/softphone-DhuhcKCy.d.cts

@@ -0,0 +1,128 @@
+import { u as ContactsSource, v as HistorySource, g as Contact, A as AgentsDirectory, q as TypedEmitter, n as SoftphoneEventMap, o as SoftphoneState, h as FatalSoftphoneError, e as CallOptions, a as Call } from './call-BTYlT2SU.cjs';
+
+/** Contacts, history, caller ID and the agents directory, all from one config. */
+interface BackendSources {
+    readonly contacts: ContactsSource;
+    readonly history: HistorySource;
+    readonly resolveContact: (number: string) => Promise<Contact | null>;
+    /** The Historial tab's "filter by person" directory. Always Coventia's own org membership. */
+    readonly listAgents: () => Promise<AgentsDirectory>;
+}
+
+/**
+ * Audio device control (SPEC §7 Phase 2). Reactive: `SoftphoneEvent.DeviceChange` fires whenever any
+ * field here changes — a device was plugged/unplugged, or a selection changed — so `useDevices()`
+ * (and any other listener) always reads a current snapshot rather than one frozen at mount.
+ */
+interface AudioDevices {
+    readonly inputs: readonly MediaDeviceInfo[];
+    readonly outputs: readonly MediaDeviceInfo[];
+    /**
+     * The currently-selected input/output, or `null` — no explicit choice made, the browser's own
+     * default is in use. Never a stale ID: if the selected device is unplugged, its selection is
+     * cleared back to `null` rather than pointing at a device that no longer exists.
+     */
+    readonly currentInputId: string | null;
+    readonly currentOutputId: string | null;
+    /**
+     * Re-enumerate. `inputs`/`outputs` already stay current on their own — a device physically
+     * plugged or unplugged fires the browser's own `devicechange` and needs no help — but a
+     * *permission* grant does not: the labels enumerate as blank strings until the microphone has been
+     * granted at least once, and granting it later fires no event at all. Call this when a UI surface
+     * that shows device names is about to become visible (SPEC §7 Phase 2 note: the settings tab calls
+     * it on mount for exactly this reason).
+     */
+    refresh(): Promise<void>;
+    /**
+     * Switches the microphone, or `null` to reset to the browser's own default device. Applies to the
+     * call in progress, if any — immediately, via `RTCRtpSender.replaceTrack`, no renegotiation and no
+     * interruption the far end can hear — and to every call placed or answered after this resolves.
+     */
+    setInput(deviceId: string | null): Promise<void>;
+    /**
+     * Switches where the REMOTE PARTY is heard, or `null` to reset to the browser's own default
+     * device. Applies instantly, live call or not — output routing needs no WebRTC renegotiation at
+     * all, unlike the input side.
+     *
+     * A no-op (resolves immediately) when `canSelectOutput` is false.
+     */
+    setOutput(deviceId: string | null): Promise<void>;
+    /**
+     * The RINGTONE output, separate from the call speaker.
+     *
+     * Of every SDK surveyed only Twilio ships this, and users want it: ring on the laptop speakers so
+     * you hear it across the room, take the call in the headset.
+     *
+     * **Not yet implemented** — still Phase 2 groundwork, like `NoopAudioDevices` before it. Calling it
+     * resolves without effect until a later pass wires it up.
+     */
+    setRingtoneOutput(deviceId: string | null): Promise<void>;
+    /** False when the browser lacks `setSinkId` (Safari, most of Firefox) — `setOutput` is then a no-op. */
+    readonly canSelectOutput: boolean;
+}
+/**
+ * The engine. Long-lived; owns registration, credentials, devices, and the provider.
+ *
+ * Implementation lands in S2.
+ */
+interface Softphone extends TypedEmitter<SoftphoneEventMap> {
+    readonly state: SoftphoneState;
+    /**
+     * The last **fatal** error, or `null` — the reason the phone cannot currently be used.
+     *
+     * State rather than only an event, because the common case is: the phone breaks, and *then* the
+     * user opens the panel to find out why. A widget that mounts after the failure would never see
+     * `SoftphoneEvent.Error`, and would render a dialpad with no explanation for why it does nothing.
+     *
+     * **Cleared when the softphone next reaches `online`** — the only evidence available that whatever
+     * was wrong no longer is. Non-fatal errors are emitted but never set this: a busy tone is a fact
+     * about one call, not a broken phone.
+     */
+    readonly lastError: FatalSoftphoneError | null;
+    /**
+     * Whether THIS tab is the one allowed to be reachable (`multi-tab-leader-election.md`).
+     *
+     * Zadarma's on-demand registration means two tabs open for the same extension race each other to
+     * register on every inbound push — confirmed live, exactly one tab rings, unpredictably which. At
+     * most one open tab is ever the leader at a time; leadership passes to the next tab automatically
+     * (no reload) the moment the current leader closes, reloads, or crashes.
+     *
+     * `false` by default and while waiting for another tab to release it — a host should show its own
+     * "active in another tab" state for that duration (the `/ui` widget already does).
+     */
+    readonly isLeader: boolean;
+    /**
+     * Start.
+     *
+     * **Call this from a user gesture.** Both the microphone permission prompt and the browser's
+     * autoplay policy key off user activation. Twilio's own docs name this as the cause of *missed
+     * calls*: with no activation, the incoming-call ringtone is silently blocked and the agent never
+     * knows anyone rang.
+     */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Idempotent. After this the instance is dead — construct a new one. */
+    destroy(): Promise<void>;
+    call(destination: string, options?: CallOptions): Promise<Call>;
+    /** The live call, or null. The consult leg of an attended transfer is reachable from it. */
+    readonly activeCall: Call | null;
+    /**
+     * Contacts + history, when `SoftphoneConfig.coventia` was given; `null` otherwise.
+     *
+     * The widget reads these rather than being handed a config, so there is exactly ONE set per
+     * softphone — one name cache, one of every request.
+     */
+    readonly sources: BackendSources | null;
+    readonly audio: AudioDevices;
+    /**
+     * False when the browser has blocked audio playback.
+     *
+     * When false, an incoming call RINGS SILENTLY. Surface a button; call `startAudio()` from its
+     * click handler. This is the failure mode almost every voice SDK leaves undocumented.
+     */
+    readonly canPlayAudio: boolean;
+    /** Must be called from within a user gesture. */
+    startAudio(): Promise<void>;
+}
+
+export type { AudioDevices as A, Softphone as S };