@coventia/softphone 0.2.0 → 0.3.0

package/dist/react/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/react/context.tsx","../../src/react/hooks.ts"],"names":["createContext","useContext","useSyncExternalStore","useCallback","useRef"],"mappings":";;;;;;AAYA,IAAM,gBAAA,GAAmBA,oBAAgC,IAAI,CAAA;AAOtD,SAAS,iBAAA,CAAkB,EAAE,SAAA,EAAW,QAAA,EAAS,EAA2B;AACjF,EAAA,sCAAQ,gBAAA,CAAiB,QAAA,EAAjB,EAA0B,KAAA,EAAO,WAAY,QAAA,EAAS,CAAA;AAChE;AAGO,SAAS,YAAA,GAA0B;AACxC,EAAA,MAAM,SAAA,GAAYC,iBAAW,gBAAgB,CAAA;AAC7C,EAAA,IAAI,CAAC,SAAA,EAAW;AACd,IAAA,MAAM,IAAI,MAAM,2DAA2D,CAAA;AAAA,EAC7E;AACA,EAAA,OAAO,SAAA;AACT;ACTO,SAAS,YAAA,GAA2C;AACzD,EAAA,MAAM,QAAQ,YAAA,EAAa;AAC3B,EAAA,OAAOC,0BAAA;AAAA,IACLC,iBAAA;AAAA,MACE,CAAC,EAAA,KAAmB;AAClB,QAAA,MAAM,QAAA,GAAW,KAAA,CAAM,EAAA,CAAA,OAAA,cAAyB,MAAM,IAAI,CAAA;AAC1D,QAAA,MAAM,QAAA,GAAW,KAAA,CAAM,EAAA,CAAA,cAAA,qBAAgC,MAAM,IAAI,CAAA;AACjE,QAAA,OAAO,MAAM;AACX,UAAA,QAAA,EAAS;AACT,UAAA,QAAA,EAAS;AAAA,QACX,CAAA;AAAA,MACF,CAAA;AAAA,MACA,CAAC,KAAK;AAAA,KACR;AAAA,IACAA,kBAAY,MAAM,KAAA,CAAM,SAAA,EAAW,CAAC,KAAK,CAAC;AAAA,GAC5C;AACF;AAEO,SAAS,iBAAA,GAAoC;AAClD,EAAA,MAAM,QAAQ,YAAA,EAAa;AAC3B,EAAA,OAAOD,0BAAA;AAAA,IACLC,iBAAA,CAAY,CAAC,EAAA,KAAmB,KAAA,CAAM,EAAA,CAAA,cAAA,qBAAgC,MAAM,EAAA,EAAI,CAAA,EAAG,CAAC,KAAK,CAAC,CAAA;AAAA,IAC1FA,kBAAY,MAAM,KAAA,CAAM,KAAA,EAAO,CAAC,KAAK,CAAC;AAAA,GACxC;AACF;AAOO,SAAS,WAAA,GAAuB;AACrC,EAAA,MAAM,QAAQ,YAAA,EAAa;AAC3B,EAAA,OAAOD,0BAAA;AAAA,IACLC,iBAAA,CAAY,CAAC,EAAA,KAAmB,KAAA,CAAM,EAAA,CAAA,eAAA,sBAAiC,MAAM,EAAA,EAAI,CAAA,EAAG,CAAC,KAAK,CAAC,CAAA;AAAA,IAC3FA,kBAAY,MAAM,KAAA,CAAM,QAAA,EAAU,CAAC,KAAK,CAAC;AAAA,GAC3C;AACF;AAOO,SAAS,aAAA,GAA6B;AAC3C,EAAA,MAAM,QAAQ,YAAA,EAAa;AAC3B,EAAA,OAAOD,0BAAA;AAAA,IACLC,iBAAA,CAAY,CAAC,EAAA,KAAmB,KAAA,CAAM,EAAA,CAAA,mBAAA,0BAAqC,MAAM,EAAA,EAAI,CAAA,EAAG,CAAC,KAAK,CAAC,CAAA;AAAA,IAC/FA,kBAAY,MAAM,KAAA,CAAM,UAAA,EAAY,CAAC,KAAK,CAAC;AAAA,GAC7C;AACF;AAYO,SAAS,YAAY,MAAA,EAA2C;AACrE,EAAA,MAAM,QAAQ,YAAA,EAAa;AAC3B,EAAA,OAAOD,0BAAA;AAAA,IACLC,iBAAA;AAAA,MACE,CAAC,EAAA,KAAmB;AAClB,QAAA,IAAI,CAAC,MAAA,EAAQ,OAAO,MAAM;AAAA,QAAC,CAAA;AAC3B,QAAA,OAAO,KAAA,CAAM,EAAA,CAAA,iBAAA,wBAAmC,MAAM,EAAA,EAAI,CAAA;AAAA,MAC5D,CAAA;AAAA,MACA,CAAC,OAAO,MAAM;AAAA,KAChB;AAAA,IACAA,kBAAY,MAAM,KAAA,CAAM,QAAA,EAAU,CAAC,KAAK,CAAC;AAAA,GAC3C;AACF;AAYA,IAAM,WAAA,GAAoC;AAAA,EAAA,cAAA;AAAA,EAAA,OAAA;AAAA,EAAA,MAAA;AAAA,EAAA,QAAA;AAAA,EAAA,oBAAA;AAAA,EAAA,cAAA;AAAA,EAAA,OAAA;AAQ1C,CAAA;AASO,SAAS,QAAQ,IAAA,EAAoC;AAC1D,EAAA,MAAM,KAAA,GAAQC,aAA8C,IAAI,CAAA;AAEhE,EAAA,MAAM,SAAA,GAAYD,iBAAA;AAAA,IAChB,CAAC,EAAA,KAAmB;AAClB,MAAA,IAAI,CAAC,IAAA,EAAM,OAAO,MAAM;AAAA,MAAC,CAAA;AACzB,MAAA,MAAM,SAAS,WAAA,CAAY,GAAA;AAAA,QAAI,CAAC,KAAA,KAC9B,IAAA,CAAK,EAAA,CAAG,OAAO,MAAM;AACnB,UAAA,KAAA,CAAM,OAAA,GAAU,IAAA;AAChB,UAAA,EAAA,EAAG;AAAA,QACL,CAAC;AAAA,OACH;AACA,MAAA,OAAO,MAAM;AACX,QAAA,KAAA,MAAW,GAAA,IAAO,QAAQ,GAAA,EAAI;AAAA,MAChC,CAAA;AAAA,IACF,CAAA;AAAA,IACA,CAAC,IAAI;AAAA,GACP;AAEA,EAAA,MAAM,WAAA,GAAcA,kBAAY,MAAuB;AACrD,IAAA,IAAI,CAAC,MAAM,OAAO,IAAA;AAClB,IAAA,IAAI,MAAM,OAAA,EAAS,IAAA,KAAS,IAAA,EAAM,OAAO,MAAM,OAAA,CAAQ,IAAA;AACvD,IAAA,MAAM,IAAA,GAAiB;AAAA,MACrB,OAAO,IAAA,CAAK,KAAA;AAAA,MACZ,SAAS,IAAA,CAAK,OAAA;AAAA,MACd,UAAU,IAAA,CAAK,QAAA;AAAA,MACf,QAAQ,IAAA,CAAK,MAAA;AAAA,MACb,cAAc,IAAA,CAAK,YAAA;AAAA,MACnB,YAAY,IAAA,CAAK;AAAA,KACnB;AACA,IAAA,KAAA,CAAM,OAAA,GAAU,EAAE,IAAA,EAAM,IAAA,EAAK;AAC7B,IAAA,OAAO,IAAA;AAAA,EACT,CAAA,EAAG,CAAC,IAAI,CAAC,CAAA;AAET,EAAA,OAAOD,0BAAA,CAAqB,WAAW,WAAW,CAAA;AACpD;AAWO,SAAS,UAAA,GAA2B;AACzC,EAAA,MAAM,QAAQ,YAAA,EAAa;AAC3B,EAAA,MAAM,KAAA,GAAQE,aAA2D,IAAI,CAAA;AAE7E,EAAA,MAAM,SAAA,GAAYD,iBAAA;AAAA,IAChB,CAAC,EAAA,KACC,KAAA,CAAM,EAAA,CAAA,cAAA,qBAAgC,MAAM;AAC1C,MAAA,KAAA,CAAM,OAAA,GAAU,IAAA;AAChB,MAAA,EAAA,EAAG;AAAA,IACL,CAAC,CAAA;AAAA,IACH,CAAC,KAAK;AAAA,GACR;AAEA,EAAA,MAAM,WAAA,GAAcA,kBAAY,MAAoB;AAClD,IAAA,MAAM,QAAQ,KAAA,CAAM,KAAA;AACpB,IAAA,IAAI,MAAM,OAAA,EAAS,KAAA,KAAU,KAAA,EAAO,OAAO,MAAM,OAAA,CAAQ,IAAA;AACzD,IAAA,MAAM,IAAA,GAAqB;AAAA,MACzB,QAAQ,KAAA,CAAM,MAAA;AAAA,MACd,SAAS,KAAA,CAAM,OAAA;AAAA,MACf,gBAAgB,KAAA,CAAM,cAAA;AAAA,MACtB,iBAAiB,KAAA,CAAM,eAAA;AAAA,MACvB,iBAAiB,KAAA,CAAM,eAAA;AAAA,MACvB,QAAA,EAAU,CAAC,QAAA,KAAa,KAAA,CAAM,SAAS,QAAQ,CAAA;AAAA,MAC/C,SAAA,EAAW,CAAC,QAAA,KAAa,KAAA,CAAM,UAAU,QAAQ,CAAA;AAAA,MACjD,iBAAA,EAAmB,CAAC,QAAA,KAAa,KAAA,CAAM,kBAAkB,QAAQ,CAAA;AAAA,MACjE,OAAA,EAAS,MAAM,KAAA,CAAM,OAAA;AAAQ,KAC/B;AACA,IAAA,KAAA,CAAM,OAAA,GAAU,EAAE,KAAA,EAAO,IAAA,EAAK;AAC9B,IAAA,OAAO,IAAA;AAAA,EACT,CAAA,EAAG,CAAC,KAAK,CAAC,CAAA;AAEV,EAAA,OAAOD,0BAAA,CAAqB,WAAW,WAAW,CAAA;AACpD","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 { PresenceEntry, 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/**\r\n * The live agent-presence list (`phone.presence`, Phase B) — reactive on `SoftphoneEvent.\r\n * PresenceChanged`. `active` gates the SUBSCRIPTION only, not the underlying connection: the socket\r\n * itself stays governed entirely by `online && isLeader` inside the softphone (spec's own\r\n * always-connected decision), so passing `false` here does not close it — it only stops this\r\n * particular component from re-rendering on every update while it has no reason to care, e.g. the\r\n * transfer step being closed (spec §4.5: \"subscribe when the step opens... unsubscribe when it\r\n * closes\"). `phone.presence` is still read fresh on every call, so flipping `active` back to `true`\r\n * never shows a stale snapshot.\r\n */\r\nexport function usePresence(active: boolean): readonly PresenceEntry[] {\r\n  const phone = useSoftphone();\r\n  return useSyncExternalStore(\r\n    useCallback(\r\n      (cb: () => void) => {\r\n        if (!active) return () => {};\r\n        return phone.on(SoftphoneEvent.PresenceChanged, () => cb());\r\n      },\r\n      [phone, active],\r\n    ),\r\n    useCallback(() => phone.presence, [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"]}
+{"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 { PresenceEntry, 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/**\r\n * The live agent-presence list (`phone.presence`, Phase B) — reactive on `SoftphoneEvent.\r\n * PresenceChanged`. `active` gates the SUBSCRIPTION only, not the underlying connection: the socket\r\n * itself stays governed entirely by `online && isLeader` inside the softphone (spec's own\r\n * always-connected decision), so passing `false` here does not close it — it only stops this\r\n * particular component from re-rendering on every update while it has no reason to care, e.g. the\r\n * transfer step being closed (spec §4.5: \"subscribe when the step opens... unsubscribe when it\r\n * closes\"). `phone.presence` is still read fresh on every call, so flipping `active` back to `true`\r\n * never shows a stale snapshot.\r\n */\r\nexport function usePresence(active: boolean): readonly PresenceEntry[] {\r\n  const phone = useSoftphone();\r\n  return useSyncExternalStore(\r\n    useCallback(\r\n      (cb: () => void) => {\r\n        if (!active) return () => {};\r\n        return phone.on(SoftphoneEvent.PresenceChanged, () => cb());\r\n      },\r\n      [phone, active],\r\n    ),\r\n    useCallback(() => phone.presence, [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      currentRingtoneOutputId: audio.currentRingtoneOutputId,\r\n      canSelectOutput: audio.canSelectOutput,\r\n      canSelectRingtoneOutput: audio.canSelectRingtoneOutput,\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

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { S as Softphone, A as AudioDevices } from '../softphone-DHG9MTNg.cjs';
-import { f as CallState, R as RemoteParty, a as Call, h as FatalSoftphoneError, P as PresenceEntry, o as SoftphoneState } from '../call-DUVnDxsz.cjs';
+import { S as Softphone, A as AudioDevices } from '../softphone-dZMkW8V1.cjs';
+import { f as CallState, R as RemoteParty, a as Call, h as FatalSoftphoneError, P as PresenceEntry, r as SoftphoneState } from '../call-CaPDWVk3.cjs';
 
 interface SoftphoneProviderProps {
     readonly softphone: Softphone;

package/dist/react/index.d.ts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { S as Softphone, A as AudioDevices } from '../softphone-BtdgZWkm.js';
-import { f as CallState, R as RemoteParty, a as Call, h as FatalSoftphoneError, P as PresenceEntry, o as SoftphoneState } from '../call-DUVnDxsz.js';
+import { S as Softphone, A as AudioDevices } from '../softphone-DEt0TtQw.js';
+import { f as CallState, R as RemoteParty, a as Call, h as FatalSoftphoneError, P as PresenceEntry, r as SoftphoneState } from '../call-CaPDWVk3.js';
 
 interface SoftphoneProviderProps {
     readonly softphone: Softphone;

package/dist/react/index.js

@@ -1,4 +1,4 @@
-export { SoftphoneProvider, useActiveCall, useCall, useDevices, useIsLeader, useLastError, usePresence, useSoftphone, useSoftphoneState } from '../chunk-LMJXX4YM.js';
+export { SoftphoneProvider, useActiveCall, useCall, useDevices, useIsLeader, useLastError, usePresence, useSoftphone, useSoftphoneState } from '../chunk-UHNLEBBO.js';
 import '../chunk-7R6LOOAI.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{softphone-BtdgZWkm.d.ts → softphone-DEt0TtQw.d.ts}

@@ -1,7 +1,7 @@
-import { u as ContactsSource, v as HistorySource, g as Contact, A as AgentsDirectory, w as TransferOutcomesPage, x as PresenceSource, q as TypedEmitter, n as SoftphoneEventMap, o as SoftphoneState, h as FatalSoftphoneError, e as CallOptions, a as Call, P as PresenceEntry } from './call-DUVnDxsz.js';
+import { x as ContactsSource, y as HistorySource, g as Contact, A as AgentsDirectory, z as TransferOutcomesPage, B as PresenceSource, m as RingtoneSource, t as TypedEmitter, q as SoftphoneEventMap, r as SoftphoneState, h as FatalSoftphoneError, e as CallOptions, a as Call, P as PresenceEntry } from './call-CaPDWVk3.js';
 
-/** Contacts, history, caller ID, the agents directory, transfer outcomes and presence, all from one
- *  config. */
+/** Contacts, history, caller ID, the agents directory, transfer outcomes, presence and ringtone
+ *  settings, all from one config. */
 interface BackendSources {
     readonly contacts: ContactsSource;
     readonly history: HistorySource;
@@ -14,6 +14,8 @@ interface BackendSources {
     }) => Promise<TransferOutcomesPage>;
     /** Phase B (presence-gated transfer picker) — opened by `presence-socket.ts`, never by UI directly. */
     readonly presence: PresenceSource;
+    /** The caller's ringtone settings (custom-ringtone.md §4.4). Always Coventia's — no override. */
+    readonly ringtones: RingtoneSource;
 }
 
 /**
@@ -25,12 +27,20 @@ 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.
+     * The currently-selected input/output/ringtone 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 reads `null` rather than pointing at a device that no longer exists.
+     *
+     * **Choices are remembered** — in `localStorage` (`coventia-softphone:devices`), so they survive a
+     * reload. What is remembered is the user's *preference*, kept apart from these current values: an
+     * unplugged headset reads `null` here, and reads as selected again the moment it is plugged back in,
+     * without the user choosing it twice. Device ids are per browser and per site, which is exactly the
+     * scope of that storage (custom-ringtone.md §4.5). Where storage is blocked (private mode, a
+     * sandboxed iframe) choices simply last for the page, as they used to.
      */
     readonly currentInputId: string | null;
     readonly currentOutputId: string | null;
+    readonly currentRingtoneOutputId: 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
@@ -55,17 +65,23 @@ interface AudioDevices {
      */
     setOutput(deviceId: string | null): Promise<void>;
     /**
-     * The RINGTONE output, separate from the call speaker.
+     * The RINGTONE output, separate from the call speaker, or `null` for the browser's default device.
      *
      * 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.
+     * you hear it across the room, take the call in the headset. Only the inbound ring (and its preview
+     * in Ajustes) follows it; the call itself, the ringback and the short cues stay where they were.
      *
-     * **Not yet implemented** — still Phase 2 groundwork, like `NoopAudioDevices` before it. Calling it
-     * resolves without effect until a later pass wires it up.
+     * Like `setOutput`, this only records the choice and fires `SoftphoneEvent.DeviceChange` — the `/ui`
+     * layer is what routes the ring. A no-op for routing when `canSelectRingtoneOutput` is false.
      */
     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;
+    /**
+     * Whether the ring can be sent to a chosen device. False on Safari (no `setSinkId` at all) — the
+     * ring then plays on the default output and a UI should not offer the picker.
+     */
+    readonly canSelectRingtoneOutput: boolean;
 }
 /**
  * The engine. Long-lived; owns registration, credentials, devices, and the provider.

package/dist/{softphone-DHG9MTNg.d.cts → softphone-dZMkW8V1.d.cts}

@@ -1,7 +1,7 @@
-import { u as ContactsSource, v as HistorySource, g as Contact, A as AgentsDirectory, w as TransferOutcomesPage, x as PresenceSource, q as TypedEmitter, n as SoftphoneEventMap, o as SoftphoneState, h as FatalSoftphoneError, e as CallOptions, a as Call, P as PresenceEntry } from './call-DUVnDxsz.cjs';
+import { x as ContactsSource, y as HistorySource, g as Contact, A as AgentsDirectory, z as TransferOutcomesPage, B as PresenceSource, m as RingtoneSource, t as TypedEmitter, q as SoftphoneEventMap, r as SoftphoneState, h as FatalSoftphoneError, e as CallOptions, a as Call, P as PresenceEntry } from './call-CaPDWVk3.cjs';
 
-/** Contacts, history, caller ID, the agents directory, transfer outcomes and presence, all from one
- *  config. */
+/** Contacts, history, caller ID, the agents directory, transfer outcomes, presence and ringtone
+ *  settings, all from one config. */
 interface BackendSources {
     readonly contacts: ContactsSource;
     readonly history: HistorySource;
@@ -14,6 +14,8 @@ interface BackendSources {
     }) => Promise<TransferOutcomesPage>;
     /** Phase B (presence-gated transfer picker) — opened by `presence-socket.ts`, never by UI directly. */
     readonly presence: PresenceSource;
+    /** The caller's ringtone settings (custom-ringtone.md §4.4). Always Coventia's — no override. */
+    readonly ringtones: RingtoneSource;
 }
 
 /**
@@ -25,12 +27,20 @@ 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.
+     * The currently-selected input/output/ringtone 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 reads `null` rather than pointing at a device that no longer exists.
+     *
+     * **Choices are remembered** — in `localStorage` (`coventia-softphone:devices`), so they survive a
+     * reload. What is remembered is the user's *preference*, kept apart from these current values: an
+     * unplugged headset reads `null` here, and reads as selected again the moment it is plugged back in,
+     * without the user choosing it twice. Device ids are per browser and per site, which is exactly the
+     * scope of that storage (custom-ringtone.md §4.5). Where storage is blocked (private mode, a
+     * sandboxed iframe) choices simply last for the page, as they used to.
      */
     readonly currentInputId: string | null;
     readonly currentOutputId: string | null;
+    readonly currentRingtoneOutputId: 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
@@ -55,17 +65,23 @@ interface AudioDevices {
      */
     setOutput(deviceId: string | null): Promise<void>;
     /**
-     * The RINGTONE output, separate from the call speaker.
+     * The RINGTONE output, separate from the call speaker, or `null` for the browser's default device.
      *
      * 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.
+     * you hear it across the room, take the call in the headset. Only the inbound ring (and its preview
+     * in Ajustes) follows it; the call itself, the ringback and the short cues stay where they were.
      *
-     * **Not yet implemented** — still Phase 2 groundwork, like `NoopAudioDevices` before it. Calling it
-     * resolves without effect until a later pass wires it up.
+     * Like `setOutput`, this only records the choice and fires `SoftphoneEvent.DeviceChange` — the `/ui`
+     * layer is what routes the ring. A no-op for routing when `canSelectRingtoneOutput` is false.
      */
     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;
+    /**
+     * Whether the ring can be sent to a chosen device. False on Safari (no `setSinkId` at all) — the
+     * ring then plays on the default output and a UI should not offer the picker.
+     */
+    readonly canSelectRingtoneOutput: boolean;
 }
 /**
  * The engine. Long-lived; owns registration, credentials, devices, and the provider.

package/dist/softphone.css

@@ -240,8 +240,6 @@
   .cv-dial-prefix { padding: 0.7rem 0.6rem 0; }
   .cv-dial-head { padding: 0.3rem 0.6rem 0.6rem; }
   .cv-display { font-size: 1.5rem; }
-  .cv-controls-row { gap: 1.1rem; }
-
 }
 
 /* Short hosts. The flex chain already lets the keypad absorb what is left, but below this the keys
@@ -720,7 +718,7 @@
 }
 .cv-badge-hold { color: var(--cv-hold); font-weight: 600; }
 
-/* ── Pre-connect device check (ringing / dialing) ──────────────────────────────
+/* ── Device check (ringing / dialing / in-call) ────────────────────────────────
    Before a call connects there is only ONE other control on screen (Colgar, or
    Rechazar/Contestar) — putting Dispositivos in that same neighbourhood, even
    spaced out, keeps it a mis-tap away from hanging up or answering. The entry
@@ -736,6 +734,11 @@
    cramped and scrolly for just two rows. `.cv-call-devices-inline` REPLACES the
    avatar/name/status block in `.cv-call` instead (see that JSX's own comment) —
    an inline swap, not an overlay, so it gets the full box, not a leftover sliver.
+
+   Once connected it is the SAME chip and the SAME swap. Dispositivos used to be a fifth control in
+   the call row (with a floating popover), which is what forced that row down to 40px buttons and
+   9px labels in a 310px host. A set-once setting does not need a slot among the four things you do
+   mid-call (mute, hold, transfer, keypad), and the control row stays live under the swap.
    ───────────────────────────────────────────────────────────────────────────── */
 .cv-call-devices-chip {
   display: inline-flex;
@@ -808,16 +811,22 @@
   display: flex;
   flex-direction: column;
   align-items: center;
-  gap: 0.7rem;
+  gap: 0.9rem;
   padding: 0.35rem 1rem 1.1rem;
-  /* The containing block for `.cv-device-popover` — see that rule's own comment for why it is
+  /* The containing block for `.cv-keypad-popover` — see that rule's own comment for why it is
      anchored here rather than to the trigger button. */
   position: relative;
 }
+/* FOUR controls, sized so they never need to shrink to fit. This row held five (Dispositivos too) and
+   the only way to fit five in the CRM's 310px host was a 40px button with a 9px label and ~6px gaps —
+   below the 44/48px a thumb needs, and below legible for a word read mid-call. The default 48px size
+   below was never actually seen: it only applied above a 360px host, which no real embed is.
+   Dispositivos is the `.cv-call-chips` chip up by the call info instead (the same entry point the
+   ringing and dialing screens already use). 4 × 52 + 3 × 20 = 268px, inside 310 - 2 × 16 padding. */
 .cv-controls-row {
   display: flex;
   justify-content: center;
-  gap: 1.5rem;
+  gap: 1.25rem;
 }
 .cv-controls-primary {
   display: flex;
@@ -840,9 +849,12 @@
   white-space: nowrap;
   user-select: none;
 }
+/* The four secondaries' words get a notch more than Colgar / Rechazar / Contestar's 10px — they are
+   the ones read mid-call, and the five-up row used to shrink them to 9px (8px in a sidebar). */
+.cv-controls-row .cv-ctrl-label { font-size: 0.6875rem; }
 .cv-ctrl {
-  width: 48px;
-  height: 48px;
+  width: 52px;
+  height: 52px;
   border-radius: 999px;
   border: 1px solid var(--cv-border-strong);
   background: var(--cv-bg);
@@ -855,6 +867,11 @@
 }
 .cv-ctrl:hover { background: var(--cv-surface); }
 .cv-ctrl:active { transform: scale(0.94); }
+.cv-ctrl:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+  pointer-events: none;
+}
 
 /* The ON states say what they MEAN, in the widget's own tokens: muted is danger,
    held is hold, transfer-open is accent. Colour is the state, not decoration. */
@@ -900,6 +917,28 @@
   border-color: var(--cv-text);
 }
 
+/*
+  Sidebar-narrow (this file's own ≤300px tier, up in "Narrow hosts"). The four 52px controls with
+  20px gaps need 268px, which a 260px host cannot give — so this tier steps down to 44px with 12px
+  gaps (4 × 44 + 3 × 12 = 212px) and reclaims `.cv-controls`'s own horizontal padding, the first
+  lever that block's own comment names. 44px is still the Apple HIG minimum tap target; the five-up
+  row this replaced went to 36px here.
+
+  Placed AFTER `.cv-controls`/`.cv-controls-row` above rather than up with this file's other
+  `@container` blocks near the top: `gap` and `padding-left`/`-right` here have the same specificity as
+  those base rules' own shorthand, so — unlike a compound selector such as `.cv-controls-row .cv-ctrl`,
+  which wins on specificity regardless of position — source order is what decides, and a narrower-width
+  override declared BEFORE the base rule it means to narrow loses to it. Confirmed live: moved up into
+  the "Narrow hosts" section, the `.cv-ctrl` width and label font-size reductions took effect (compound
+  selectors) but `gap` and `.cv-controls`'s padding silently did not (plain selectors, later base rule won).
+*/
+@container cv (max-width: 300px) {
+  .cv-controls { padding-left: 0.5rem; padding-right: 0.5rem; }
+  .cv-controls-row { gap: 0.75rem; }
+  .cv-controls-row .cv-ctrl { width: 44px; height: 44px; }
+  .cv-controls-row .cv-ctrl-label { font-size: 0.625rem; }
+}
+
 /*
   The attended-transfer target-entry panel (`docs/specs/transfer-availability.md` §5): an optional
   outcome line, then a row of whatever's actionable (input+button today). Once a consult exists,
@@ -1146,49 +1185,58 @@
   transform: scale(0.98);
 }
 
+@keyframes cv-pop-in-up {
+  from { opacity: 0; transform: translateY(4px) scale(0.97); }
+  to   { opacity: 1; transform: none; }
+}
+
 /*
-  The in-call device quick-switch (SPEC §7 Phase 2 — device management). Same rows as the Ajustes tab
-  (`.cv-settings-row`, via the shared `DevicePickers`), in a popover instead of a page — the call
-  screen already takes over the whole body, so there is no tab bar to reach Ajustes from mid-call.
-
-  Only the in-call state still uses a floating popover — before a call connects, Dispositivos is
-  inline content instead (`.cv-call-devices-inline`, above), not an overlay. Opens UPWARD (`bottom:
-  100%`): the trigger sits at the bottom of the call screen, and there is no room to open downward.
-  Anchored to `.cv-controls`'s own horizontal padding — a container whose width is bounded by ITS
-  parent, never the narrow trigger itself — the same fix CountryPicker's own popover needed (see its
-  comment).
+  The in-call DTMF keypad — the one floating popover left on the call screen. (Dispositivos was the
+  other; it is inline content now, `.cv-call-devices-inline` above, in every call state.)
+
+  Opens UPWARD (`bottom: 100%`): the trigger sits at the bottom of the call screen, and there is no
+  room to open downward. Anchored to `.cv-controls`'s own horizontal padding — a container whose width
+  is bounded by ITS parent, never the narrow trigger itself — the same fix CountryPicker's own popover
+  needed (see its comment): anchoring to a narrow, off-centre trigger let the popover's edge reach
+  `.cv-softphone`'s `overflow: hidden` and get clipped.
 */
-.cv-device-popover {
+.cv-keypad-popover {
   position: absolute;
   z-index: 20;
-  display: flex;
-  flex-direction: column;
-  gap: 0.6rem;
-  padding: 0.7rem;
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 8px;
+  padding: 0.85rem 1rem;
   background: var(--cv-surface);
   border: 1px solid var(--cv-border);
   border-radius: var(--cv-radius);
   box-shadow: var(--cv-shadow);
 }
-.cv-device-popover--above {
+.cv-keypad-popover--above {
   bottom: 100%;
   left: 1rem;
   right: 1rem;
   margin-bottom: 0.6rem;
   transform-origin: bottom center;
-  animation: cv-device-pop-in-up 0.14s cubic-bezier(0.2, 0, 0.2, 1);
-}
-@keyframes cv-device-pop-in-up {
-  from { opacity: 0; transform: translateY(4px) scale(0.97); }
-  to   { opacity: 1; transform: none; }
+  animation: cv-pop-in-up 0.14s cubic-bezier(0.2, 0, 0.2, 1);
+}
+/* `.cv-key` already carries the full key look (border, hover, active-scale, digit/letter type) from
+   the pre-call dialer — only the size needs setting here, since this grid has no flex ancestor to
+   stretch the rows the way `.cv-keypad` gets to.
+
+   A fixed HEIGHT, not an `aspect-ratio`. This popover opens upward from `.cv-controls`, so it has
+   (host height - controls block - margin) to work with, and a ratio ties its height to the host's
+   WIDTH, which says nothing about how much height there is. Found live: the CRM's real body is 310×473
+   (a 520px panel minus its 45px header), and a 1.3 ratio made this popover 285px — with the 184px
+   controls block that is 479px, so its top ~7px were clipped by `.cv-softphone`'s `overflow: hidden`.
+   48px keys give a 243px popover at ANY width, fit that host with room to spare, and stay at the
+   44-48px minimum tap target (the old ratio gave 45px keys at a 260px host, 58px at 310). */
+.cv-keypad-popover .cv-key {
+  height: 48px;
 }
 @media (prefers-reduced-motion: reduce) {
-  .cv-device-popover--above { animation: none; }
+  .cv-keypad-popover--above { animation: none; }
 }
-/* No per-row override needed here: `.cv-settings-row`/`.cv-settings-note` carry no border,
-   background or padding of their own (see the Settings tab block) — this popover's own `gap` and
-   `padding` are the only spacing in play, which is what keeps it lighter than the full Ajustes
-   page's bordered section for what is meant to be a quick, transient panel. */
 
 /* ── Lists (contacts / history) ──────────────────────────────────────────────── */
 .cv-list-head { flex-shrink: 0; padding: 0.85rem 1rem 0.5rem; }
@@ -1904,6 +1952,116 @@
 }
 .cv-settings-select:focus { outline: none; border-color: var(--cv-accent); background: var(--cv-bg); }
 .cv-settings-empty { font-size: 0.85rem; color: var(--cv-muted); }
+
+/* `--cv-danger-strong` is the AS-TEXT danger token (see its definition): red-600 on the light `--cv-bg`,
+   red-400 on the dark one. */
+.cv-settings-error { margin: 0.6rem 0.2rem 0; font-size: 0.78rem; line-height: 1.4; color: var(--cv-danger-strong); }
+
+/*
+  Ajustes as a list (custom-ringtone.md §4.6, revised 2026-10-14): each row names a setting, shows its CURRENT
+  value under the name, and opens a page. Same icon circle and dividers as the device rows above (they live in
+  the same `.cv-settings-section-body`, which supplies the padding and the dividers), same chevron as
+  `.cv-detail-row--action` — one row vocabulary across the widget.
+*/
+.cv-settings-nav {
+  display: flex;
+  align-items: center;
+  gap: 0.7rem;
+  width: 100%;
+  border: none;
+  background: none;
+  font: inherit;
+  color: inherit;
+  text-align: left;
+}
+button.cv-settings-nav { cursor: pointer; transition: background 0.12s ease; }
+button.cv-settings-nav:hover { background: var(--cv-surface); }
+button.cv-settings-nav:focus-visible { outline: 2px solid var(--cv-accent); outline-offset: -2px; }
+.cv-settings-nav-text { flex: 1; min-width: 0; display: flex; flex-direction: column; gap: 0.1rem; }
+.cv-settings-nav-title { font-size: 0.88rem; font-weight: 600; color: var(--cv-text); }
+/* One line, cut with an ellipsis — the full device name is on its page. `--cv-muted` on `--cv-bg` is the
+   pairing already verified for `.cv-settings-note`. The static row (a note, no page) may wrap instead. */
+.cv-settings-nav-value {
+  font-size: 0.8rem;
+  color: var(--cv-muted);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.cv-settings-nav--static .cv-settings-nav-value { white-space: normal; line-height: 1.45; }
+.cv-settings-nav-chevron { flex-shrink: 0; color: var(--cv-muted); }
+
+/* A settings page: the `.cv-detail` overlay (entrance, back button, reduced motion all inherited) with a
+   scrolling body of its own. */
+.cv-settings-page-body { flex: 1; min-height: 0; overflow-y: auto; padding: 0.25rem 1rem 1rem; }
+.cv-settings-page-title {
+  margin: 0.15rem 0.2rem 0.35rem;
+  font-size: 1.05rem;
+  font-weight: 700;
+  letter-spacing: -0.01em;
+  color: var(--cv-text);
+}
+/* Focus lands here on open (for keyboard and screen-reader users); a ring on a heading would only look
+   like a stray box to everyone else. */
+.cv-settings-page-title:focus { outline: none; }
+.cv-settings-page-intro { margin: 0 0.2rem 0.85rem; font-size: 0.8rem; line-height: 1.45; color: var(--cv-muted); }
+.cv-settings-page-empty { margin: 0; padding: 0 0.2rem; font-size: 0.85rem; color: var(--cv-muted); }
+
+/* The checkmark list: one card like `.cv-settings-section-body`, a row per choice. */
+.cv-choices {
+  border: 1px solid var(--cv-border);
+  border-radius: 14px;
+  background: var(--cv-bg);
+  overflow: hidden;
+}
+.cv-choice {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+  min-height: 44px;
+  padding: 0.6rem 0.85rem;
+  cursor: pointer;
+  transition: background 0.12s ease;
+}
+.cv-choice + .cv-choice { border-top: 1px solid var(--cv-border); }
+.cv-choice:hover { background: var(--cv-surface); }
+/* The real control: a native radio, kept in the accessibility tree and keyboard order, drawn by the row. */
+.cv-choice-input {
+  position: absolute;
+  opacity: 0;
+  width: 1px;
+  height: 1px;
+  margin: 0;
+  pointer-events: none;
+}
+.cv-choice:has(.cv-choice-input:focus-visible) { outline: 2px solid var(--cv-accent); outline-offset: -2px; }
+.cv-choice-text { flex: 1; min-width: 0; display: flex; flex-direction: column; gap: 0.1rem; }
+.cv-choice-label { font-size: 0.88rem; color: var(--cv-text); overflow-wrap: anywhere; }
+.cv-choice-sub { font-size: 0.78rem; color: var(--cv-muted); }
+.cv-choice[data-checked] .cv-choice-label { font-weight: 600; }
+.cv-choice-check { flex-shrink: 0; color: var(--cv-accent-strong); visibility: hidden; }
+.cv-choice[data-checked] .cv-choice-check { visibility: visible; }
+.cv-choice-playing { display: inline-flex; flex-shrink: 0; color: var(--cv-accent-strong); }
+
+.cv-settings-test,
+.cv-settings-retry {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4rem;
+}
+.cv-settings-test { margin-top: 0.85rem; }
+.cv-settings-retry { margin-top: 0.6rem; }
+
+/* Visually hidden, still read aloud. */
+.cv-sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
 /* `--cv-muted` on `--cv-bg` — 4.83:1 light / 6.97:1 dark, computed fresh for THIS pairing (the note
    used to sit on `--cv-surface` with its own card; now it sits directly on the section's `--cv-bg`,
    a different background that earns its own check rather than inheriting the old one's number). */
@@ -1913,18 +2071,6 @@
   font-size: 0.8rem;
   line-height: 1.5;
 }
-/* Closing note for the tab as a whole, not any one section — sits directly on `.cv-settings-body`,
-   which shares the same `--cv-bg` as `.cv-settings-section-body` above, so the `--cv-muted`-on-
-   `--cv-bg` pairing already verified for `.cv-settings-note` carries over unchanged. Centred and
-   quieter than a row: this is a footnote about the tab, not a row's worth of content. */
-.cv-settings-more {
-  margin: 0;
-  padding: 0 0.5rem;
-  text-align: center;
-  color: var(--cv-muted);
-  font-size: 0.78rem;
-  line-height: 1.5;
-}
 
 /* ── Centred states (mic gate) ───────────────────────────────────────────────── */
 .cv-center {